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

package/docs/public/getting-started/script-tag.md

@@ -0,0 +1,57 @@
+# Script tag (IIFE / global)
+
+## Build
+
+O subpath `@beworke/pixel/global` expõe um bundle IIFE que define `window.PixelV2`.
+
+Após `npm run build`, o artefato está em `dist/global/` (nome conforme `tsup` / `package.json`).
+
+## HTML mínimo
+
+```html
+<!DOCTYPE html>
+<html lang="pt-BR">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Pixel — script tag</title>
+  </head>
+  <body>
+    <script src="../../dist/global/pixel.global.js"></script>
+    <script>
+      (async function () {
+        const { Pixel, DEFAULT_PIXEL_CONFIG } = window.PixelV2;
+
+        const pixel = new Pixel({
+          ...DEFAULT_PIXEL_CONFIG,
+          app: { ...DEFAULT_PIXEL_CONFIG.app, debug: true },
+          identity: { pixelId: 'pix_YOUR_ID' },
+          transport: {
+            ...DEFAULT_PIXEL_CONFIG.transport,
+            apiEndpoint: 'https://your-pixel-api.example.com',
+          },
+          storage: {
+            ...DEFAULT_PIXEL_CONFIG.storage,
+            persistence: {
+              visitor: 'localStorage',
+              session: 'sessionStorage',
+              attribution: 'localStorage',
+            },
+          },
+        });
+
+        await pixel.init();
+        // Conversões manuais quando necessário
+      })();
+    </script>
+  </body>
+</html>
+```
+
+## Exemplo público
+
+Veja `apps/playground-html/public/html/landing.html`.
+
+## Limitações
+
+- TypeScript/IDE não inferem tipos no global — use JSDoc ou migre para npm ESM em apps maiores.
+- Mesmas regras de privacidade: a aplicação controla **quando** chamar `init()` após consentimento.

package/docs/public/guides/funnel-checkout.md

@@ -0,0 +1,52 @@
+# Funil — Checkout
+
+## Objetivo
+
+Rastrear início de checkout, carrinho, pagamento e compra.
+
+## Config
+
+- `commerce.enabled: true` + catálogo de produtos
+- `identity.checkoutId`, `funnelStepId`
+- Transport API habilitado
+
+Ver `apps/playground-next/lib/pixel-config.ts` e `apps/playground-html/public/html/checkout.html`.
+
+## API manual (ordem recomendada)
+
+```typescript
+await pixel.init(); // PAGE_VIEW
+
+pixel.addToCart({ productId: 'main' });       // opcional se carrinho já montado
+pixel.initiateCheckout();                     // início do checkout
+pixel.addPaymentInfo({ paymentType: 'card' }); // antes de confirmar
+pixel.purchase({ transactionId: 'ord_123' }); // após confirmação
+```
+
+## AutoTrack
+
+`modules.conversion.auto.detectors` para `addToCart`, `initiateCheckout`, `purchase` com seletores `[data-track]`.
+
+## Eventos esperados
+
+1. `PAGE_VIEW`
+2. `ADD_TO_CART` (se aplicável)
+3. `INITIATE_CHECKOUT`
+4. `ADD_PAYMENT_INFO`
+5. `PURCHASE`
+
+## QA
+
+- [ ] `value` / `currency` coerentes com `commerce.catalog`
+- [ ] `transactionId` único por pedido
+- [ ] Batch flush antes de redirect (aguardar rede ou `destroy()`)
+
+## Erros comuns
+
+| Problema | Causa | Solução |
+|----------|-------|---------|
+| `PURCHASE` sem valor | Catálogo vazio | Preencher `commerce.catalog` ou passar `value` em `purchase()` |
+| Eventos fora de ordem | Chamadas antes do `init()` | Aguardar `init()` |
+| Perda no redirect | Navegação imediata | `await pixel.destroy()` ou delay curto |
+
+Guia Next.js: [React / Next.js](../getting-started/react-nextjs.md)

