@beworke/pixel 0.1.0-rc.7 → 0.1.0-rc.9

package/docs/public/README.md

@@ -2,7 +2,9 @@
 
 Documentação para desenvolvedores que implementam funis e páginas com `@beworke/pixel`.
 
-**Versão de referência:** `0.1.0-rc.6` · **Etapas concluídas:** 1–20
+A versão publicada está em `package.json` do pacote. Instale `@beworke/pixel@rc`.
+
+> Esta pasta é a documentação **pública**. Arquitetura interna, prompts de etapas e relatórios de engenharia ficam em `PLAN_PIXEL/` (`ARCHITECTURE.md`, `PIXEL_V2_*`).
 
 > Esta pasta é a documentação **pública**. Arquitetura interna, prompts de etapas e relatórios de engenharia ficam em `PLAN_PIXEL/` (`ARCHITECTURE.md`, `PIXEL_V2_*`).
 
@@ -21,9 +23,9 @@ Instalação: `npm install @beworke/pixel@rc` (público, sem token).
 | Guia | Descrição |
 |------|-----------|
 | [Instalação](./getting-started/installation.md) | npm, tarball local, validação do pacote |
-| [Quick start](./getting-started/quick-start.md) | Primeiro `init` em ESM/CJS |
-| [Script tag (IIFE)](./getting-started/script-tag.md) | `@beworke/pixel/global` → `window.PixelV2` |
-| [React / Next.js](./getting-started/react-nextjs.md) | Padrão `useEffect` + hooks locais |
+| [Quick start](./getting-started/quick-start.md) | Factory, classe e bootstrap |
+| [Script tag (IIFE)](./getting-started/script-tag.md) | `@beworke/pixel/global` → `window.Pixel` |
+| [React / Next.js](./getting-started/react-nextjs.md) | `@beworke/pixel-react` (`PixelProvider` / `usePixel`) |
 
 ## Referência
 
@@ -33,6 +35,7 @@ Instalação: `npm install @beworke/pixel@rc` (público, sem token).
 | [Package exports](./api/exports.md) | Subpaths do `package.json` |
 | [Catálogo de eventos](./events/catalog.md) | Tipos `PixelEvent` por categoria |
 | [Configuração — visão geral](./configuration/overview.md) | `PixelConfig` e defaults |
+| [Transport](./configuration/transport.md) | Config única e senders `test`, `internal`, `external` |
 | [Módulos](./configuration/modules.md) | `modules.core`, `behavior`, `conversion`, etc. |
 | [Commerce (root)](./configuration/commerce.md) | `commerce.catalog`, `cart`, `enrichment` |
 

package/docs/public/api/exports.md

@@ -1,21 +1,24 @@
 # Package exports
 
-Auditado contra `package.json` do RC `0.1.0-rc.5`.
+Auditado contra `package.json`. Não pinamos o número da RC neste documento.
 
 ## Entry principal
 
 | Subpath | Import | Conteúdo principal |
 |---------|--------|-------------------|
-| `@beworke/pixel` | ESM / CJS | `Pixel`, `DEFAULT_PIXEL_CONFIG`, `PixelConfig`, `PixelDebugSnapshot`, `resolveStorageAdapterName` |
+| `@beworke/pixel` | ESM / CJS | `Pixel`, `createPixel`, `resolvePixelConfig`, `DEFAULT_PIXEL_CONFIG`, `PixelSettings`, `PixelConfig`, `PixelConfigurationError`, `PixelDebugSnapshot`, `resolveStorageAdapterName`, `SDK_VERSION` |
 | `@beworke/pixel/v2` | ESM / CJS | Alias do entry principal (mesmos exports) |
+| `@beworke/pixel/browser` | ESM / CJS | `bootstrapPixel`, `getBootstrappedPixel`, `getBootstrappedPixelPending`, `destroyBootstrappedPixel`, `PixelBootstrapError` |
 
 ## Global (IIFE)
 
 | Subpath | Formato | Global |
 |---------|---------|--------|
-| `@beworke/pixel/global` | IIFE | `window.PixelV2` |
+| `@beworke/pixel/global` | IIFE | `window.Pixel` (factory) + `window.PixelV2` (compat) |
 
