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

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

@@ -1,55 +1,78 @@
 # React e Next.js (App Router)
 
-O SDK não exporta hooks React. O padrão recomendado é um hook **local** no app.
+O pacote recomendado é [`@beworke/pixel-react`](../../../../pixel-react/README.md): `PixelProvider` + `usePixel` sobre `bootstrapPixel`.
 
-## Hook local (`usePixel`)
+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.
 
-Referência: `apps/playground-next/lib/use-pixel.ts`
+## Instalação
 
-```typescript
-'use client';
-
-import { Pixel } from '@beworke/pixel';
-import { useEffect, useRef, useState } from 'react';
-import { createPixelConfig } from './pixel-config';
+```bash
+pnpm add @beworke/pixel-react@rc @beworke/pixel@rc
+```
 
-export function usePixel() {
-  const pixelRef = useRef<Pixel | null>(null);
-  const [ready, setReady] = useState(false);
+## Provider
 
-  useEffect(() => {
-    const pixel = new Pixel(createPixelConfig());
-    pixelRef.current = pixel;
+```tsx
+'use client';
 
-    pixel.init().then(() => setReady(true));
+import { PixelProvider } from '@beworke/pixel-react';
+import type { PixelSettings } from '@beworke/pixel';
 
-    return () => {
-      void pixel.destroy();
-      pixelRef.current = null;
-      setReady(false);
-    };
-  }, []);
+const settings = {
+  identity: { pixelId: 'pix_YOUR_ID' },
+} satisfies PixelSettings;
 
-  return { pixel: pixelRef, ready };
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <PixelProvider settings={settings}>{children}</PixelProvider>;
 }
 ```
 
-## Config por página/funil
+`settings` é `PixelSettings`. Somente `identity.pixelId` é obrigatório; o Core resolve o restante.
+
+## Hook
 
-Centralize em `createPixelConfig()` (`apps/playground-next/lib/pixel-config.ts`):
+```tsx
+'use client';
 
-- `identity.funnelId`, `funnelStepId`, `pageId` por etapa do funil
-- `commerce.catalog` para produtos da oferta
-- `storage.persistence` com `sessionStorage` para sessão sobreviver a reloads
+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
 
-- Instancie `Pixel` apenas no cliente (`'use client'`).
-- Não chame `init()` no servidor.
-- `destroy()` no unmount evita listeners duplicados.
+- `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.
 
-## Checkout
+`settings` é capturado na montagem. Reinit dinâmico está fora do MVP.
 
-`apps/playground-next/app/checkout/page.tsx` demonstra `initiateCheckout`, `addPaymentInfo`, `purchase` com catálogo commerce.
+## Alternativa: instância local
 
-Guia: [Funil checkout](../guides/funnel-checkout.md).
+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

@@ -2,11 +2,15 @@
 
 ## Build
 
-O subpath `@beworke/pixel/global` expõe um bundle IIFE que define `window.PixelV2`.
+O subpath `@beworke/pixel/global` expõe um bundle IIFE autossuficiente.
 
-Após `npm run build`, o artefato está em `dist/global/` (nome conforme `tsup` / `package.json`).
+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.
 
-## HTML mínimo
+Carregar o script **apenas registra** a API. Não há auto-init, leitura de `document.currentScript` nem atributos `data-*`.
+
+## HTML mínimo (`type="module"`)
+
+Top-level `await` exige `type="module"`.
 
 ```html
 <!DOCTYPE html>
@@ -14,44 +18,63 @@ Após `npm run build`, o artefato está em `dist/global/` (nome conforme `tsup`
   <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>
-    <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
-      })();
+    <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>
 ```
 
-## Exemplo público
+## 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
 
-Veja `apps/playground-html/public/html/landing.html`.
+- `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.
-- Mesmas regras de privacidade: a aplicação controla **quando** chamar `init()` após consentimento.
+- 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

@@ -6,7 +6,7 @@ Rastrear início de checkout, carrinho, pagamento e compra.
 
 ## Config
 
-- `commerce.enabled: true` + catálogo de produtos
+- catálogo de produtos em `commerce.catalog` (enrichment já está on por default)
 - `identity.checkoutId`, `funnelStepId`
 - Transport API habilitado
 

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

@@ -7,6 +7,13 @@ 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 },
@@ -20,11 +27,6 @@ modules: {
       exitIntent: { enabled: true },
     },
   },
-  transport: {
-    ...DEFAULT_PIXEL_CONFIG.modules.transport,
-    enabled: true,
-    sender: { mode: 'api' },
-  },
 },
 ```
 
@@ -52,7 +54,7 @@ Opcional: `modules.conversion.auto` + detector `lead` com seletores do formulár
 
 ## QA
 
-- [ ] `pixelId` e `apiEndpoint` corretos
+- [ ] `pixelId` e sender (`internal`/`external`) corretos
 - [ ] Persistência `sessionStorage` para sessão
 - [ ] Um único `init()` por aba
 - [ ] `getDebugSnapshot()` mostra transport enviando (dev)
@@ -61,7 +63,7 @@ Opcional: `modules.conversion.auto` + detector `lead` com seletores do formulár
 
 | Problema | Causa | Solução |
 |----------|-------|---------|
-| Sem eventos na API | `transport.enabled: false` ou `sender.mode: 'mock'` | Habilitar transport + mode `api` |
+| 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()` |
 

package/docs/public/limitations.md

@@ -1,12 +1,13 @@
 # Limitações conhecidas do RC
 