package/docs/public/guides/funnel-downsell.md

@@ -0,0 +1,53 @@
+# Funil — Downsell
+
+## Objetivo
+
+Oferta alternativa (menor preço) quando upsell é recusado.
+
+## Importante (RC)
+
+Sem evento `DOWNSELL_*`. Mesmo padrão do upsell:
+
+- `PAGE_VIEW`
+- `VIEW_CONTENT` — downsell apresentado
+- `PURCHASE` — aceite
+
+## Config
+
+```typescript
+identity: {
+  funnelStepId: 'downsell_step_01',
+  offerId: 'downsell_basic',
+},
+commerce: {
+  catalog: {
+    products: [
+      { id: 'downsell_01', name: 'Plano básico', type: 'downsell', price: 47, currency: 'BRL', quantity: 1 },
+    ],
+  },
+},
+```
+
+## API manual
+
+```typescript
+pixel.viewContent({ contentId: 'downsell_01' });
+
+// Aceite
+pixel.purchase({ transactionId: 'downsell_tx_789', value: 47, currency: 'BRL' });
+```
+
+## Eventos esperados
+
+1. `PAGE_VIEW`
+2. `VIEW_CONTENT`
+3. `PURCHASE` ou abandono
+
+## QA
+
+- [ ] Step ID reflete posição no funil
+- [ ] Valor menor que upsell/checkout refletido no payload
+
+## Erros comuns
+
+Documentar downsell como `VIEW_CONTENT` + `PURCHASE` na spec interna — não esperar tipo dedicado na API HTTP legada.

package/docs/public/guides/funnel-full.md

@@ -0,0 +1,64 @@
+# Funil completo
+
+Fluxo de referência para landing → checkout → upsell → downsell → thank-you.
+
+## Ordem das páginas
+
+```txt
+1. Landing      → PAGE_VIEW, behavior, LEAD (opcional)
+2. Checkout     → INITIATE_CHECKOUT, ADD_PAYMENT_INFO, PURCHASE (principal)
+3. Upsell       → VIEW_CONTENT, PURCHASE (opcional)
+4. Downsell     → VIEW_CONTENT, PURCHASE (opcional)
+5. Thank-you    → PAGE_VIEW, PURCHASE (confirmação/dedupe)
+```
+
+## Identity por etapa
+
+Atualize em cada página (ou no router):
+
+| Campo | Exemplo |
+|-------|---------|
+| `funnelId` | Constante do funil |
+| `funnelStepId` | `landing`, `checkout`, `upsell`, … |
+| `pageId` | ID da página no CMS |
+| `offerId` | Oferta ativa |
+
+## Persistência cross-page
+
+```typescript
+storage: {
+  persistence: {
+    visitor: 'localStorage',
+    session: 'sessionStorage',
+    attribution: 'localStorage',
+  },
+},
+```
+
+Visitor e sessão devem continuar entre steps no mesmo domínio.
+
+## Commerce
+
+Um `catalog` com todos os produtos (main, bumps, upsell, downsell) simplifica enrichment. Filtre por `productId` nas chamadas manuais.
+
+## Transport
+
+Uma instância `Pixel` por aba; `destroy()` ao desmontar componentes React entre rotas se recriar instância.
+
+## QA end-to-end
+
+1. Instalar tarball RC em app limpo
+2. Percorrer funil completo em staging
+3. Validar sequência na API backend
+4. Confirmar attribution (UTM) na primeira landing
+5. Verificar dedupe de `PURCHASE` duplicado na thank-you
+
+## Exemplos
+
+| Etapa | Exemplo |
+|-------|---------|
+| Landing | `apps/playground-html/public/html/landing.html` |
+| Checkout | `apps/playground-html/public/html/checkout.html` |
+| Full (Next) | `apps/playground-next/` |
+
+Guias individuais: [landing](./funnel-landing.md), [checkout](./funnel-checkout.md), [upsell](./funnel-upsell.md), [downsell](./funnel-downsell.md), [thank-you](./funnel-thank-you.md).