-Arquivo build: `dist/v2/global.global.js`
+Arquivo build recomendado: `dist/browser/pixel.global.js`
+
+O artifact legado `dist/v2/global.global.js` continua gerado para consumidores que ainda apontam para `window.PixelV2` via caminho antigo.
 
 ## Subpaths avançados
 
@@ -23,7 +26,7 @@ Arquivo build: `dist/v2/global.global.js`
 
 | Subpath | Uso típico |
 |---------|------------|
-| `@beworke/pixel/config` | Tipos e helpers de config |
+| `@beworke/pixel/config` | Tipos, `PixelSettings`, `resolvePixelConfig`, `DEFAULT_TRANSPORT_CONFIG` e demais helpers de config |
 | `@beworke/pixel/events` | Tipos `PixelEvent`, payloads de conversão |
 | `@beworke/pixel/runtime` | Runtime interno (uso avançado) |
 | `@beworke/pixel/services` | Serviços compartilhados |
@@ -40,8 +43,9 @@ Arquivo build: `dist/v2/global.global.js`
 ## Validar tarball
 
 ```bash
-npm pack --dry-run
-npm run validate:rc-package
+pnpm pack:pixel
+pnpm validate:pixel-package
+pnpm smoke:pixel-package
 ```
 
-Arquivos publicados (`files`): `dist/`, `README.md`, `CHANGELOG.md`, `RELEASE_CANDIDATE.md`.
+Arquivos publicados (`files`): `dist/`, `docs/public/`, `README.md`, `CHANGELOG.md`, `RELEASE_CANDIDATE.md`.

package/docs/public/api/pixel.md

@@ -1,13 +1,28 @@
 # API — classe `Pixel`
 
-Superfície pública estável do RC `0.1.0-rc.5`. Métodos marcados `@internal` no código **não** fazem parte desta referência.
+Superfície pública estável. A versão publicada está em `package.json`. Métodos marcados `@internal` no código **não** fazem parte desta referência.
 
-## Construtor
+## Construtor e factory
 
 ```typescript
-import { Pixel, type PixelConfig } from '@beworke/pixel';
+import { Pixel, createPixel, type PixelConfig, type PixelSettings } from '@beworke/pixel';
 
-const pixel = new Pixel(config);
+const manual = new Pixel({ identity: { pixelId: 'pix_YOUR_ID' } });
+await manual.init();
+
+const pixel = await createPixel({ identity: { pixelId: 'pix_YOUR_ID' } });
+```
+
+`createPixel` e o construtor aceitam `PixelSettings` (parcial). Um `PixelConfig` completo continua válido. O merge acontece uma única vez no construtor de `Pixel`.
+
+`createPixel` cria uma instância independente, chama `init()` e só resolve depois. Se `init()` falhar, tenta `destroy()` e relança o erro original.
+
+## Bootstrap (`@beworke/pixel/browser`)
+
+```typescript
+import { bootstrapPixel } from '@beworke/pixel/browser';
+
+const pixel = await bootstrapPixel(config, { waitForConsent, force });
 ```
 
 ## Ciclo de vida
@@ -47,10 +62,16 @@ Tipos de dados: importe de `@beworke/pixel/events` se necessário.
 
 | Export | Uso |
 |--------|-----|
-| `DEFAULT_PIXEL_CONFIG` | Defaults auditados — base para merge |
-| `PixelConfig` | Tipo da configuração |
+| `Pixel` | Classe pública |
+| `createPixel` | Factory assíncrona (instâncias independentes) |
+| `resolvePixelConfig` | Resolve `PixelSettings` → `PixelConfig` |
+| `DEFAULT_PIXEL_CONFIG` | Defaults auditados — inspeção / avançado |
+| `PixelSettings` | Tipo do input público (parcial) |
+| `PixelConfig` | Tipo da configuração resolvida |
+| `PixelConfigurationError` | Erro de `pixelId` / settings inválidos |
 | `PixelDebugSnapshot` | Tipo do snapshot |
 | `resolveStorageAdapterName` | Resolve nome do adapter de persistência |
