@mira-arandu/commerce-client-sdk 0.0.0-stage → 47.20.3

package/README.md

@@ -1,3 +1,407 @@
-# Temporary Holding Version
+# @mira-dev-tech/commerce-client-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cliente TypeScript da API aranduOS, gerado do contrato OpenAPI
+(`services/api/openapi/spec.yaml`). Tipos, funções e erros vêm todos do
+contrato — cada versão do SDK corresponde a um contrato publicado.
+
+```bash
+npm i @mira-dev-tech/commerce-client-sdk@npm:@mira-arandu/commerce-client-sdk
+```
+
+Não precisa de `.npmrc` nem de token. No npm público o pacote chama-se
+`@mira-arandu/commerce-client-sdk`; o apelido acima instala-o com o nome
+`@mira-dev-tech/commerce-client-sdk`, que é o dos imports desta página. No
+`package.json` fica
+`"@mira-dev-tech/commerce-client-sdk": "npm:@mira-arandu/commerce-client-sdk@<versão>"`.
+No GitHub Packages o nome é `@mira-dev-tech/commerce-client-sdk`, sem apelido.
+
+## Começar
+
+```ts
+import { createCommerceClient, listProducts } from "@mira-dev-tech/commerce-client-sdk"
+
+const client = createCommerceClient({
+  baseUrl: "https://api.mira-dev.tech/v1",
+  token: process.env.COMMERCE_TOKEN,   // servidor apenas
+  memberId: process.env.MEMBER_ID,     // enviado como X-Tenant-ID
+})
+
+const { data } = await listProducts({ client })
+```
+
+O `memberId` identifica o tenant e vai sozinho no header `X-Tenant-ID` — não o
+adicione à mão.
+
+## Superfície da vitrine (`/storefront-api`)
+
+O pacote full re-exporta **todas** as operações da API (admin, POS, ERP, …).
+Uma vitrine deve importar o subpath `/storefront-api`, que traz num import só o
+que um site precisa — **não** é um segundo codegen:
+
+```ts
+import {
+  createCommerceClient,
+  listStorefrontProducts,
+  composeCheckout,
+  getRentalAvailabilityCalendar,
+  requestCustomerMagicLink,
+  customerListAppointments,
+  listAvailableScheduleSlots,
+  groupAvailableSlotsByDay,
+} from "@mira-dev-tech/commerce-client-sdk/storefront-api"
+```
+
+O que está lá:
+
+- as operações das tags `storefront`, `checkout`, `booking` e `customers` (#1469),
+  sem os writes de staff que partilham essas tags (frota, CRM, heuristics);
+- **toda a operação do cliente final**: login, conta, pedidos, assinaturas,
+  marcações, documentos e solicitações. Entra sozinha, pelo contrato (#4319);
+- o que o site chama sem login: catálogo, horários livres, frete, pagamento,
+  link de pagamento, formulários (`sdkOperationIds` em `storefront-surface.yaml`);
+- os tipos do contrato e as funções prontas abaixo.
+
+**A garantia:** o que um site alcança está neste pacote. Operação pública, ou que
+o bearer do BFF alcança, fora do pacote e sem motivo declarado reprova o CI
+(Garantia 6, `tests/bff/storefront-sdk-surface.test.ts`). Se faltar algo aqui, é
+defeito: abra uma issue.
+
+Exportar a função não abre rota. Quem decide o acesso é o proxy e o RBAC, e a
+[`storefront-bff-allowlist.json`](../../public/openapi/storefront-bff-allowlist.json)
+é um conjunto menor: não leva a sessão do comprador.
+
+Checkout com `throwOnError` e interceptor de sessão continua em
+`@mira/commerce-checkout-sdk`. Storefronts actuais podem ficar no pacote full
+até migrar.
+
+### Agenda e documentos do cliente
+
+```ts
+const { data } = await listAvailableScheduleSlots({
+  client,
+  query: { warehouse_id: unidadeId, product_id: servicoId },
+})
+// O fuso é o da empresa: no do visitante, um horário às 23h podia mudar de dia.
+const dias = groupAvailableSlotsByDay(data?.data ?? [], "America/Sao_Paulo")
+
+const { error } = await customerRescheduleAppointment({
+  client,
+  path: { slot_id: marcacao.id },
+  body: { scheduled_for: novoHorario },
+})
+const recusa = appointmentChangeRefusal(error)
+if (recusa?.team_request) {
+  // Fora da regra da empresa: ofereça falar com a equipe, com a mensagem do cliente.
+  const body = teamRequestCaseBody(recusa, { submissionId: crypto.randomUUID(), message })
+  if (body) await customerOpenCase({ client, body })
+}
+```
+
+Também: `appointmentIsAwaitingPayment` (horário reservado à espera do pagamento),
+`cancelRefundLabel` (o que acontece com o valor pago), `customerDocumentIsNew` e
+`formatDocumentSize`. O documento baixa-se com `customerDownloadDocument`, que
+devolve uma URL assinada de 5 minutos: peça de novo a cada download.
+
+> **O token é de servidor.** Ele vale por todo o tenant: exposto no browser, dá
+> acesso a pedidos com dados pessoais dos seus clientes. Chame a API do seu
+> backend ou de um BFF, nunca de código entregue ao navegador.
+
+## Mídia de produto / SKU (PDP + stories, otimizado para web)
+
+Imagem e vídeo podem viver no **produto pai** e/ou na **SKU** (filho). A PDP
+consolida isso em `variants[].effective_media` (media da SKU se não vazia,
+senão do pai). Cada item tem `role`: `gallery` (carrossel) ou `story` (9:16 /
+shorts). Imagens trazem `variants[]` (imagor / ADR 0125) para `srcset`.
+
+Helpers no SDK — use-os em vez de montar URLs à mão:
+
+```ts
+import {
+  createCommerceClient,
+  getStorefrontProductDetail,
+  buildPdpWebMedia,
+  plpCoverWebMedia,
+} from "@mira-dev-tech/commerce-client-sdk"
+
+const client = createCommerceClient({ baseUrl, token, memberId })
+const { data: pdp } = await getStorefrontProductDetail({
+  client,
+  path: { slug_or_id: "meu-produto" },
+})
+
+// Variante seleccionada (SKU ou product_id do filho)
+const { gallery, stories, cover } = buildPdpWebMedia(pdp!, selectedSku)
+
+// Galeria — srcset + sizes prontos para <img> / next/image
+gallery.map((m) => (
+  <img
+    key={m.key}
+    src={m.src}
+    srcSet={m.srcSet}
+    sizes={m.sizes}
+    alt={m.alt}
+    width={m.width}
+    height={m.height}
+    style={{ aspectRatio: m.aspectRatio }}
+  />
+))
+
+// Stories / live commerce — rail vertical
+stories.map((m) =>
+  m.kind === "video" ? (
+    <video
+      key={m.key}
+      src={m.src}
+      poster={m.poster}
+      style={{ aspectRatio: m.aspectRatio }}
+      muted
+      playsInline
+      preload="metadata"
+    />
+  ) : (
+    <img key={m.key} src={m.src} srcSet={m.srcSet} alt={m.alt} style={{ aspectRatio: m.aspectRatio }} />
+  ),
+)
+
+// PLP thumb
+const thumb = plpCoverWebMedia(product)
+```
+
+Também disponíveis: `resolveEffectiveMedia`, `resolveEffectiveMediaFromPdp`,
+`galleryMedia` / `storyMedia`, `toWebProductMedia` / `toWebProductMediaList`.
+
+Upload (admin/BFF): `uploadProductMedia` com multipart `file` + opcional
+`role`, `poster`, `duration_ms` — `product_id` do pai **ou** do filho.
+
+## Storefront helpers (ciclo PLP → PDP → checkout)
+
+O SDK inclui helpers **sem I/O** (excepto `fetchWithEtag`) para não reimplementar
+regras no storefront:
+
+| Área | API |
+|------|-----|
+| Variantes | `createVariantPicker(pdp)` — eixos → SKU, preço, stock, mídia |
+| PLP | `toPlpCardView(card)` — `priceLabel`, cover, rental |
+| Locação | `rentalFromPrice`, `formatRentalFromLabel` |
+| Dinheiro | `formatMoney`, `formatPriceRange`, `formatInstallments` |
+| Cache | `fetchWithEtag` / `createEtagMemoryCache` (`If-None-Match` / 304) |
+| Documento | `normalizeDocument`, `isValidCPF` / `isValidCNPJ`, `validateDocument` |
+| CEP | `normalizeZip`, `addressFromZipLookup` (campos locked) |
+| Frete | `ShippingQuoteSession` — trocar CEP invalida cotação |
+| Pagamento | `paymentMethodLabel`, `pixPendingFromResponse`, `pixPollIntervalMs` |
+| Wishlist | `isInWishlist`, `normalizeWishlistCreate` |
+| Carrinho | `normalizeCartLines`, `cartLinesSubtotal` |
+| Experiences | `sortExperienceBlocks`, `resolvedExperienceBlocks` |
+| Erros | `apiErrorMessage`, `isStockConflictError` |
+
+```ts
+import {
+  createVariantPicker,
+  toPlpCardView,
+  fetchWithEtag,
+  ShippingQuoteSession,
+  normalizeDocument,
+  validateDocument,
+} from "@mira-dev-tech/commerce-client-sdk"
+
+const picker = createVariantPicker(pdp!)
+const resolved = picker.resolve({ Cor: "PRETO", Tamanho: "M" })
+if (resolved.complete && resolved.inStock) {
+  // add to cart: resolved.variant.sku + resolved.gallery
+}
+
+const cards = plp.data.map(toPlpCardView)
+
+const ship = new ShippingQuoteSession()
+ship.setZip(cep)
+// após resolveShippingQuotes:
+ship.applyResult(quotes, cep)
+```
+
+Checkout headless completo (sessão/compose/place-order) continua em
+`@mira/commerce-checkout-sdk` — este pacote não duplica esse fluxo.
+
+## Mudanças que afetam integrações
+
+### CNPJ alfanumérico (em emissão desde 31/07/2026)
+
+O CNPJ passou a ter **12 posições alfanuméricas + 2 dígitos verificadores
+numéricos** (IN RFB 2.229). O tipo de `document_number` continua `string`; o que
+muda é o tratamento:
+
+```ts
+// ERRADO — descarta as letras e produz outro documento
+const doc = input.replace(/\D/g, "")
+
+// CERTO — remove só pontuação, preserva letras, MAIÚSCULAS
+const doc = input.toUpperCase().replace(/[^0-9A-Z]/g, "")
+```
+
+Validação com `^\d{14}$` rejeita toda empresa aberta a partir dessa data. A API
+confere o dígito verificador (módulo 11 com valor `ASCII-48`) e recusa documento
+inválido — inclusive os numéricos com DV errado que passavam antes.
+
+### Endereço de entrega é conferido contra o CEP
+
+O frete é cotado a partir do CEP, então um endereço incoerente com ele (CEP de
+uma zona, cidade de outra) é recusado com **422**.
+
+Busque o endereço oficial e deixe o comprador preencher **apenas número e
+complemento**:
+
+```ts
+import { getAddressByZip } from "@mira-dev-tech/commerce-client-sdk"
+
+const { data } = await getAddressByZip({ client, query: { zip: "01310-100" } })
+// data.street / data.neighborhood / data.city / data.state → campos bloqueados
+```
+
+`404` significa "não foi possível resolver o CEP agora" (inexistente, ou o
+provedor externo fora do ar), não "CEP inválido". É raro — a base se preenche
+sozinha na primeira consulta de cada CEP — e nesse caso deixe preencher à mão:
+o pedido não é bloqueado por isso.
+
+**Trocar o CEP invalida a cotação.** Recote com `resolveShippingQuotes` e
+descarte o método anterior: um `shipping_method_id` cotado para outro CEP dá um
+preço que a API não aceita.
+
+### O pedido guarda um snapshot do comprador
+
+`order.customer_snapshot` traz nome, email, WhatsApp e documento **como estavam
+no momento da compra**. Use-o em nota fiscal e pós-venda em vez de reconsultar o
+cadastro, que muda com o tempo.
+
+## Erros
+
+As funções devolvem `{ data, error }` — status HTTP não lança exceção:
+
+```ts
+const { data, error, response } = await createOrder({ client, body })
+if (error) {
+  if (response.status === 422) {
+    // regra de negócio: endereço incoerente com o CEP, estoque insuficiente, …
+  }
+  return
+}
+```
+
+## Versões e notificações
+
+Versionamento semântico, uma versão por contrato publicado:
+
+- **patch** — correção sem mudar contrato
+- **minor** — campos ou operações novas, retrocompatíveis
+- **major** — mudança que quebra, sempre com nota de migração no release
+
+Para ser avisado de cada versão, no repositório
+[mira-dev-tech/mira-commerce-core](https://github.com/mira-dev-tech/mira-commerce-core)
+use **Watch → Custom → Releases**. Toda publicação nasce de um GitHub Release
+com o changelog — as do SDK usam tags `sdk-vX.Y.Z`.
+
+Pré-releases saem na dist-tag `next`
+(`npm i @mira-dev-tech/commerce-client-sdk@npm:@mira-arandu/commerce-client-sdk@next`)
+e nunca viram o `latest`.
+
+O pacote é publicado já compilado (JS + `.d.ts`), então funciona tanto com
+bundler quanto em Node puro.
+
+## Referência
+
+- Catálogo de operações da API em execução: <https://api.mira-dev.tech/mcp/catalog>
+- Contrato OpenAPI: `public/openapi/mira-commerce.openapi.yaml`
+- Analytics, comissões e returns: [`docs/sdk-wiring.md`](../../docs/sdk-wiring.md)
+
+### Analytics (Mira dataLayer + GTM/GA4)
+
+```ts
+import { createMiraAnalytics } from "@mira-dev-tech/commerce-client-sdk"
+
+const analytics = createMiraAnalytics({ gtmId: "GTM-XXXX", gaMeasurementId: "G-XXXX" })
+analytics.setConsent({ analytics: true })
+analytics.viewItem({ currency: "BRL", items: [{ item_id: "SKU-1" }] })
+analytics.viewItemList({ item_list_id: "catalog", item_list_name: "Catálogo", items })
+// Loja sem checkout (venda por WhatsApp): o lead é a conversão
+analytics.generateLead({ currency: "BRL", value: 99 }, { lead_source: "whatsapp", placement: "pdp" })
+```
+
+Guia: [`docs/storefront-analytics.md`](../../docs/storefront-analytics.md) · ADR 0067.
+
+### Primeiro toque da sessão no pedido — ADR 0198 C4
+
+O core guarda o primeiro toque da sessão em `core.order_attribution` e nunca o
+reescreve, mas só o browser sabe por onde a pessoa chegou. Duas linhas:
+
+```ts
+import { captureFirstTouch, firstTouchMarketingData } from "@mira-dev-tech/commerce-client-sdk"
+
+captureFirstTouch() // em TODO o carregamento de página (layout/root)
+
+// ao gravar a sessão de checkout, junto com a UTM do último toque que a loja já envia:
+marketing_data: { ...lastTouchUtm, ...firstTouchMarketingData() }
+```
+
+- Grava UTM (`source`/`medium`/`campaign`/`content`/`term`), `gclid` e
+  `first_touch_at` (RFC3339) **uma vez**, na primeira visita conhecida — uma
+  primeira visita directa também conta, e a campanha posterior não vira a
+  descoberta.
+- `touch_count` só cresce quando chega UTM/gclid **novo** (recarregar a mesma
+  URL não conta).
+- `anon_id` é o `mira_anon_id` do `localStorage` — o mesmo token do header
+  `X-Mira-Anon` de `/events/track` (`core.web_events`). Para o header, usar
+  `getOrCreateAnonId()` em vez de gerar outro id.
+- Chave desconhecida é **omitida**, nunca string vazia; sem storage (SSR, modo
+  privado) devolve `{}` sem lançar.
+
+### Carrinho dual-write (session + local) — ADR 0142
+
+Sessões de checkout expiram (~30 min). O helper `createCartStore` grava linhas
+cotadas na sessão **e** num snapshot local; na leitura reidrata a sessão se
+estiver vazia. Tokens (`cks_tok`) **nunca** vão para o storage do browser.
+
+```ts
+import { createCartStore } from "@mira/commerce-client-sdk"
+
+const cart = createCartStore({
+  storageKey: "loja-cart-v1",
+  ensureSession: () => ensureCheckoutSession(),
+  getSessionState: () => fetchCheckoutSessionState(),
+  patchSessionState: (partial) => patchCheckoutSessionState(partial),
+})
+
+await cart.write({ lines: [{ sku: "SKU-1", qty: 1 }], updatedAt: new Date().toISOString() })
+const current = await cart.read()
+```
+
+Forma recomendada de `state.cart`: `{ lines, updatedAt }` (array legado ainda
+aceite no core). Detalhe: [`docs/adr/0142-storefront-cart-dual-write.md`](../../docs/adr/0142-storefront-cart-dual-write.md)
+· também em `@mira/commerce-checkout-sdk`.
+
+### Dinheiro em centavos (ADR 0151)
+
+Quote, compose, card da PLP e `rental_meta` devolvem o major (reais, deprecated)
+e o irmão `*_cents`. Na vitrine, preferir os centavos:
+
+```ts
+import { formatMoneyFromCents } from "@mira-dev-tech/commerce-client-sdk"
+
+formatMoneyFromCents(16990) // "R$ 169,90"
+```
+
+## Desenvolvimento (interno)
+
+```bash
+npm run sdk:generate                              # regenera src/generated do spec
+npm run build --workspace=@mira/commerce-client-sdk   # dist JS + .d.ts (o que é publicado)
+```
+
+No repositório o `package.json` aponta para `src/` — é o que o monorepo consome
+via workspace, sem passo de build. O workflow de publicação reescreve
+`main`/`types`/`exports` para `dist/` no tarball.
+
+Não editar `src/generated/` à mão. No monorepo, preferir a facade
+[`lib/commerce-client/`](../../lib/commerce-client/), que roteia mock vs live via
+`NEXT_PUBLIC_COMMERCE_API_MODE`.
+
+Publicação: `.github/workflows/publish-commerce-sdk.yml` (npm público e GitHub
+Packages, disparado por GitHub Release). ADR 0008 · runbook em
+[`docs/ops/sdk-publish.md`](../../docs/ops/sdk-publish.md).

package/dist/address.d.ts

@@ -0,0 +1,27 @@
+/** CEP só dígitos (8). */
+export declare function normalizeZip(raw: string): string;
+export declare function isValidZip(raw: string): boolean;
+export declare function formatZip(raw: string): string;
+/** Subconjunto típico de `getAddressByZip`. */
+export type ZipLookupAddress = {
+    zip?: string;
+    street?: string;
+    neighborhood?: string;
+    city?: string;
+    state?: string;
+};
+export type AddressFill = {
+    zip: string;
+    street: string;
+    neighborhood: string;
+    city: string;
+    state: string;
+    /** Campos que o comprador não deve editar (preenchidos pelo CEP). */
+    lockedFields: Array<"street" | "neighborhood" | "city" | "state" | "zip">;
+};
+/**
+ * Monta formulário de entrega a partir do lookup de CEP.
+ * Comprador preenche só número/complemento.
+ */
+export declare function addressFromZipLookup(data: ZipLookupAddress): AddressFill;
+//# sourceMappingURL=address.d.ts.map

package/dist/address.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.d.ts","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAI7C;AAED,+CAA+C;AAC/C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,YAAY,EAAE,MAAM,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,YAAY,EAAE,KAAK,CAAC,QAAQ,GAAG,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,KAAK,CAAC,CAAA;CAC1E,CAAA;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CAUxE"}

package/dist/address.js

@@ -0,0 +1,29 @@
+/** CEP só dígitos (8). */
+export function normalizeZip(raw) {
+    return raw.replace(/\D/g, "").slice(0, 8);
+}
+export function isValidZip(raw) {
+    return /^\d{8}$/.test(normalizeZip(raw));
+}
+export function formatZip(raw) {
+    const z = normalizeZip(raw);
+    if (z.length !== 8)
+        return z;
+    return `${z.slice(0, 5)}-${z.slice(5)}`;
+}
+/**
+ * Monta formulário de entrega a partir do lookup de CEP.
+ * Comprador preenche só número/complemento.
+ */
+export function addressFromZipLookup(data) {
+    const zip = normalizeZip(data.zip ?? "");
+    return {
+        zip,
+        street: data.street ?? "",
+        neighborhood: data.neighborhood ?? "",
+        city: data.city ?? "",
+        state: data.state ?? "",
+        lockedFields: ["street", "neighborhood", "city", "state", "zip"],
+    };
+}
+//# sourceMappingURL=address.js.map

package/dist/address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"address.js","sourceRoot":"","sources":["../src/address.ts"],"names":[],"mappings":"AAAA,0BAA0B;AAC1B,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,OAAO,SAAS,CAAC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,MAAM,CAAC,GAAG,YAAY,CAAC,GAAG,CAAC,CAAA;IAC3B,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,CAAA;IAC5B,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;AACzC,CAAC;AAqBD;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAsB;IACzD,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,CAAA;IACxC,OAAO;QACL,GAAG;QACH,MAAM,EAAE,IAAI,CAAC,MAAM,IAAI,EAAE;QACzB,YAAY,EAAE,IAAI,CAAC,YAAY,IAAI,EAAE;QACrC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,EAAE;QACvB,YAAY,EAAE,CAAC,QAAQ,EAAE,cAAc,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC;KACjE,CAAA;AACH,CAAC"}

package/dist/analytics/cdp.d.ts

@@ -0,0 +1,14 @@
+import type { MiraCdpBridgeOptions, MiraDataLayerEvent } from "./types.js";
+export declare function toCdpEvents(event: MiraDataLayerEvent): Array<{
+    type: string;
+    ref?: string;
+}>;
+/**
+ * Fire-and-forget; falhas (401 anónimo, etc.) são ignoradas.
+ *
+ * Sem sessão de cliente, `/events/track` só grava o evento quando chega o
+ * `X-Mira-Anon` — sem ele responde 202 e descarta, e o funil anónimo (a maior
+ * parte do tráfego) ficava vazio.
+ */
+export declare function sendToCdp(opts: MiraCdpBridgeOptions, event: MiraDataLayerEvent): Promise<void>;
+//# sourceMappingURL=cdp.d.ts.map

package/dist/analytics/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../src/analytics/cdp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,kBAAkB,EAAiB,MAAM,SAAS,CAAA;AAatF,wBAAgB,WAAW,CACzB,KAAK,EAAE,kBAAkB,GACxB,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA2BvC;AA+BD;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,oBAAoB,EAC1B,KAAK,EAAE,kBAAkB,GACxB,OAAO,CAAC,IAAI,CAAC,CAgBf"}

package/dist/analytics/cdp.js

@@ -0,0 +1,94 @@
+/** Allowlist do backend (`internal/events/track.go`). */
+const CDP_TYPE = {
+    page_view: "page_view",
+    view_item: "product_view",
+    add_to_cart: "add_to_cart",
+    begin_checkout: "checkout_step",
+    checkout_step: "checkout_step",
+    // view_item_list / select_item / purchase / generate_lead: fora do allowlist
+    // CDP — não enviar (o core responderia 202 e descartaria)
+};
+export function toCdpEvents(event) {
+    const type = CDP_TYPE[event.event];
+    if (!type)
+        return [];
+    if (event.event === "page_view") {
+        return [{ type }];
+    }
+    if (event.event === "checkout_step" || event.event === "begin_checkout") {
+        const step = event.ecommerce?.checkout_step;
+        const ref = step != null
+            ? String(step).slice(0, 120)
+            : event.event === "begin_checkout"
+                ? "begin"
+                : undefined;
+        return [{ type, ...(ref ? { ref } : {}) }];
+    }
+    const items = event.ecommerce?.items ?? [];
+    if (items.length === 0) {
+        return [{ type }];
+    }
+    return items.map((item) => ({
+        type,
+        ref: String(item.item_id).slice(0, 120),
+    }));
+}
+/**
+ * Chave do token anónimo no `localStorage` e header que o leva ao core. É o
+ * MESMO token do `anon_id` do `marketing_data` (ADR 0198 C4, #2345) — um
+ * segundo identificador partiria a costura entre o funil (`core.web_events`) e
+ * o pedido (`core.order_attribution`).
+ *
+ * Leitura mínima de propósito: quem CRIA o token é o `getOrCreateAnonId` da
+ * captura do primeiro toque (PR #2368), que substitui este leitor quando
+ * entrar. Aqui só se lê — o bridge não inventa um id que a atribuição do
+ * pedido não conheça.
+ */
+const ANON_STORAGE_KEY = "mira_anon_id";
+const ANON_HEADER = "X-Mira-Anon";
+/** Tecto do core (`internal/events/track.go`). */
+const MAX_ANON_LEN = 64;
+function readAnonId(opts) {
+    try {
+        const explicit = typeof opts.anonId === "function" ? opts.anonId() : opts.anonId;
+        if (explicit !== undefined)
+            return explicit.trim().slice(0, MAX_ANON_LEN);
+        if (typeof window === "undefined")
+            return "";
+        // Aceder a `window.localStorage` pode LANÇAR (SecurityError com cookies bloqueados).
+        const stored = window.localStorage?.getItem(ANON_STORAGE_KEY)?.trim() ?? "";
+        return stored.length <= MAX_ANON_LEN ? stored : "";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Fire-and-forget; falhas (401 anónimo, etc.) são ignoradas.
+ *
+ * Sem sessão de cliente, `/events/track` só grava o evento quando chega o
+ * `X-Mira-Anon` — sem ele responde 202 e descarta, e o funil anónimo (a maior
+ * parte do tráfego) ficava vazio.
+ */
+export async function sendToCdp(opts, event) {
+    if (opts.enabled === false)
+        return;
+    const events = toCdpEvents(event);
+    if (events.length === 0)
+        return;
+    const headers = { "Content-Type": "application/json" };
+    const anon = readAnonId(opts);
+    if (anon)
+        headers[ANON_HEADER] = anon;
+    try {
+        await opts.client.post({
+            url: "/events/track",
+            body: { events },
+            headers,
+        });
+    }
+    catch {
+        /* CDP é best-effort */
+    }
+}
+//# sourceMappingURL=cdp.js.map

package/dist/analytics/cdp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.js","sourceRoot":"","sources":["../../src/analytics/cdp.ts"],"names":[],"mappings":"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"}

package/dist/analytics/create-analytics.d.ts

@@ -0,0 +1,3 @@
+import type { CreateMiraAnalyticsOptions, MiraAnalytics } from "./types.js";
+export declare function createMiraAnalytics(options?: CreateMiraAnalyticsOptions): MiraAnalytics;
+//# sourceMappingURL=create-analytics.d.ts.map

package/dist/analytics/create-analytics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-analytics.d.ts","sourceRoot":"","sources":["../../src/analytics/create-analytics.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,0BAA0B,EAC1B,aAAa,EAKd,MAAM,SAAS,CAAA;AAEhB,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,aAAa,CAyG3F"}