package/docs/public/guides/funnel-landing.md

@@ -0,0 +1,68 @@
+# Funil — Landing
+
+## Objetivo
+
+Medir visita, comportamento na página e leads antes do checkout.
+
+## Config recomendada
+
+```typescript
+modules: {
+  ...DEFAULT_PIXEL_CONFIG.modules,
+  core: { ...DEFAULT_PIXEL_CONFIG.modules.core, enabled: true },
+  behavior: {
+    ...DEFAULT_PIXEL_CONFIG.modules.behavior,
+    enabled: true,
+    trackers: {
+      scroll: { enabled: true, thresholds: [25, 50, 75, 100], debounceMs: 100 },
+      click: { enabled: true, rageClick: { enabled: true } },
+      visibility: { enabled: true },
+      exitIntent: { enabled: true },
+    },
+  },
+  transport: {
+    ...DEFAULT_PIXEL_CONFIG.modules.transport,
+    enabled: true,
+    sender: { mode: 'api' },
+  },
+},
+```
+
+Ajuste `identity.funnelStepId` / `pageId` para a landing.
+
+## API manual
+
+```typescript
+await pixel.init();
+// PAGE_VIEW automático
+
+pixel.lead({ email: 'user@example.com' }); // formulário enviado
+pixel.viewContent({ contentId: 'hero-offer' }); // CTA / seção vista
+```
+
+## AutoTrack
+
+Opcional: `modules.conversion.auto` + detector `lead` com seletores do formulário.
+
+## Eventos esperados (ordem típica)
+
+1. `PAGE_VIEW`
+2. `SCROLL`, `PAGE_CLICK`, … (behavior)
+3. `LEAD` ou `VIEW_CONTENT` (conversão)
+
+## QA
+
+- [ ] `pixelId` e `apiEndpoint` corretos
+- [ ] Persistência `sessionStorage` para sessão
+- [ ] Um único `init()` por aba
+- [ ] `getDebugSnapshot()` mostra transport enviando (dev)
+
+## Erros comuns
+
+| Problema | Causa | Solução |
+|----------|-------|---------|
+| Sem eventos na API | `transport.enabled: false` ou `sender.mode: 'mock'` | Habilitar transport + mode `api` |
+| Sessão zera no reload | Sem `storage.persistence.session` | Configurar `sessionStorage` |
+| Duplo `PAGE_VIEW` | Dois `init()` | Singleton / cleanup `destroy()` |
+
+Exemplo: `apps/playground-html/public/html/landing.html`

package/docs/public/guides/funnel-thank-you.md

@@ -0,0 +1,48 @@
+# Funil — Thank-you
+
+## Objetivo
+
+Confirmar compra concluída e encerrar sessão de tracking da jornada.
+
+## API manual
+
+Se `PURCHASE` já foi enviado no checkout/upsell, thank-you pode ser apenas:
+
+```typescript
+await pixel.init(); // PAGE_VIEW na página de obrigado
+```
+
+Opcional — reforço com dados do pedido:
+
+```typescript
+pixel.purchase({
+  transactionId: 'ord_123',
+  value: 197,
+  currency: 'BRL',
+});
+```
+
+O módulo de conversão deduplica eventos repetidos dentro da janela configurada (`modules.core.dedupe`).
+
+## AutoTrack
+
+Detector `purchase` em URL patterns: `thank-you`, `success`, `order` (`modules.conversion.rules.urlPatterns`).
+
+## Eventos esperados
+
+1. `PAGE_VIEW`
+2. `PURCHASE` (se disparado manualmente ou via auto)
+3. `ENGAGEMENT_SUMMARY` / `BEHAVIOR_SESSION_SUMMARY` (se behavior + session summary habilitados no destroy)
+
+## QA
+
+- [ ] `transactionId` igual ao pedido real
+- [ ] Sem PII em plain text se política exigir hashing (Etapa 25)
+
+## Encerramento
+
+```typescript
+await pixel.destroy();
+```
+
+Em SPA, ao sair da thank-you page.