+| `SDK_VERSION` | Versão runtime alinhada a `package.json` |
 
 ## Não usar em produção / exemplos públicos
 

package/docs/public/configuration/commerce.md

@@ -6,14 +6,14 @@ Configuração root-level (não dentro de `modules`).
 
 | Campo | Default | Descrição |
 |-------|---------|-----------|
-| `enabled` | `false` (via shared default) | Habilita enrichment commerce |
+| `enabled` | `true` | Habilita enrichment commerce (catálogo vazio é no-op) |
 | `currency` | conforme `DEFAULT_COMMERCE_CONFIG` | Moeda padrão |
 | `catalog.products` | `[]` | Produtos da oferta (main, bump, upsell) |
 | `cart.mode` | `'custom'` | Carrinho gerenciado pelo app |
 | `cart.allowDynamicItems` | `true` | Itens dinâmicos no carrinho |
 | `cart.calculateValueFrom` | `'cart'` | Cálculo de `value` |
 | `mappings` | `{}` | Mapeamento de atributos/campos |
-| `enrichment` | defaults | Enriquece payloads de conversão |
+| `enrichment` | pageView/viewContent/cart events on | Completa value/items a partir do catálogo e do carrinho |
 
 ## Quando usar
 

package/docs/public/configuration/modules.md

@@ -34,23 +34,20 @@ Referência resumida auditada contra `DEFAULT_PIXEL_CONFIG`.
 
 | Campo | Default | Descrição |
 |-------|---------|-----------|
-| `enabled` | `false` | Flag do módulo |
-| `manual.*` | `enabled: false` | Wrappers manuais internos |
-| `auto.enabled` | `false` | AutoTrack off |
-| `rules.enabled` | `false` | Regras por seletor/URL |
+| `enabled` | `true` | Flag do módulo |
+| `manual.*` | `enabled: true` | API manual pública |
+| `auto.enabled` | `true` | AutoTrack on |
+| `auto.detectors.*` | `data-track` | clique em todos; `view_content` também **hover** e **visível** |
+| `auto.detectors.viewContent` | click + hover + visible | `[data-track="view_content"]` |
+| `rules.enabled` | `false` | Regras extras por seletor/URL/texto |
 
-**Quando usar:** habilite `auto` + detectors para AutoTrack; ou use API `pixel.purchase()` etc. sem auto.
+**Quando usar:** coloque `data-track="<evento>"` no HTML (e `data-product-id` / `data-email` / `data-query` quando o evento precisar). `view_content` dispara no clique, hover e visível; restrinja com `data-trigger="hover"` (ou `click` / `visible`, ou lista `hover,click`). Sem `data-trigger`, valem os 3. Para desligar: `auto.enabled: false`.
 
-## `modules.transport`
+## Transport
 
-| Campo | Default | Descrição |
-|-------|---------|-----------|
-| `enabled` | `false` | **Deve ser `true` + `sender.mode: 'api'` para API real** |
-| `sender.mode` | `'mock'` | RC local usa mock até configurar API |
-| `batch.enabled` | `true` | Agrupa envios |
-| `retry`, `circuitBreaker`, `offline` | habilitados | Resiliência |
-
-**Quando usar:** produção/staging com `transport.apiEndpoint` e `sender.mode: 'api'`.
+Transport não é módulo. Configure somente `config.transport`, usando os modos
+`test`, `internal` ou `external`. Consulte a
+[referência de Transport](./transport.md).
 
 ## `modules.integrations`
 

package/docs/public/configuration/overview.md

@@ -1,16 +1,41 @@
 # Configuração — visão geral
 
-`PixelConfig` é o objeto passado ao construtor `new Pixel(config)`.
+O input público é `PixelSettings`. Somente `identity.pixelId` é obrigatório.
+O construtor de `Pixel` chama `resolvePixelConfig(settings)` e entrega um
+`PixelConfig` completo ao Runtime.
 
