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

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

@@ -0,0 +1,87 @@
+# Instalação
+
+## Requisitos
+
+- Node.js 18+ (para npm/ESM)
+- Navegador moderno (Chrome, Firefox, Safari, Edge)
+
+## npm (registry — recomendado para o time)
+
+Pacote **público** — **não precisa de token** nem login npm para instalar:
+
+```bash
+npm install @beworke/pixel@rc
+```
+
+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`.
+
+## Onde ler a documentação
+
+| Contexto | Caminho |
+|----------|---------|
+| **Browser (GitHub)** | https://github.com/techionext/Pixel-Global/tree/main/packages/pixel/docs/public |
+| **Após npm install** | `node_modules/@beworke/pixel/docs/public/` |
+
+O site **npmjs.com não abre** arquivos `.md` individuais (ex.: `npmjs.com/package/@beworke/docs/...` → 404). Isso é normal.
+
+## Tarball local (opcional)
+
+```bash
+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:
+
+```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).
+
+## Imports recomendados
+
+```typescript
+import { Pixel, createPixel, DEFAULT_PIXEL_CONFIG, type PixelConfig } from '@beworke/pixel';
+import { bootstrapPixel } from '@beworke/pixel/browser';
+```
+
+Subpaths adicionais: [Package exports](../api/exports.md).
+
+## CDN / script tag
+
+```html
+<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>
+```
+
+Presets BuyGoods (um script, sem settings):
+
+```html
+<script src="https://unpkg.com/@beworke/pixel@latest/dist/browser/pixel.buygoods-landing.global.js"></script>
+<script src="https://unpkg.com/@beworke/pixel@latest/dist/browser/pixel.buygoods-checkout.global.js"></script>
+```
+
+Detalhes: [Script tag](./script-tag.md).
+
+## O que não instalar
+
+- Não importe de `src/` — use apenas exports do pacote publicados no tarball.
+- Não dependa de `./diagnostics` — não é subpath público no `package.json` RC.

package/docs/public/getting-started/quick-start.md

@@ -0,0 +1,142 @@
+# Quick start
+
+Há três níveis de uso. O input público é `PixelSettings`: somente
+`identity.pixelId` é obrigatório. O SDK mescla o restante com
+`DEFAULT_PIXEL_CONFIG` dentro do construtor de `Pixel`.
+
+- objetos são mesclados profundamente;
+- arrays substituem os defaults (não concatenam);
+- `transport.sender` substitui a variante inteira (`test` / `internal` / `external`);
+- `undefined` significa “usar o default”;
+- `false`, `0` e `''` são valores válidos e não apagam o default por acidente.
+
+Use `PixelSettings` no input e `PixelConfig` quando precisar da configuração
+já resolvida.
+
+## 1. HTML — `Pixel(settings)`
+
+O bundle global **não** auto-inicializa. Top-level `await` exige `type="module"`.
+
+```html
+<script src="https://unpkg.com/@beworke/pixel@rc/dist/browser/pixel.global.js"></script>
+<script type="module">
+  const pixel = await Pixel({
+    identity: {
+      pixelId: 'pix_YOUR_ID',
+    },
+  });
+  pixel.lead({ email: 'user@example.com' });
+</script>
+```
+
+Overrides opcionais:
+
+```js
+await Pixel({
+  identity: { pixelId: 'pix_YOUR_ID' },
+  app: { environment: 'development', debug: true },
+});
+```
+
+Isso equivale a `bootstrapPixel(settings)`: uma instância por `window`.
+
+## 2. NPM — `createPixel`
+
+Instâncias **independentes** (não é singleton).
+
+```typescript
+import { createPixel } from '@beworke/pixel';
+
+const pixel = await createPixel({
+  identity: { pixelId: 'pix_YOUR_ID' },
+});
+```
+
+A classe pública continua válida:
+
+```typescript
+import { Pixel } from '@beworke/pixel';
+
+const pixel = new Pixel({
+  identity: { pixelId: 'pix_YOUR_ID' },
+});
+await pixel.init();
+```
+
+Um `PixelConfig` completo continua sendo aceito.
+
+## 3. Browser avançado — `bootstrapPixel`
+
+```typescript
+import { bootstrapPixel } from '@beworke/pixel/browser';
+
+const pixel = await bootstrapPixel(
+  {
+    identity: { pixelId: 'pix_YOUR_ID' },
+  },
+  { waitForConsent: () => true }
+);
+```
+
+- Sem `force`, a primeira chamada é dona da instância naquela `window`.
+- Para trocar a configuração: `destroyBootstrappedPixel()` ou `{ force: true }`.
+- Chamadas concorrentes compartilham a configuração da primeira chamada.
+
+## 4. Eventos automáticos
+
+Após `Pixel(settings)` / `createPixel` / `bootstrapPixel`:
+
+- `PAGE_VIEW` (core) é emitido por default
+- métodos manuais de conversão (`lead`, `purchase`, …) estão habilitados
+- AutoTrack escuta `[data-track="<evento>"]` no clique (`view_content`, `add_to_cart`, `remove_from_cart`, `initiate_checkout`, `add_payment_info`, `purchase`, `lead`, `search`)
+- `view_content` dispara no **hover** e quando o elemento **fica visível**; `data-trigger="hover"` (ou `click` / `visible`) restringe o modo — sem o atributo, valem os 3
+- enrichment de commerce está on: informe o catálogo para completar name/price/currency
+- rules de DOM extras, behavior avançado e destinos Meta/Google/TikTok
+  continuam **desabilitados** até você habilitá-los
+
+```html
+<button data-track="add_to_cart" data-product-id="sku-1">Comprar</button>
+<div data-track="view_content" data-product-id="sku-1">Produto (click + hover + visible)</div>
+<div data-track="view_content" data-product-id="sku-1" data-trigger="hover">Só hover</div>
+<button data-track="lead" data-email="user@example.com">Quero saber mais</button>
+```
+
+## 5. Conversão manual
+
+```typescript
+pixel.purchase({
+  transactionId: 'order_123',
+  value: 197,
+  currency: 'BRL',
+});
+```
+
+Outros métodos: `lead`, `addToCart`, `removeFromCart`, `initiateCheckout`, `addPaymentInfo`, `viewContent`, `search`.
+
+## 6. Encerrar (SPA / navegação)
+
+```typescript
+await pixel.destroy();
+```
+
+Com `bootstrapPixel` / `window.Pixel`, prefira `destroyBootstrappedPixel()` / `Pixel.destroy()`. Em React, o `PixelProvider` é dono do lifecycle.
+
+## 7. Debug (somente desenvolvimento)
+
+```typescript
+if (pixel.isInitialized()) {
+  console.log(pixel.getDebugSnapshot());
+}
+```
+
+`getDebugSnapshot()` é público; não use `getDebugServices()` (interno).
+
+`DEFAULT_PIXEL_CONFIG` permanece disponível para inspeção e configuração avançada — não é necessário espalhá-lo numa integração comum.
+
+## Próximos passos
+
+- [Configuração](../configuration/overview.md)
+- [Transport](../configuration/transport.md)
+- [Catálogo de eventos](../events/catalog.md)
+- [Funil checkout](../guides/funnel-checkout.md)
+- [React / Next.js](./react-nextjs.md)

package/docs/public/getting-started/react-nextjs.md

@@ -0,0 +1,78 @@
+# React e Next.js (App Router)
+
+O pacote recomendado é [`@beworke/pixel-react`](../../../../pixel-react/README.md): `PixelProvider` + `usePixel` sobre `bootstrapPixel`.
+
+Esta camada **não** duplica `lead` / `purchase` no Context. O hook devolve a instância real de `Pixel`. O playground Next Bemony continua na integração de domínio e **não** usa este pacote genérico.
+
+## Instalação
+
+```bash
+pnpm add @beworke/pixel-react@rc @beworke/pixel@rc
+```
+
+## Provider
+
+```tsx
+'use client';
+
+import { PixelProvider } from '@beworke/pixel-react';
+import type { PixelSettings } from '@beworke/pixel';
+
+const settings = {
+  identity: { pixelId: 'pix_YOUR_ID' },
+} satisfies PixelSettings;
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <PixelProvider settings={settings}>{children}</PixelProvider>;
+}
+```
+
+`settings` é `PixelSettings`. Somente `identity.pixelId` é obrigatório; o Core resolve o restante.
+
+## Hook
+
+```tsx
+'use client';
+
+import { usePixel } from '@beworke/pixel-react';
+
+export function LeadButton() {
+  const { pixel, ready, status, error } = usePixel();
+
+  if (status === 'initializing') {
+    return <span>Inicializando...</span>;
+  }
+
+  if (error) {
+    return <span>Falha ao inicializar o Pixel.</span>;
+  }
+
+  return (
+    <button
+      disabled={!ready}
+      onClick={() => {
+        pixel?.lead({ email: 'user@example.com' });
+      }}
+    >
+      Enviar lead
+    </button>
+  );
+}
+```
+
+## SSR
+
+- `PixelProvider` é Client Component (`'use client'`).
+- O `layout.tsx` pode permanecer Server Component.
+- Importar o pacote não acessa `window`.
+- Bootstrap só no `useEffect` do cliente.
+
+## Strict Mode e múltiplos Providers
+
+Vários Providers na mesma `window` compartilham a instância. Strict Mode (mount → cleanup → mount) não destrói a instância reutilizada; o último unmount real destrói o bootstrap.
+
+`settings` é capturado na montagem. Reinit dinâmico está fora do MVP.
+
+## Alternativa: instância local
+
+Apps que precisam de uma instância isolada (sem singleton da `window`) podem continuar usando `createPixel` ou `new Pixel(settings)` num `useEffect` próprio. Nesse caso o app é dono de `destroy()`.

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

@@ -0,0 +1,94 @@
+# Script tag (IIFE / global)
+
+## Build
+
+O subpath `@beworke/pixel/global` expõe um bundle IIFE autossuficiente.
+
+Após o build, o artefato recomendado é `dist/browser/pixel.global.js`. O bundle legado `dist/v2/global.global.js` (`window.PixelV2`) permanece para compatibilidade.
+
+Carregar o script **apenas registra** a API. Não há auto-init, leitura de `document.currentScript` nem atributos `data-*`.
+
+## Presets BuyGoods (sem configuração)
+
+Para landing e checkout BuyGoods o integrador **só inclui o script**. `pixelId`, `subid4`, UTMs e detectores já vêm internos.
+
+```html
+<!-- Landing: gera subid4 e decora todos os links -->
+<script src="https://unpkg.com/@beworke/pixel@latest/dist/browser/pixel.buygoods-landing.global.js"></script>
+
+<!-- Checkout: lê subid4, ATC, ADD_PAYMENT_INFO, heartbeat (sobe para window.top) -->
+<script src="https://unpkg.com/@beworke/pixel@latest/dist/browser/pixel.buygoods-checkout.global.js"></script>
+```
+
+Não chame `Pixel({...})` nessas páginas. O preset auto-inicializa.
+
+## HTML mínimo (`type="module"`)
+
+Top-level `await` exige `type="module"`.
+
+```html
+<!DOCTYPE html>
+<html lang="pt-BR">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Pixel — script tag</title>
+    <script src="https://unpkg.com/@beworke/pixel@rc/dist/browser/pixel.global.js"></script>
+  </head>
+  <body>
+    <button id="lead-button" type="button">Enviar lead</button>
+    <script type="module">
+      const pixel = await Pixel({
+        identity: { pixelId: 'pix_YOUR_ID' },
+      });
+
+      document.getElementById('lead-button').addEventListener('click', () => {
+        pixel.lead({ email: 'user@example.com' });
+      });
+    </script>
+  </body>
+</html>
+```
+
+## Script clássico (sem top-level await)
+
+```html
+<script>
+  Pixel({
+    identity: {
+      pixelId: 'pix_YOUR_ID',
+    },
+  })
+    .then(function (pixel) {
+      pixel.lead({ email: 'user@example.com' });
+    })
+    .catch(function (error) {
+      console.error(error);
+    });
+</script>
+```
+
+## API global
+
+```js
+await Pixel(settings); // bootstrap (uma instância por window)
+await Pixel.create(settings); // instância independente
+await Pixel.bootstrap(settings, { force: true, waitForConsent });
+Pixel.getInstance();
+Pixel.getPending();
+await Pixel.destroy();
+new Pixel.Client(settings); // classe; o construtor resolve PixelSettings
+Pixel.DEFAULT_PIXEL_CONFIG; // inspeção / configuração avançada
+```
+
+`window.PixelV2` continua como compatibilidade / baixo nível (`Pixel`, `DEFAULT_PIXEL_CONFIG`, `resolveStorageAdapterName`, `createPixel`, `bootstrap`, `getInstance`, `destroy`).
+
+## Exemplos no monorepo
+
+- `apps/playground-html/example-global-factory.html`
+- `apps/playground-html/example-global-factory-classic.html`
+
+## Limitações
+
+- TypeScript/IDE não inferem tipos no global — use JSDoc ou migre para npm ESM em apps maiores.
+- A aplicação controla **quando** chamar `Pixel(settings)` após consentimento.
+- Não declare conformidade LGPD/GDPR/CCPA apenas por usar este bundle.

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

@@ -0,0 +1,52 @@
+# Funil — Checkout
+
+## Objetivo
+
+Rastrear início de checkout, carrinho, pagamento e compra.
+
+## Config
+
+- catálogo de produtos em `commerce.catalog` (enrichment já está on por default)
+- `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,70 @@
+# Funil — Landing
+
+## Objetivo
+
+Medir visita, comportamento na página e leads antes do checkout.
+
+## Config recomendada
+
+```typescript
+import { DEFAULT_TRANSPORT_CONFIG } from '@beworke/pixel/config';
+
+transport: {
+  ...DEFAULT_TRANSPORT_CONFIG,
+  enabled: true,
+  sender: { mode: 'internal' },
+},
+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 },
+    },
+  },
+},
+```
+
+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 sender (`internal`/`external`) 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 `test` | Habilitar Transport + sender `internal`/`external` |
+| 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.