package/docs/public/guides/funnel-upsell.md

@@ -0,0 +1,72 @@
+# Funil — Upsell
+
+## Objetivo
+
+Medir visualização e conversão de oferta adicional **após** compra inicial.
+
+## Importante (RC)
+
+**Não existe** evento `UPSELL_*` no SDK. Use:
+
+- `PAGE_VIEW` — página carregou
+- `VIEW_CONTENT` — oferta upsell exibida / vídeo assistido
+- `PURCHASE` — aceite da oferta (novo `transactionId` ou mesmo pedido conforme regra de negócio)
+
+## Config
+
+```typescript
+identity: {
+  ...identity,
+  funnelStepId: 'upsell_step_01',
+  offerId: 'upsell_premium',
+},
+commerce: {
+  enabled: true,
+  catalog: {
+    products: [
+      { id: 'upsell_01', name: 'Upsell', type: 'upsell', price: 97, currency: 'BRL', quantity: 1 },
+    ],
+  },
+},
+```
+
+## API manual
+
+```typescript
+await pixel.init();
+
+pixel.viewContent({
+  contentId: 'upsell_01',
+  contentName: 'Oferta complementar',
+});
+
+// Botão "Sim, quero adicionar"
+pixel.purchase({
+  transactionId: 'upsell_tx_456',
+  value: 97,
+  currency: 'BRL',
+});
+```
+
+## AutoTrack
+
+Detector `viewContent` / `purchase` em botões da oferta (`data-track="upsell-accept"`).
+
+## Eventos esperados
+
+1. `PAGE_VIEW`
+2. `VIEW_CONTENT`
+3. `PURCHASE` (se aceito) ou saída sem conversão
+
+## QA
+
+- [ ] `funnelStepId` distinto do checkout principal
+- [ ] Produto upsell no `catalog`
+- [ ] Não reutilizar `transactionId` do pedido principal sem regra explícita
+
+## Erros comuns
+
+| Problema | Causa | Solução |
+|----------|-------|---------|
+| Upsell não aparece na API | Evento inventado | Usar `VIEW_CONTENT` / `PURCHASE` |
+| Sessão quebrada | Novo domínio sem persistência | Mesmo `storage.persistence` cross-page |

package/docs/public/limitations.md

@@ -0,0 +1,32 @@
+# Limitações conhecidas do RC
+
+Versão: `0.1.0-rc.5` · Etapas 1–20 concluídas.
+
+## Produto
+
+| Limitação | Detalhe |
+|-----------|---------|
+| Consent / CMP | Incompleto — Etapa 25 |
+| Commerce Lifecycle | Etapa 21 não iniciada neste RC documental |
+| Eventos upsell/downsell | Sem tipos dedicados; use `VIEW_CONTENT` + `PURCHASE` |
+| `./diagnostics` | Não é export do pacote |
+| APIs `@internal` | Playgrounds only — não suportadas publicamente |
+
+## Config / defaults
+
+| Limitação | Detalhe |
+|-----------|---------|
+| `modules.behavior.enabled` | `false` por default — habilitar explicitamente |
+| `modules.transport.sender.mode` | `'mock'` por default — trocar para `'api'` |
+| Sessão em memory | Sem `storage.persistence.session` |
+
+## Distribuição
+
+- Tarball local / npm privado — não há CDN público fixo documentado neste RC.
+- Não altere versão sem política de release do time.
+
+## Validação
+
+670 testes automatizados (2 skipped). Smoke real requer endpoint configurado.
+
+Veja também [RELEASE_CANDIDATE.md](../../RELEASE_CANDIDATE.md) e [PIXEL_V2_VALIDATION_MATRIX.md](../../../../PLAN_PIXEL/PIXEL_V2_VALIDATION_MATRIX.md).