-Use `DEFAULT_PIXEL_CONFIG` como base e sobrescreva apenas o necessário.
+```ts
+import { createPixel, type PixelSettings } from '@beworke/pixel';
+
+const settings = {
+  identity: { pixelId: 'pix_YOUR_ID' },
+  app: { debug: true },
+} satisfies PixelSettings;
+
+const pixel = await createPixel(settings);
+```
+
+`DEFAULT_PIXEL_CONFIG` continua disponível para inspeção e casos avançados.
+Não é necessário espalhá-lo numa integração comum.
+
+## Semântica do merge
+
+| Caso | Comportamento |
+|------|----------------|
+| Objetos plain | mescla profunda |
+| Arrays | substituem o default (não concatenam) |
+| `transport.sender` | substitui a variante inteira (`test` / `internal` / `external`) |
+| `undefined` | ausência — o default permanece |
+| `false` / `0` / `''` | valores válidos, preservados |
+| Records (`mappings`, etc.) | mescla por chave |
 
 ## Top-level
 
 | Seção | Descrição |
 |-------|-----------|
-| `app` | Ambiente, debug, source/target |
-| `identity` | `pixelId`, IDs de funil, visitor, user |
-| `transport` | API endpoint, batch, timeout, retry |
+| `app` | Ambiente, debug, source/target/platform. Vai no payload HTTP em `app` e `meta` |
+| `identity` | `pixelId` (obrigatório no input), IDs de funil |
+| `transport` | Sender, batch, timeout, retry e flush |
 | `storage` | Prefixo, namespace, fila, persistência |
 | `attribution` | UTM, cookies, persistência de atribuição |
 | `commerce` | Catálogo, carrinho, enrichment |
@@ -22,34 +47,28 @@ Use `DEFAULT_PIXEL_CONFIG` como base e sobrescreva apenas o necessário.
 |-------|---------|------|
 | `app.environment` | `'production'` | Use `'development'` + `debug: true` localmente |
 | `app.debug` | `false` | |
-| `identity.pixelId` | `''` | **Obrigatório** em produção |
-| `transport.apiEndpoint` | `''` | **Obrigatório** para enviar eventos |
-| `transport.timeoutMs` | `10000` | |
+| `app.source` | `'custom'` | Conhecidos: `pageus`, `gomarke`, `bemony`, `custom`. **Qualquer outra string é válida** (ex.: `hwaffiliate`) |
+| `app.target` | `'custom'` | `landing` \| `checkout` \| `editor` \| `preview` \| `dashboard` \| `custom` |
+| `app.platform` | `''` | Vendor da página. Conhecido: `buygoods`. String livre ok |
+| `identity.pixelId` | `''` | Obrigatório no input; o resolvedor valida e faz trim |
+| `transport.enabled` | `true` | Envia para a API interna pública |
+| `transport.sender.mode` | `'internal'` | Sem segredo no browser; `baseUrl` público |
+| `transport.timeout.timeoutMs` | `10000` | |
 | `storage.prefix` | `'__gmk'` | |
 | `storage.namespace` | `'pixel'` | |
+| `storage.persistence.visitor` | `'localStorage'` | |
+| `storage.persistence.session` | `'sessionStorage'` | |
+| `storage.persistence.attribution` | `'localStorage'` | |
 | `storage.queue.enabled` | `true` | |
 | `storage.queue.persistence` | `'memory'` | |
 | `commerce.cart.mode` | `'custom'` | |
-| `modules.core.enabled` | ver [modules](./modules.md) | Emite `PAGE_VIEW` |
+| `modules.core.enabled` | `true` | Emite `PAGE_VIEW` |
 | `modules.behavior.enabled` | `false` | Trackers off por default |
-| `modules.conversion.enabled` | `false` | Manual API ainda funciona quando módulo registrado |
-| `modules.transport.enabled` | ver modules | |
+| `modules.conversion.enabled` | `true` | Métodos manuais on; AutoTrack `data-track` on; rules off |
+| `commerce.enabled` | `true` | Enrichment on; catálogo vazio não altera payloads |
 | `modules.privacy.enabled` | ver modules | Sem CMP completo no RC |
 
