@beworke/pixel 0.1.0-rc.1 → 0.1.0-rc.11

package/docs/public/README.md

@@ -0,0 +1,80 @@
+# Pixel v2 — Documentação pública (RC)
+
+Documentação para desenvolvedores que implementam funis e páginas com `@beworke/pixel`.
+
+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_*`).
+
+## Onde ler (importante)
+
+| Contexto | URL / caminho |
+|----------|----------------|
+| **GitHub (browser)** | https://github.com/techionext/Pixel-Global/tree/main/packages/pixel/docs/public |
+| **Pacote npm instalado** | `node_modules/@beworke/pixel/docs/public/` |
+| **npmjs.com** | Só renderiza o `README.md` do pacote — **não** abre `.md` individuais |
+
+Instalação: `npm install @beworke/pixel@rc` (público, sem token).
+
+## Começar
+
+| Guia | Descrição |
+|------|-----------|
+| [Instalação](./getting-started/installation.md) | npm, tarball local, validação do pacote |
+| [Quick start](./getting-started/quick-start.md) | Factory, classe e bootstrap |
+| [Script tag (IIFE)](./getting-started/script-tag.md) | `@beworke/pixel/global` → `window.Pixel`; presets BuyGoods sem config |
+| [React / Next.js](./getting-started/react-nextjs.md) | `@beworke/pixel-react` (`PixelProvider` / `usePixel`) |
+
+## Referência
+
+| Documento | Conteúdo |
+|-----------|----------|
+| [API — Pixel](./api/pixel.md) | Métodos públicos estáveis |
+| [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` |
+
+## Funis
+
+| Página | Guia |
+|--------|------|
+| Landing | [guides/funnel-landing.md](./guides/funnel-landing.md) |
+| Checkout | [guides/funnel-checkout.md](./guides/funnel-checkout.md) |
+| Upsell | [guides/funnel-upsell.md](./guides/funnel-upsell.md) |
+| Downsell | [guides/funnel-downsell.md](./guides/funnel-downsell.md) |
+| Thank-you | [guides/funnel-thank-you.md](./guides/funnel-thank-you.md) |
+| Funil completo | [guides/funnel-full.md](./guides/funnel-full.md) |
+
+## Exemplos públicos
+
+Exemplos em `apps/playground-html/public/` usam **somente API pública** (sem `getDebugServices`, sem hooks de debug).
+
+| Exemplo | Caminho no monorepo |
+|---------|---------------------|
+| Landing (HTML) | `apps/playground-html/public/html/landing.html` |
+| Checkout (HTML) | `apps/playground-html/public/html/checkout.html` |
+| Next.js (App Router) | `apps/playground-next/` (hooks locais, não exportados pelo SDK) |
+
+Playgrounds internos de engenharia: `apps/playground-html/` (podem usar APIs `@internal`).
+
+> **Legado:** na estrutura anterior ao monorepo, estes caminhos eram `examples/public/`, `examples/nextjs/` e `examples/html-script/`.
+
+## Privacidade e limitações
+
+| Documento | Conteúdo |
+|-----------|----------|
+| [Privacidade e consentimento](./privacy/limitations.md) | RC sem CMP completo; responsabilidade da aplicação |
+| [Limitações conhecidas do RC](./limitations.md) | O que não está pronto para produção pública |
+| [Troubleshooting](./troubleshooting.md) | Erros comuns |
+
+## Release Candidate
+
+| Documento | Conteúdo |
+|-----------|----------|
+| [Validação do pacote](./release-candidate/validation.md) | `pack:pixel`, smoke, checklist |
+| [RELEASE_CANDIDATE.md](../../RELEASE_CANDIDATE.md) | Notas oficiais do RC |

package/docs/public/api/exports.md