package/docs/public/privacy/limitations.md

@@ -0,0 +1,33 @@
+# Privacidade e consentimento (RC)
+
+## Estado do RC `0.1.0-rc.5`
+
+- **Não há Consent Gate / CMP completo** integrado ao SDK.
+- `modules.core.consent` e `modules.privacy.consent` existem na config mas **defaults desligados**.
+- Etapa **25 — Privacy/Consent** ainda não concluída.
+
+## Responsabilidade da aplicação
+
+1. **Quando inicializar** — só chame `pixel.init()` após obter consentimento do usuário, se exigido pela sua política.
+2. **Banner / CMP** — implemente no app (React, HTML, tag manager). O Pixel não substitui ferramenta de consentimento.
+3. **PII** — `modules.privacy.pii` (hash email/phone) off por default; você controla o que envia em `lead()` etc.
+
+## O que NÃO declarar
+
+- Não afirmar **GDPR**, **LGPD** ou **CCPA compliant** apenas por usar este RC.
+- Não documentar fluxos de opt-out automáticos que ainda não existem no SDK.
+
+## Padrão recomendado
+
+```typescript
+async function onUserConsentGranted() {
+  const pixel = new Pixel(createConfig());
+  await pixel.init();
+}
+
+// Antes do consentimento: não instanciar ou não chamar init()
+```
+
+## Próximos passos (roadmap)
+
+Consentimento completo e políticas de retenção/anonymization na Etapa 25. Até lá, trate o RC como **distribuição controlada ao time** com revisão jurídica da aplicação host.

package/docs/public/release-candidate/validation.md

@@ -0,0 +1,42 @@
+# Validação do Release Candidate
+
+## Comandos (raiz do monorepo)
+
+```bash
+pnpm type-check
+pnpm test
+pnpm build
+pnpm --filter @beworke/pixel test:smoke:real
+pnpm --filter @beworke/pixel test:transport
+pnpm --filter @beworke/pixel test:integration
+
+pnpm pack:pixel
+pnpm validate:pixel-package
+pnpm smoke:pixel-package
+pnpm validate:public-docs
+pnpm validate:public-examples
+```
+
+O fluxo oficial de empacotamento é **`pnpm pack:pixel`** (tarball em `artifacts/`).  
+Não use `pnpm --filter @beworke/pixel pack` como fluxo principal.
+
+## Tarball
+
+Nome esperado: `artifacts/beworke-pixel-0.1.0-rc.6.tgz`  
+Manifesto: `artifacts/latest-package.json` (caminho relativo portátil).
+
+Instalação em projeto limpo:
+
+```bash
+npm install /caminho/para/artifacts/beworke-pixel-0.1.0-rc.6.tgz
+```
+
+## Checklist rápido
+
+- [ ] Exports `.`, `./global`, `./v2`, `./config`, `./events`, `./services`, `./runtime`, `./logger`
+- [ ] `window.PixelV2` no build global
+- [ ] Exemplos públicos sem `@internal` / sem import de `src/`
+- [ ] Links em `packages/pixel/docs/public/` válidos
+- [ ] README aponta para `packages/pixel/docs/public/`
+
+Documentos: [RELEASE_CANDIDATE.md](../../../RELEASE_CANDIDATE.md), [PIXEL_V2_PUBLIC_RC_RELEASE_CHECKLIST.md](../../../../../PLAN_PIXEL/PIXEL_V2_PUBLIC_RC_RELEASE_CHECKLIST.md).

package/docs/public/troubleshooting.md