-## Persistência recomendada (funis)
-
-```typescript
-storage: {
-  ...DEFAULT_PIXEL_CONFIG.storage,
-  persistence: {
-    visitor: 'localStorage',
-    session: 'sessionStorage',
-    attribution: 'localStorage',
-  },
-},
-```
-
-Sem `persistence.session`, a sessão usa `memory` e some em reload/destroy React.
+`identity.pixelId` aceita no máximo 128 caracteres após trim, sem caracteres de controle. O prefixo `pix_` não é exigido.
 
 ## Identity para funis
 
@@ -58,9 +77,9 @@ Campos úteis em `identity`:
 - `pixelId` — ID do pixel na API
 - `funnelId`, `funnelStepId` — etapa do funil
 - `pageId`, `offerId`, `checkoutId`
-- `visitorId`, `userId` — opcionais se gerenciados pelo backend
 
 ## Próximo
 
 - [Módulos](./modules.md)
+- [Transport](./transport.md)
 - [Commerce](./commerce.md)

package/docs/public/configuration/transport.md

@@ -0,0 +1,127 @@
+# Transport
+
+O Transport possui uma única configuração top-level: `config.transport`.
+
+Use `DEFAULT_TRANSPORT_CONFIG` como base avançada. No input público, basta
+omitir `transport` para usar o sender `internal` default, ou substituir a
+variante inteira:
+
+```typescript
+import { Pixel } from '@beworke/pixel';
+
+const pixel = new Pixel({
+  identity: { pixelId: 'pix_test' },
+  transport: {
+    sender: {
+      mode: 'test',
+      capture: true,
+      response: 'success',
+      delayMs: 0,
+    },
+  },
+});
+```
+
+Playgrounds podem ajustar o sender após `init()`:
+
+```typescript
+pixel.configureTransportTestSender({
+  capture: true,
+  response: 'success',
+  delayMs: 0,
+});
+```
+
+`configureTransportTestSender()` é uma API interna para playground e
+desenvolvimento; não a use como contrato de produção.
+
+## Internal sender com endpoint padrão
+
+O modo `internal` envia para os endpoints públicos oficiais do Pixel. Sem
+`baseUrl`, o SDK usa `DEFAULT_INTERNAL_TRANSPORT_BASE_URL`.
+
+```typescript
+const pixel = new Pixel({
+  identity: { pixelId: 'pix_xxx' },
+  transport: {
+    sender: { mode: 'internal' },
+  },
+});
+```
+
+Os caminhos resolvidos são:
+
+```text
+POST {baseUrl}/pixels/public/event
+POST {baseUrl}/pixels/public/event/batch
+```
+
+## Internal sender com `baseUrl`
+
+Use um `baseUrl` aprovado para staging, proxy próprio ou outra implantação
+compatível com os endpoints internos:
+
+```typescript
+transport: {
+  ...DEFAULT_TRANSPORT_CONFIG,
+  enabled: true,
+  sender: {
+    mode: 'internal',
+    baseUrl: 'https://pixel-api.example.com',
+  },
+},
+```
+
+## External sender
+
+Use `external` quando os endpoints não seguem os caminhos internos:
+
+```typescript
+transport: {
+  ...DEFAULT_TRANSPORT_CONFIG,
+  enabled: true,
+  sender: {
+    mode: 'external',
+    endpoints: {
+      event: 'https://events.example.com/v1/event',
+      batch: 'https://events.example.com/v1/batch',
+    },
+    batchFallback: 'single',
+    headers: {
+      'X-Public-Client': 'checkout-web',
+    },
+  },
+},
+```
+
+> Os headers são públicos e visíveis no browser. Nunca coloque token privado,
+> API key secreta, credencial backend ou dado equivalente em
+> `sender.headers`. Segredos devem ficar atrás de um servidor ou proxy
+> confiável.
+
+Se `endpoints.batch` não for informado, `batchFallback: 'single'` envia cada
+evento pelo endpoint individual; `'error'` rejeita o envio em lote.
+
+## Batch, timeout e flush
+
+`batch.maxWaitMs` controla a espera do lote. O intervalo periódico pertence a
+`transport.flush.flushIntervalMs`.
+
+```typescript
+transport: {
+  ...DEFAULT_TRANSPORT_CONFIG,
+  enabled: true,
+  sender: { mode: 'test', capture: true },
+  batch: {
+    ...DEFAULT_TRANSPORT_CONFIG.batch,
+    enabled: true,
+    batchSize: 10,
+    maxWaitMs: 5_000,
+  },
+  flush: {
+    ...DEFAULT_TRANSPORT_CONFIG.flush,
+    enabled: true,
+    flushIntervalMs: 2_000,
+  },
+},
+```

