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

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @beworke/pixel
 
+## 0.1.0-rc.9 — app.source livre, platform e payload `app`
+
+### Added
+
+- `app.source` aceita os valores conhecidos (`pageus`, `gomarke`, `bemony`, `custom`) **e qualquer outra string** (ex.: `hwaffiliate`)
+- `app.platform` (default `''`; conhecido: `buygoods`; string livre ok)
+- Payload HTTP inclui `app` (`source`, `target`, `platform`, `environment`) no evento e no batch; os mesmos campos também vão em `meta`
+- Exemplo BuyGoods (`apps/playground-html/buygoods`) sobe o Pixel do iframe de Funnel Pixels para `window.top`
+
+### Changed
+
+- Checkout BuyGoods dispara `PAGE_VIEW` no init e desliga `INITIATE_CHECKOUT`
+
+## 0.1.0-rc.8 — factory, browser bootstrap, global callable
+
+### Added
+
+- `createPixel()` no entry principal (instâncias independentes)
+- Subpath `@beworke/pixel/browser` (`bootstrapPixel`, getters, destroy, `PixelBootstrapError`)
+- Bundle `dist/browser/pixel.global.js` com `window.Pixel(settings)` callable
+- Compatibilidade: `window.PixelV2` ganha `createPixel` / `bootstrap` / `getInstance` / `destroy`
+- Pacote `@beworke/pixel-react` (`PixelProvider` / `usePixel`)
+- `SDK_VERSION` centralizada e validada contra `package.json`
+- `PixelSettings` (input público parcial) + `resolvePixelConfig()` no construtor de `Pixel`
+- AutoTrack `selector` aceita `trigger: 'hover'` e `'visible'`; `viewContent` default liga os 3 em `[data-track="view_content"]`. `data-trigger` no HTML restringe o modo (`click` / `hover` / `visible`); sem o atributo, dispara nos 3
+- `PixelConfigurationError` para `pixelId` inválido
+
+### Fixed
+
+- `REMOVE_FROM_CART` usa a mesma janela de 500ms do `ADD_TO_CART` — add → remove → add → remove do mesmo produto volta a disparar
+- `force: true` durante pending destrói a instância anterior (generation token)
+- `window.PixelV2` continua disponível quando `window.Pixel` estrangeiro bloqueia o global
+
 ## 0.1.0-rc.6 — Public RC docs on npm + install fix
 
 ### Fixed

package/README.md

@@ -2,7 +2,7 @@
 
 SDK de analytics e conversão para web — implemente funis (landing, checkout, upsell, thank-you) em React, Next.js, SPA ou HTML puro **sem conhecer a arquitetura interna**.
 
-**Versão RC:** `0.1.0-rc.6` · **Etapas concluídas:** 1–20 · **Próxima etapa funcional:** 21 — Commerce Lifecycle
+A versão publicada está em `package.json`. Instale a tag `@rc` para receber a release candidate atual.
 
 ## Instalação (npm — sem token)
 
@@ -10,11 +10,9 @@ Pacote **público**. Qualquer dev instala **sem login** no npm:
 
 ```bash
 npm install @beworke/pixel@rc
-# ou versão fixa:
-npm install @beworke/pixel@0.1.0-rc.6
 ```
 
-> **Importante:** `npm install @beworke/pixel` sem tag usa `latest`. Use `@rc` ou `@0.1.0-rc.6` até alinhar tags.
+> **Importante:** `npm install @beworke/pixel` sem tag usa `latest`. Use `@rc` até alinhar tags.
 
 ## Documentação pública
 