@@ -0,0 +1,56 @@
+# Package exports
+
+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`, `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`, settings dos presets BuyGoods |
+
+## Global (IIFE)
+
+| Subpath | Formato | Global |
+|---------|---------|--------|
+| `@beworke/pixel/global` | IIFE | `window.Pixel` (factory) + `window.PixelV2` (compat) |
+| `@beworke/pixel/buygoods-landing` | IIFE | Auto-init landing BuyGoods (sem settings) |
+| `@beworke/pixel/buygoods-checkout` | IIFE | Auto-init checkout BuyGoods (sem settings; sobe para `window.top`) |
+| `@beworke/pixel/internal-checkout` | IIFE | Auto-init checkout interno; `pixelId` só na query do script |
+
+Arquivo build recomendado: `dist/browser/pixel.global.js`
+
+Presets drop-in: `dist/browser/pixel.buygoods-landing.global.js`, `dist/browser/pixel.buygoods-checkout.global.js` e `dist/browser/pixel.internal-checkout.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
+
+Úteis para tipos, eventos ou integrações custom — **não** necessários para funis básicos.
+
+| Subpath | Uso típico |
+|---------|------------|
+| `@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 |
+| `@beworke/pixel/logger` | Logger do SDK |
+
+## Não exportado
+
+| Subpath | Status |
+|---------|--------|
+| `@beworke/pixel/diagnostics` | **Não existe** no `package.json` RC |
+
+`PixelDebugSnapshot` é exportado pelo entry principal, não por subpath separado.
+
+## Validar tarball
+
+```bash
+pnpm pack:pixel
+pnpm validate:pixel-package
+pnpm smoke:pixel-package
+```
+
+Arquivos publicados (`files`): `dist/`, `docs/public/`, `README.md`, `CHANGELOG.md`, `RELEASE_CANDIDATE.md`.

package/docs/public/api/pixel.md

@@ -0,0 +1,86 @@
+# API — classe `Pixel`
+
+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 e factory
+
+```typescript
+import { Pixel, createPixel, type PixelConfig, type PixelSettings } from '@beworke/pixel';
+
+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
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `init()` | `Promise<void>` | Inicializa runtime, módulos e emite `PAGE_VIEW` quando core habilitado |
+| `destroy()` | `Promise<void>` | Remove listeners, flush parcial e marca snapshot como destruído |
+| `isInitialized()` | `boolean` | `true` após `init()` concluir com sucesso |
+
+## Diagnóstico (público)
+
+| Método | Retorno | Descrição |
+|--------|---------|-----------|
+| `getDebugSnapshot()` | `Readonly<PixelDebugSnapshot>` | Snapshot read-only sanitizado; seguro antes/depois de init e após destroy |
+
+Use em desenvolvimento para validar sessão, fila de transport e módulos. Não substitui observabilidade de produção.
+
+## Conversão (manual)
+
+Todos retornam `void`. Dados opcionais enriquecem payload; commerce config pode calcular `value`/`items`.
+
+| Método | Dados | Evento emitido |
+|--------|-------|----------------|
+| `purchase(data?)` | `PurchaseData` | `PURCHASE` |
+| `lead(data)` | `LeadData` (obrigatório) | `LEAD` |
+| `addToCart(data?)` | `AddToCartData` | `ADD_TO_CART` |
+| `removeFromCart(data?)` | `RemoveFromCartData` | `REMOVE_FROM_CART` |
+| `initiateCheckout(data?)` | `InitiateCheckoutData` | `INITIATE_CHECKOUT` |
+| `addPaymentInfo(data?)` | `AddPaymentInfoEvent` | `ADD_PAYMENT_INFO` |
+| `viewContent(data?)` | `ViewContentData` | `VIEW_CONTENT` |
+| `search(data)` | `SearchData` (obrigatório) | `SEARCH` |
+
+Tipos de dados: importe de `@beworke/pixel/events` se necessário.
+
+## Exports relacionados (entry principal)
+
+| Export | Uso |
+|--------|-----|
+| `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
+
+Estes existem no código para playgrounds internos:
+
+- `getDebugServices()`
+- `debugPublishBehaviorSignal()`
+- `flushBehaviorBuffer()`
+- `simulateTransport*`, `manualTransportReplay`, etc.
+- `getDebugDedupeKeys`, `getDebugIntegrationState`, …
+
+Veja `apps/playground-html/` apenas para engenharia interna.

package/docs/public/configuration/commerce.md

@@ -0,0 +1,44 @@
+# Commerce (`commerce`)
+
+Configuração root-level (não dentro de `modules`).
+
+## Campos principais
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `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` | pageView/viewContent/cart events on | Completa value/items a partir do catálogo e do carrinho |
+
+## Quando usar
+
+- **Checkout:** catálogo com produto principal + order bumps
+- **Upsell/downsell:** produtos adicionais no `catalog`; dispare `viewContent` / `purchase` manualmente
+- **Thank-you:** `purchase` com `transactionId` do pedido
+
+## Exemplo (checkout)
+
+```typescript
+commerce: {
+  enabled: true,
+  currency: 'BRL',
+  catalog: {
+    products: [
+      { id: 'main', name: 'Oferta', type: 'main', price: 197, currency: 'BRL', quantity: 1 },
+    ],
+  },
+  cart: {
+    mode: 'custom',
+    initialItems: [],
+    allowDynamicItems: true,
+    calculateValueFrom: 'cart',
+  },
+},
+```
+
+Referência completa: `apps/playground-next/lib/pixel-config.ts`.

package/docs/public/configuration/modules.md

@@ -0,0 +1,63 @@
+# Módulos (`modules.*`)
+
+Referência resumida auditada contra `DEFAULT_PIXEL_CONFIG`.
+
+## `modules.core`
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `enabled` | `true` | Módulo core ativo |
+| `pageView.enabled` | `true` | Emite `PAGE_VIEW` |
+| `pageView.trackInitialPageView` | `true` | No `init()` |
+| `pageView.spa` | `true` | Suporte SPA |
+| `visitor.enabled` | `true` | Gera/persiste visitor |
+| `session.enabled` | `true` | Sessão com TTL 3h |
+| `consent.enabled` | `false` | Gate de consentimento **off** no default |
+
+**Quando usar:** sempre em páginas web. Desligue apenas em testes headless sem DOM.
+
+## `modules.behavior`
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `enabled` | `false` | Behavior off por default |
+| `trackers.scroll/click/...` | `enabled: false` | Habilitar por tracker |
+| `heartbeat.enabled` | `false` | `BEHAVIOR_HEARTBEAT` |
+| `engagement.enabled` | `false` | Score + `ENGAGEMENT_*` |
+| `rateLimit/buffer/stateMachine/sessionSummary` | `enabled: false` | Runtime intelligence (Etapa 20) |
+
+**Quando usar:** landing e páginas de conteúdo para scroll, cliques, engagement.
+
+**Limitação RC:** muitos sub-recursos exigem config explícita; defaults conservadores.
+
+## `modules.conversion`
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `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:** 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`.
+
+## Transport
+
+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`
+
+Destinos browser (GA, Meta, etc.) — ver defaults em `@beworke/pixel/config`. Off por default no RC de funil API-first.
+
+## `modules.privacy`
+
+| Campo | Default | Descrição |
+|-------|---------|-----------|
+| `enabled` | `false` | Módulo privacy off |
+| `consent.enabled` | `false` | Sem CMP integrado |
+
+**Limitação RC:** consentimento completo previsto para Etapa 25. Ver [privacidade](../privacy/limitations.md).