@@ -0,0 +1,55 @@
+# Troubleshooting
+
+## Nenhum evento chega na API
+
+1. Confirme `transport.apiEndpoint` preenchido
+2. `modules.transport.enabled: true`
+3. `modules.transport.sender.mode: 'api'` (não `mock`)
+4. `identity.pixelId` definido
+5. DevTools → Network: requisições ao endpoint
+
+## `init()` falha ou trava
+
+- Verifique DOM disponível (browser only)
+- Em SSR, não chame `init()` no servidor
+- Confira CORS no endpoint da API
+
+## Sessão / visitor inconsistentes
+
+Configure persistência:
+
+```typescript
+storage: {
+  persistence: {
+    visitor: 'localStorage',
+    session: 'sessionStorage',
+    attribution: 'localStorage',
+  },
+},
+```
+
+## Duplicata de `PAGE_VIEW` ou `PURCHASE`
+
+- Evite múltiplos `init()` sem `destroy()`
+- Dedupe default: `modules.core.dedupe.windowMs: 2000`
+- React Strict Mode pode montar duas vezes em dev — use singleton ou guard
+
+## Snapshot para debug
+
+```typescript
+console.log(pixel.getDebugSnapshot());
+```
+
+Não use `getDebugServices()` em apps de funil.
+
+## Instalação / tarball
+
+```bash
+npm run validate:rc-package
+```
+
+## Links úteis
+
+- [Configuração](./configuration/overview.md)
+- [Transport module](./configuration/modules.md)
+- [Validação RC](./release-candidate/validation.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beworke/pixel",
-  "version": "0.1.0-rc.5",
+  "version": "0.1.0-rc.7",
   "description": "Pixel v2 — SDK de analytics e conversão para API própria e destinos browser",
   "main": "./dist/index.cjs.js",
   "module": "./dist/index.esm.js",
@@ -47,21 +47,21 @@
   },
   "files": [
     "dist",
+    "docs/public",
     "README.md",
     "CHANGELOG.md",
     "RELEASE_CANDIDATE.md"
   ],
   "scripts": {
     "dev": "tsup --watch",
-    "build": "tsup",
+    "build": "tsup && node ../../scripts/copy-packaged-examples.mjs",
     "test": "vitest run",
     "test:watch": "vitest",
-    "test:smoke:real": "node ./scripts/run-smoke-real.mjs",
-    "validate:rc-package": "node ./scripts/validate-rc-package.mjs",
-    "validate:public-docs": "node ./scripts/validate-public-docs.mjs",
-    "validate:public-examples": "node ./scripts/validate-public-examples.mjs",
-    "publish:rc": "npm publish --tag rc",
-    "validate:15b": "node ./scripts/validate-15b.mjs",
+    "test:smoke:real": "node ../../scripts/run-smoke-real.mjs",
+    "validate:rc-package": "node ../../scripts/validate-rc-package.mjs",
+    "validate:public-docs": "node ../../scripts/validate-public-docs.mjs",
+    "validate:public-examples": "node ../../scripts/validate-public-examples.mjs",
+    "publish:rc": "npm publish --tag rc --tag latest",
     "test:integration": "vitest run src/integration",
     "test:transport": "vitest run src/transport",
     "test:full-funnel": "vitest run src/modules/core/url-context src/integration/stage-15b-module-matrix.test.ts",
@@ -71,9 +71,7 @@
     "format": "prettier --write src/**/*.{ts,tsx,js,jsx,json,css,md}",
     "type-check": "tsc --noEmit",
     "prepublishOnly": "pnpm build",
-    "changeset": "changeset",
-    "version": "changeset version",
-    "release": "pnpm build && changeset publish"
+    "clean": "rimraf dist coverage"
   },
   "keywords": [
     "pixel",
@@ -91,9 +89,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.7.1",
   "devDependencies": {
-    "@changesets/cli": "^2.29.7",
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
@@ -102,6 +98,7 @@
     "eslint-plugin-prettier": "^5.0.0",
     "happy-dom": "^20.6.3",
     "prettier": "^3.0.0",
+    "rimraf": "^6.0.1",
     "tsup": "^8.5.0",
     "typescript": "^5.0.0",
     "vitest": "^4.0.18"