@@ -22,59 +20,84 @@ O **npm não hospeda** arquivos `.md` como site (URLs tipo `npmjs.com/.../instal
 
 | Onde ler | Link |
 |----------|------|
-| **GitHub (recomendado no browser)** | [docs/public/README.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/README.md) |
+| **GitHub (recomendado no browser)** | [docs/public/README.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/README.md) |
 | **Após `npm install`** | `node_modules/@beworke/pixel/docs/public/` |
 
 | Guia | GitHub |
 |------|--------|
-| Instalação | [getting-started/installation.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/getting-started/installation.md) |
-| Quick start | [getting-started/quick-start.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/getting-started/quick-start.md) |
-| API Pixel | [api/pixel.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/api/pixel.md) |
-| Eventos | [events/catalog.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/events/catalog.md) |
-| Configuração | [configuration/overview.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/configuration/overview.md) |
-| Funis | [guides/funnel-full.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/guides/funnel-full.md) |
-| Privacidade (RC) | [privacy/limitations.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/privacy/limitations.md) |
-| Limitações | [limitations.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/limitations.md) |
+| Instalação | [getting-started/installation.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/getting-started/installation.md) |
+| Quick start | [getting-started/quick-start.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/getting-started/quick-start.md) |
+| API Pixel | [api/pixel.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/api/pixel.md) |
+| Eventos | [events/catalog.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/events/catalog.md) |
+| Configuração | [configuration/overview.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/configuration/overview.md) |
+| Funis | [guides/funnel-full.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/guides/funnel-full.md) |
+| Privacidade (RC) | [privacy/limitations.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/privacy/limitations.md) |
+| Limitações | [limitations.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/limitations.md) |
 
-Repositório: https://github.com/techionext/Pixel-Global
+Repositório: https://github.com/beworke-apps/Pixel-Global
 
-## Quick start
+## Três níveis de uso
+
+### HTML simples (script tag)
+
+Carregar o bundle **apenas registra** `window.Pixel`. Nada é inicializado até `Pixel(settings)` resolver. Top-level `await` exige `type="module"` (ou um IIFE/`then`).
+
+```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>
+```
+
+`Pixel(settings)` usa o bootstrap (uma instância por `window`). `window.PixelV2` permanece como compatibilidade / API de baixo nível.
+
+### NPM com factory
+
+`createPixel` cria **instâncias independentes** (não é singleton).
 
 ```typescript
-import { Pixel, DEFAULT_PIXEL_CONFIG } from '@beworke/pixel';
+import { createPixel } from '@beworke/pixel';
 
-const pixel = new Pixel({
-  ...DEFAULT_PIXEL_CONFIG,
+const pixel = await createPixel({
   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',
-    },
-  },
-  modules: {
-    ...DEFAULT_PIXEL_CONFIG.modules,
-    core: { ...DEFAULT_PIXEL_CONFIG.modules.core, enabled: true },
-    transport: {
-      ...DEFAULT_PIXEL_CONFIG.modules.transport,
-      enabled: true,
-      sender: { mode: 'api' },
-    },
-  },
 });
 
-await pixel.init();
 pixel.lead({ email: 'user@example.com' });
-pixel.purchase({ transactionId: 'ord_1', value: 197, currency: 'BRL' });
-await pixel.destroy();
 ```
 
+A classe continua disponível:
+
+```typescript
+import { Pixel } from '@beworke/pixel';
+
+const pixel = new Pixel({
+  identity: { pixelId: 'pix_YOUR_ID' },
+});
+await pixel.init();
+```
+
+### Browser avançado
+
+`bootstrapPixel` gerencia **uma instância por `window`**. Para trocar a configuração, destrua explicitamente ou use `force`. Chamadas concorrentes compartilham a configuração da primeira chamada.
+
+```typescript
+import { bootstrapPixel } from '@beworke/pixel/browser';
+
+const pixel = await bootstrapPixel(
+  {
+    identity: { pixelId: 'pix_YOUR_ID' },
+  },
+  {
+    waitForConsent: () => window.consentGranted === true,
+  }
+);
+```
+
+React: use [`@beworke/pixel-react`](../pixel-react/README.md) (`PixelProvider` / `usePixel`).
+
 ## Métodos públicos
 
 | Método | Descrição |
@@ -84,27 +107,19 @@ await pixel.destroy();
 | `purchase`, `lead`, `addToCart`, `removeFromCart` | Conversão |
 | `initiateCheckout`, `addPaymentInfo`, `viewContent`, `search` | Conversão |
 
-Detalhes: [api/pixel.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/api/pixel.md)
-
-## Script tag (CDN)
-
-```html
-<script src="https://unpkg.com/@beworke/pixel@rc/dist/v2/global.global.js"></script>
-<script>
-  const { Pixel, DEFAULT_PIXEL_CONFIG } = window.PixelV2;
-</script>
-```
+Detalhes: [api/pixel.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/api/pixel.md)
 
-Global oficial: **`window.PixelV2`**.
+Métodos internos de playground (`@internal`) **não** são API pública.
 
 ## Limitações do RC
 
-- Sem Consent Gate / CMP completo — a aplicação controla quando chamar `init()`
+- O bundle **não** auto-inicializa; a aplicação controla quando chamar `Pixel(settings)` / `init()`
+- Consent gate opcional no bootstrap — a aplicação decide quando há consentimento suficiente
 - Não declarar GDPR/LGPD/CCPA compliant com este RC
 - Sem eventos dedicados upsell/downsell — use `VIEW_CONTENT` + `PURCHASE`
 
-Lista: [limitations.md](https://github.com/techionext/Pixel-Global/blob/main/packages/pixel/docs/public/limitations.md)
+Lista: [limitations.md](https://github.com/beworke-apps/Pixel-Global/blob/main/packages/pixel/docs/public/limitations.md)
 
 ## Contribuidores
 
-Arquitetura interna: [PLAN_PIXEL/ARCHITECTURE.md](https://github.com/techionext/Pixel-Global/blob/main/PLAN_PIXEL/ARCHITECTURE.md) · Playgrounds: `apps/playground-html/` no monorepo.
+Arquitetura interna: [PLAN_PIXEL/ARCHITECTURE.md](https://github.com/beworke-apps/Pixel-Global/blob/main/PLAN_PIXEL/ARCHITECTURE.md) · Playgrounds: `apps/playground-html/` no monorepo.

package/RELEASE_CANDIDATE.md

@@ -1,7 +1,7 @@
 # Pixel v2 — Release Candidate Notes
 
 **Pacote:** `@beworke/pixel`  
-**Versão:** `0.1.0-rc.5` (release candidate)  
+**Versão:** consulte `package.json` (fonte de verdade; este arquivo é histórico do RC)  
 **Data:** 2026-07-14  
 **Status 20:** **Concluída** — Runtime Intelligence · [`PLAN_PIXEL/PIXEL_V2_STAGE_20_REPORT.md`](../../../PLAN_PIXEL/PIXEL_V2_STAGE_20_REPORT.md)
 
@@ -104,58 +104,24 @@ node scripts/validate-rc-package.mjs artifacts/beworke-pixel-0.1.0-rc.6.tgz
 ## 4. Como usar via import (ESM)
 
 ```ts
-import { Pixel, DEFAULT_PIXEL_CONFIG } from '@beworke/pixel';
+import { createPixel } from '@beworke/pixel';
 
-const pixel = new Pixel({
-  ...DEFAULT_PIXEL_CONFIG,
-  identity: {
-    ...DEFAULT_PIXEL_CONFIG.identity,
-    pixelId: 'pix_xxx',
-  },
-  transport: {
-    ...DEFAULT_PIXEL_CONFIG.transport,
-    apiEndpoint: 'https://sua-api.example.com',
-  },
-  modules: {
-    ...DEFAULT_PIXEL_CONFIG.modules,
-    core: {
-      ...DEFAULT_PIXEL_CONFIG.modules.core,
-      enabled: true,
-      pageView: {
-        ...DEFAULT_PIXEL_CONFIG.modules.core.pageView,
-        enabled: true,
-        trackInitialPageView: true,
-      },
-    },
-    conversion: {
-      ...DEFAULT_PIXEL_CONFIG.modules.conversion,
-      enabled: true,
-      manual: {
-        ...DEFAULT_PIXEL_CONFIG.modules.conversion.manual,
-        lead: { enabled: true },
-        purchase: { enabled: true },
-      },
-    },
-    transport: {
-      ...DEFAULT_PIXEL_CONFIG.modules.transport,
-      enabled: true,
-      mockSender: { enabled: false },
-      sender: { mode: 'http' },
-    },
-  },
+const pixel = await createPixel({
+  identity: { pixelId: 'pix_xxx' },
 });
 
-await pixel.init();
 // PAGE_VIEW: emitido pelo Core (trackInitialPageView) — não existe pixel.pageView()
 pixel.lead({ email: 'user@example.com' });
 pixel.purchase({ orderId: '1', value: 99.9, currency: 'BRL' });
 await pixel.destroy();
 ```
 
+Overrides parciais e `PixelConfig` completo continuam válidos. `DEFAULT_PIXEL_CONFIG` permanece para inspeção avançada.
+
 ### CJS
 
 ```js
-const { Pixel, DEFAULT_PIXEL_CONFIG } = require('@beworke/pixel');
+const { createPixel } = require('@beworke/pixel');
 ```
 
 ### Subpath `/v2`
@@ -168,24 +134,20 @@ import { Pixel } from '@beworke/pixel/v2';
 
 ## 5. Como usar via script tag
 
-Bundle IIFE: `dist/v2/global.global.js` → **`window.PixelV2`**
+Bundle recomendado: `dist/browser/pixel.global.js` → **`window.Pixel(settings)`**
 
 ```html
-<script src="./node_modules/@beworke/pixel/dist/v2/global.global.js"></script>
-<script>
-  const { Pixel, DEFAULT_PIXEL_CONFIG } = window.PixelV2;
-  const pixel = new Pixel({
-    ...DEFAULT_PIXEL_CONFIG,
-    identity: { ...DEFAULT_PIXEL_CONFIG.identity, pixelId: 'pix_xxx' },
-    transport: {
-      ...DEFAULT_PIXEL_CONFIG.transport,
-      apiEndpoint: 'https://sua-api.example.com',
-    },
+<script src="./node_modules/@beworke/pixel/dist/browser/pixel.global.js"></script>
+<script type="module">
+  const pixel = await Pixel({
+    identity: { pixelId: 'pix_xxx' },
   });
-  pixel.init();
+  pixel.lead({ email: 'user@example.com' });
 </script>
 ```
 
+`window.PixelV2` permanece como compatibilidade / API de baixo nível.
+
 Export npm: `@beworke/pixel/global`.
 
 ---
@@ -193,20 +155,24 @@ Export npm: `@beworke/pixel/global`.
 ## 6. Transport real
 
 ```ts
-modules: {
-  transport: {
+transport: {
+  ...DEFAULT_TRANSPORT_CONFIG,
+  enabled: true,
+  sender: {
+    mode: 'internal',
+    baseUrl: process.env.PIXEL_API_ENDPOINT,
+  },
+  batch: {
+    ...DEFAULT_TRANSPORT_CONFIG.batch,
     enabled: true,
-    mockSender: { enabled: false },
-    sender: { mode: 'http' },
-    batch: { enabled: true, batchSize: 1 }, // Event
-    // batchSize: 10 → Batch
+    batchSize: 1, // Event; use 10 para Batch
   },
 },
-transport: {
-  apiEndpoint: process.env.PIXEL_API_ENDPOINT, // não hardcodar em produção
-},
 ```
 
+Para sender `test`, `internal` sem `baseUrl` e `external`, consulte
+[`docs/public/configuration/transport.md`](./docs/public/configuration/transport.md).
+
 Endpoints oficiais do SDK:
 
 ```txt