package/docs/public/events/catalog.md

@@ -2,7 +2,9 @@
 
 Fonte: union `PixelEvent` (`src/events/types.ts`) — **24 tipos** no RC.
 
-Todos os eventos listados abaixo passam pelo pipeline de transport quando `modules.transport.enabled` e `transport.apiEndpoint` estão configurados.
+Todos os eventos listados abaixo passam pelo pipeline quando
+`transport.enabled` está ativo. Os modos `internal` e `external` enviam pela
+rede; `test` captura eventos sem requisição.
 
 > `ApiEventType` (HTTP) inclui tipos legados/históricos que **não** fazem parte de `PixelEvent`. Use esta tabela como catálogo público.
 

package/docs/public/getting-started/installation.md

@@ -13,19 +13,13 @@ Pacote **público** — **não precisa de token** nem login npm para instalar:
 npm install @beworke/pixel@rc
 ```
 
-Versão fixa:
-
-```bash
-npm install @beworke/pixel@0.1.0-rc.6
-```
-
 Confirme a versão instalada:
 
 ```bash
 node -e "console.log(require('@beworke/pixel/package.json').version)"
 ```
 
-> Evite `npm install @beworke/pixel` sem tag até a tag `latest` apontar para a RC atual. Use `@rc` ou `@0.1.0-rc.6`.
+> Evite `npm install @beworke/pixel` sem tag até a tag `latest` apontar para a RC atual. Use `@rc`.
 
 ## Onde ler a documentação
 
@@ -39,9 +33,12 @@ O site **npmjs.com não abre** arquivos `.md` individuais (ex.: `npmjs.com/packa
 ## Tarball local (opcional)
 
 ```bash
-npm install ./beworke-pixel-0.1.0-rc.6.tgz
+pnpm pack:pixel
+npm install ./artifacts/beworke-pixel-<versão>.tgz
 ```
 
+A versão exata está em `package.json` / `artifacts/latest-package.json`.
+
 ## Validar instalação limpa
 
 Na raiz do monorepo:
@@ -49,6 +46,7 @@ Na raiz do monorepo:
 ```bash
 pnpm pack:pixel
 pnpm validate:pixel-package
+pnpm smoke:pixel-package
 ```
 
 O tarball fica em `artifacts/` (não use `pnpm --filter @beworke/pixel pack` como fluxo principal).
@@ -56,7 +54,8 @@ O tarball fica em `artifacts/` (não use `pnpm --filter @beworke/pixel pack` com
 ## Imports recomendados
 
 ```typescript
-import { Pixel, DEFAULT_PIXEL_CONFIG, type PixelConfig } from '@beworke/pixel';
+import { Pixel, createPixel, DEFAULT_PIXEL_CONFIG, type PixelConfig } from '@beworke/pixel';
+import { bootstrapPixel } from '@beworke/pixel/browser';
 ```
 
 Subpaths adicionais: [Package exports](../api/exports.md).
@@ -64,9 +63,12 @@ Subpaths adicionais: [Package exports](../api/exports.md).
 ## CDN / script tag
 
 ```html
-<script src="https://unpkg.com/@beworke/pixel@rc/dist/v2/global.global.js"></script>
-<script>
-  const { Pixel, DEFAULT_PIXEL_CONFIG } = window.PixelV2;
+<script src="https://unpkg.com/@beworke/pixel@rc/dist/browser/pixel.global.js"></script>
+<script type="module">
+  const pixel = await Pixel({
+    ...Pixel.DEFAULT_PIXEL_CONFIG,
+    identity: { pixelId: 'pix_YOUR_ID' },
+  });
 </script>
 ```