-Versão: `0.1.0-rc.5` · Etapas 1–20 concluídas.
+A versão publicada está em `package.json`. Este documento descreve limitações do produto, não um número de RC.
 
 ## Produto
 
 | Limitação | Detalhe |
 |-----------|---------|
-| Consent / CMP | Incompleto — Etapa 25 |
+| Consent / CMP | Incompleto — a aplicação controla quando inicializar; `waitForConsent` é um gate opcional no bootstrap |
+| Auto-init | O bundle base **não** auto-inicializa ao ser carregado |
 | 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 |
@@ -17,8 +18,8 @@ Versão: `0.1.0-rc.5` · Etapas 1–20 concluídas.
 | 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` |
+| `modules.conversion.auto` | Auto detectors e rules continuam off; só a API manual vem ligada |
+| Sessão | Persistência default em `sessionStorage` |
 
 ## Distribuição
 

package/docs/public/privacy/limitations.md

@@ -1,14 +1,15 @@
 # Privacidade e consentimento (RC)
 
-## Estado do RC `0.1.0-rc.5`
+## Estado atual
 
 - **Não há Consent Gate / CMP completo** integrado ao SDK.
+- `bootstrapPixel(..., { waitForConsent })` e `PixelProvider` permitem abortar **antes** de criar a instância.
 - `modules.core.consent` e `modules.privacy.consent` existem na config mas **defaults desligados**.
-- Etapa **25 — Privacy/Consent** ainda não concluída.
+- O chamador controla o momento da inicialização. Este RC **não** declara conformidade LGPD/GDPR/CCPA.
 
 ## Responsabilidade da aplicação
 
-1. **Quando inicializar** — só chame `pixel.init()` após obter consentimento do usuário, se exigido pela sua política.
+1. **Quando inicializar** — só chame `Pixel(settings)`, `createPixel()` ou `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.
 
@@ -21,11 +22,10 @@
 
 ```typescript
 async function onUserConsentGranted() {
-  const pixel = new Pixel(createConfig());
-  await pixel.init();
+  const pixel = await createPixel(createConfig());
 }
 
-// Antes do consentimento: não instanciar ou não chamar init()
+// Antes do consentimento: não chamar Pixel(settings) / createPixel() / init()
 ```
 
 ## Próximos passos (roadmap)

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

@@ -22,19 +22,19 @@ Não use `pnpm --filter @beworke/pixel pack` como fluxo principal.
 
 ## Tarball
 
-Nome esperado: `artifacts/beworke-pixel-0.1.0-rc.6.tgz`  
+O nome do tarball segue a versão de `package.json` (veja `artifacts/latest-package.json`).  
 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
+npm install /caminho/para/artifacts/beworke-pixel-<versão>.tgz
 ```
 
 ## Checklist rápido
 
-- [ ] Exports `.`, `./global`, `./v2`, `./config`, `./events`, `./services`, `./runtime`, `./logger`
-- [ ] `window.PixelV2` no build global
+- [ ] Exports `.`, `./browser`, `./global`, `./v2`, `./config`, `./events`, `./services`, `./runtime`, `./logger`
+- [ ] `window.Pixel` (factory) e `window.PixelV2` (compat) 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/`

package/docs/public/troubleshooting.md

@@ -2,11 +2,12 @@
 
 ## 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
+1. Confirme `transport.enabled: true`
+2. Use `transport.sender.mode: 'internal'` ou `'external'` (`'test'` não acessa a rede)
+3. Em `internal`, confira o `baseUrl` opcional; sem ele, vale o endpoint público padrão
+4. Em `external`, confira `endpoints.event` e a política de batch
+5. Confirme `identity.pixelId`
+6. DevTools → Network: requisições ao endpoint
 
 ## `init()` falha ou trava
 
@@ -51,5 +52,5 @@ npm run validate:rc-package
 ## Links úteis
 
 - [Configuração](./configuration/overview.md)
-- [Transport module](./configuration/modules.md)
+- [Transport](./configuration/transport.md)
 - [Validação RC](./release-candidate/validation.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beworke/pixel",
-  "version": "0.1.0-rc.7",
+  "version": "0.1.0-rc.8",
   "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",
@@ -11,8 +11,13 @@
       "import": "./dist/index.esm.js",
       "require": "./dist/index.cjs.js"
     },
+    "./browser": {
+      "types": "./dist/browser/index.d.ts",
+      "import": "./dist/browser/index.esm.js",
+      "require": "./dist/browser/index.cjs.js"
+    },
     "./global": {
-      "default": "./dist/v2/global.global.js"
+      "default": "./dist/browser/pixel.global.js"
     },
     "./config": {
       "types": "./dist/config/index.d.ts",
@@ -61,7 +66,7 @@
     "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",
+    "publish:rc": "pnpm publish --access public --tag rc --no-git-checks && node -e \"require('child_process').execSync('npm dist-tag add @beworke/pixel@'+require('./package.json').version+' latest',{stdio:'inherit'})\"",
     "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",

package/dist/pixel-default-config-BDPUVHse.d.ts

@@ -1,5 +0,0 @@
-import { P as PixelConfig } from './pixel-2uL4LSyC.js';
-
-declare const DEFAULT_PIXEL_CONFIG: PixelConfig;
-
-export { DEFAULT_PIXEL_CONFIG as D };

package/dist/pixel-default-config-C5uLt52W.d.mts

@@ -1,5 +0,0 @@
-import { P as PixelConfig } from './pixel-DMwpppf_.mjs';
-
-declare const DEFAULT_PIXEL_CONFIG: PixelConfig;
-
-export { DEFAULT_PIXEL_CONFIG as D };