package/docs/public/configuration/overview.md

@@ -0,0 +1,85 @@
+# Configuração — visão geral
+
+O input público é `PixelSettings`. Somente `identity.pixelId` é obrigatório.
+O construtor de `Pixel` chama `resolvePixelConfig(settings)` e entrega um
+`PixelConfig` completo ao Runtime.
+
+```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/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 |
+| `modules` | Feature flags por módulo |
+
+## Defaults críticos (`DEFAULT_PIXEL_CONFIG`)
+
+| Campo | Default | Nota |
+|-------|---------|------|
+| `app.environment` | `'production'` | Use `'development'` + `debug: true` localmente |
+| `app.debug` | `false` | |
+| `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` | `true` | Emite `PAGE_VIEW` |
+| `modules.behavior.enabled` | `false` | Trackers off por default |
+| `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 |
+
+`identity.pixelId` aceita no máximo 128 caracteres após trim, sem caracteres de controle. O prefixo `pix_` não é exigido.
+
+## Identity para funis
+
+Campos úteis em `identity`:
+
+- `pixelId` — ID do pixel na API
+- `funnelId`, `funnelStepId` — etapa do funil
+- `pageId`, `offerId`, `checkoutId`
+
+## 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

@@ -0,0 +1,67 @@
+# Catálogo de eventos
+
+Fonte: union `PixelEvent` (`src/events/types.ts`) — **24 tipos** no RC.
+
+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.
+
+## Core
+
+| Tipo | Disparo | Transport |
+|------|---------|-----------|
+| `PAGE_VIEW` | Automático no `init()` (core habilitado) | Sim |
+
+## Session
+
+| Tipo | Disparo | Transport |
+|------|---------|-----------|
+| `SESSION_RENEWED` | Renovação de sessão | Sim |
+| `SESSION_EXPIRED` | Expiração de sessão | Sim |
+
+## Behavior
+
+Requer `modules.behavior.enabled` e trackers/config correspondentes.
+
+| Tipo | Disparo típico | Transport |
+|------|----------------|-----------|
+| `SCROLL` | Thresholds de scroll | Sim |
+| `PAGE_CLICK` | Clique na página | Sim |
+| `RAGE_CLICK` | Cliques repetidos (rage detector) | Sim |
+| `VISIBILITY_CHANGE` | Tab hidden/visible | Sim |
+| `USER_IDLE` | Usuário inativo | Sim |
+| `USER_ACTIVE` | Retorno da inatividade | Sim |
+| `EXIT_INTENT` | Intenção de saída | Sim |
+| `BEHAVIOR_HEARTBEAT` | Intervalo configurado | Sim |
+| `VIEWPORT_ENTER` | Elemento entra no viewport | Sim |
+| `VIEWPORT_EXIT` | Elemento sai do viewport | Sim |
+| `ENGAGEMENT_UPDATE` | Score de engagement muda | Sim |
+| `ENGAGEMENT_SUMMARY` | Resumo (ex.: destroy) | Sim |
+| `BEHAVIOR_SESSION_SUMMARY` | Resumo agregado da sessão (Etapa 20) | Sim |
+
+## Conversion
+
+Disparados por métodos públicos `pixel.*` ou auto-detectors quando habilitados.
+
+| Tipo | API manual | Transport |
+|------|------------|-----------|
+| `PURCHASE` | `purchase()` | Sim |
+| `LEAD` | `lead()` | Sim |
+| `ADD_TO_CART` | `addToCart()` | Sim |
+| `REMOVE_FROM_CART` | `removeFromCart()` | Sim |
+| `INITIATE_CHECKOUT` | `initiateCheckout()` | Sim |
+| `ADD_PAYMENT_INFO` | `addPaymentInfo()` | Sim |
+| `VIEW_CONTENT` | `viewContent()` | Sim |
+| `SEARCH` | `search()` | Sim |
+
+## Eventos inexistentes (RC)
+
+Não há tipos dedicados `UPSELL_*` ou `DOWNSELL_*`. Use `VIEW_CONTENT`, `PAGE_VIEW` e conversões commerce (`PURCHASE`, etc.) conforme [guias de funil](../guides/funnel-upsell.md).
+
+## Importar tipos
+
+```typescript
+import type { PixelEvent, PurchaseEvent } from '@beworke/pixel/events';
+```