Essencialista Admin

Qual pacote usar?

Escolha pela camada — OpenAPI gerada, helpers de domínio ou extensão Go.

Passo 1
API REST completa
@mira/commerce-client-sdk — 65+ ops geradas da OpenAPI SSOT.
Ver instalação
Passo 2
Checkout headless
@mira/commerce-checkout-sdk — sessão, patch e place-order tipados.
Guia checkout
Passo 3
Protótipo / app Mirá
lib/commerce-client/ — facade live com auth bridge e tipos de domínio.
Ver facade

Catálogo de pacotes

SSOT humano: docs/sdk-wiring.md · Versão alinhada à OpenAPI 0.3.0.

Pacote	Público	Estado	Quando usar
@mira/commerce-client-sdk	Integradores + core	Gerado (65+ ops)	Qualquer chamada REST — scripts, BFF, apps cliente
@mira/commerce-checkout-sdk	Parceiros checkout	Helpers Fase 3b	Fluxo sessions — ver headless-checkout
@mira/commerce-ui	Clientes B2C	Scaffold Fase 6	Shells platform/member reutilizáveis (extract incremental)
commerce-ext (Go)	Plugins / client template	Fase 2b+	Hooks, manifest, verify — ver extensibility
lib/commerce-client/	App Next.js deste repo	Live 100%	Preferir em app/ — não publicar como pacote npm

Arquitetura

Fluxo de dados

┌─────────────┐     ┌──────────────────────┐     ┌─────────────────────────┐
│  app/ UI    │────▶│ lib/commerce-client/ │────▶│ @mira/commerce-client-  │
│  (Next.js)  │     │ facade (live)        │     │ sdk (gerado OpenAPI)    │
└─────────────┘     └──────────────────────┘     └───────────┬─────────────┘
                                                               │
                    ┌──────────────────────┐                   │
                    │ @mira/commerce-      │◀──────────────────┘
                    │ checkout-sdk         │   (integradores headless)
                    └──────────────────────┘
                                                               ▼
                                                    GET/POST /api/commerce/v1/*  (browser demo)
                                                               │
                                                    POST/GET /commerce-api/v1/*  (integrador)
                                                               ▼
                                                    cmd/api (Go) → Postgres

Dev local: middleware + rewrite /commerce-api/* → localhost:8080. Produção demo: BFF /api/commerce/v1 — ver docs/deploy-ovh.md.

Instalação

Monorepo core: workspace packages. Repo cliente (Fase 4): GitHub Packages — ADR 0008.

Monorepo (este repo)

// package.json raiz já resolve workspace:*
import { createCommerceClient, listProducts } from "@mira/commerce-client-sdk"
import { createCheckoutSession } from "@mira/commerce-checkout-sdk"

Repo cliente (futuro publish)

npm install @mira/[email protected]
npm install @mira/[email protected]   # checkout headless
npm install @mira/[email protected]             # opcional — shells UI

packages/commerce-client-sdk/
Cliente TS gerado (@hey-api/openapi-ts)
packages/commerce-checkout-sdk/
Helpers checkout sobre o client SDK
packages/commerce-ui/
Scaffold UI — Fase 6
templates/mira-commerce-client-template/
Manifest + verify CI cliente

Cliente base — createCommerceClient

Server-side (integrador / BFF)

import { createCommerceClient, listProducts, resolvePrice } from "@mira/commerce-client-sdk"

const client = createCommerceClient({
  baseUrl: process.env.COMMERCE_API_URL, // ex.: https://demo.mira-dev.tech/commerce-api/v1
  token: process.env.MC_API_TOKEN,       // mc_live_… — nunca no browser
})

const { data: products } = await listProducts({
  client,
  query: { member_id: "550e8400-…", limit: 20 },
})

const { data: price } = await resolvePrice({
  client,
  query: { sku_id: "…", member_id: "…", channel: "web" },
})

Browser via proxy (protótipo Mirá)

import { createCommerceClient } from "@mira/commerce-client-sdk"

// baseUrl browser demo: /api/commerce/v1 (BFF — Bearer server-side)
// Dev local: middleware injecta token em /commerce-api/*
const client = createCommerceClient({ token: sessionBearer })

// Preferir facade em app/:
import { getProducts, getOrders } from "@/lib/commerce-client"

Opção	baseUrl	Auth
Integrador server-side	URL absoluta da API	Bearer mc_live_… (env)
Protótipo Next.js (demo)	/api/commerce/v1	BFF — cookies ou storefront bearer
Dev local Mac	/commerce-api/v1	middleware → dev tokens
Checkout comprador	qualquer	X-Checkout-Session-Token (cks_tok_…)
Conta comprador	qualquer	Bearer mc_sess_… (pós magic link)

Checkout SDK (@mira/commerce-checkout-sdk)

Sessão → place-order

import { createCommerceClient } from "@mira/commerce-client-sdk"
import {
  createCheckoutSession,
  patchCheckoutSession,
  placeCheckoutOrder,
} from "@mira/commerce-checkout-sdk"

const client = createCommerceClient({ baseUrl, token: integratorToken })

const session = await createCheckoutSession(client, {
  memberId: "550e8400-…",
  warehouseId: "660e8400-…",
  channel: "web",
  state: { items: [{ sku_id: "…", qty: 2 }] },
})

await patchCheckoutSession(client, session.id, session.sessionToken, {
  delivery: { mode: "pickup", slot_id: "…" },
})

const order = await placeCheckoutOrder(client, {
  sessionId: session.id,
  sessionToken: session.sessionToken,
  idempotencyKey: crypto.randomUUID(),
})

Guia completo com erros HTTP, anti-fraude e padrão BFF: Checkout headless

Facade lib/commerce-client/

Aspecto	Facade	SDK direto
Import em app/	import { getOrders } from '@/lib/commerce-client'	Evitar — sem auth bridge
Tipos de domínio	Re-export de lib/types.ts + mapeamento	types.gen.ts (OpenAPI)
Handlers	lib/commerce-client/domains/live/*.ts	Funções geradas listX, createX…
Modo API	Sempre live (sem mock fallback)	N/A

// lib/commerce-client/index.ts — ponto único para UI
import { getOrders, createOrder, testErpConnection } from "@/lib/commerce-client"

if (isLiveMode()) { /* sempre true */ }

Domínios cobertos (client SDK)

Domínio	Exemplos gerados	Guia domínio
Catálogo	listProducts, listServices, getCatalogSpecifications	—
Pedidos	listOrders, createOrder, submitOrder, initiateOrderPayment	headless-checkout
Checkout sessions	createCheckoutSession, patchCheckoutSession, placeCheckoutOrder	headless-checkout
Preços / promo	listPrices, resolvePrice, listPromotions, listCoupons	—
ERP	createErpConnection, testErpConnection, generateErpMappings	erp-integration
Auth staff/customer	requestStaffMagicLink, verifyCustomerMagicLink, getCustomerMe	—
Tokens / RBAC	listApiTokens, createApiToken, rotateApiToken	api-access-policies.md
Analytics	analyticsAsk, executeAnalyticsReport	—
Dev / MCP	getDeveloperOps, tryMcpTool	mcp-tools.md

Lista completa: packages/commerce-client-sdk/src/generated/sdk.gen.ts · Explorer: /docs/apis

Regenerar e validar

Comando	Quando
npm run sdk:generate	Após alterar as fontes em services/api/openapi/src/
npm run sdk:check	CI — regen + falha se drift em src/generated/
npm run spec:refresh	Sync public/openapi + regen SDK + explorer
npm run spec:validate	Gate completo antes de PR — inclui sdk:check

Fluxo após mudança OpenAPI

1. Editar as fontes em services/api/openapi/src/ (paths/<tag>/, schemas/)
2. npm run spec:refresh          # ou openapi:sync + sdk:generate
3. Ajustar lib/commerce-client/domains/live/ se novos paths
4. npm run spec:validate         # deve ficar verde
5. Commit packages/commerce-client-sdk/src/generated/ junto com as fontes do spec

Auth em dev local

Sessão UI (mock-session)	Bearer injectado	Escopo
platform	mc_live_dev_platform_001	Tenant platform — admin
member	mc_live_dev_member_001	Tenant member — lojista

Pré-requisito: API Go em execução (go run ./cmd/api) · WireGuard se Postgres OVH.

Princípios

OpenAPI → SDK

Nunca editar src/generated/ à mão — sempre regenerar a partir da spec.

Verificação: sdk:check

Secrets server-side

mc_live_… e mc_sess_… só em BFF ou backend — nunca expor no bundle browser.

Verificação: api-access-policies.md

UI usa facade

app/ importa lib/commerce-client — não o pacote gerado diretamente.

Verificação: module-boundaries.md

Anti-patterns

Evitar	Preferir
Fetch manual sem SDK	Funções geradas — tipos e paths alinhados à spec
Editar sdk.gen.ts	npm run sdk:generate + commit generated/
mc_live_… no React client	BFF proxy com token server-side
Duplicar helpers checkout	@mira/commerce-checkout-sdk
Import SDK em plugin Go	commerce-ext — hooks e manifest YAML

SSOT e guias relacionados

docs/sdk-wiring.md
Documento canónico wiring protótipo → SDK
services/api/openapi/src/
Contrato REST — fontes da geração (o spec.yaml é gerado)
docs/headless-checkout.md
Checkout headless — parceiros
docs/erp-integration.md
ERP — wizard e mapeamentos
docs/fase-4-client-template.md
Template repo cliente
docs/fase-6-commerce-ui.md
Roadmap @mira/commerce-ui
docs/adr/0008-registry-github-packages.md
Decisão publish npm GitHub Packages

Checkout headless Integração ERP API Explorer