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

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,33 @@
+# Limitações conhecidas do RC
+
+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 — 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 |
+| APIs `@internal` | Playgrounds only — não suportadas publicamente |
+
+## Config / defaults
+
+| Limitação | Detalhe |
+|-----------|---------|
+| `modules.behavior.enabled` | `false` por default — habilitar explicitamente |
+| `modules.conversion.auto` | Auto detectors e rules continuam off; só a API manual vem ligada |
+| Sessão | Persistência default em `sessionStorage` |
+
+## 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 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**.
+- 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(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.
+
+## 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 = await createPixel(createConfig());
+}
+
+// Antes do consentimento: não chamar Pixel(settings) / createPixel() / 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
+
+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-<versão>.tgz
+```
+
+## Checklist rápido
+
+- [ ] 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/`
+
+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,56 @@
+# Troubleshooting
+
+## Nenhum evento chega na API
+
+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
+
+- 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](./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.1",
+  "version": "0.1.0-rc.11",
   "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,22 @@
       "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"
+    },
+    "./buygoods-landing": {
+      "default": "./dist/browser/pixel.buygoods-landing.global.js"
+    },
+    "./buygoods-checkout": {
+      "default": "./dist/browser/pixel.buygoods-checkout.global.js"
+    },
+    "./internal-checkout": {
+      "default": "./dist/browser/pixel.internal-checkout.global.js"
     },
     "./config": {
       "types": "./dist/config/index.d.ts",
@@ -47,26 +61,11 @@
   },
   "files": [
     "dist",
+    "docs/public",
     "README.md",
     "CHANGELOG.md",
     "RELEASE_CANDIDATE.md"
   ],
-  "scripts": {
-    "dev": "tsup --watch",
-    "build": "tsup",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:smoke:real": "node ./scripts/run-smoke-real.mjs",
-    "validate:rc-package": "node ./scripts/validate-rc-package.mjs",
-    "lint": "eslint src --ext .ts,.tsx",
-    "lint:fix": "eslint src --ext .ts,.tsx --fix",
-    "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"
-  },
   "keywords": [
     "pixel",
     "tracking",
@@ -80,9 +79,10 @@
   ],
   "author": "",
   "license": "ISC",
-  "packageManager": "pnpm@10.7.1",
+  "publishConfig": {
+    "access": "public"
+  },
   "devDependencies": {
-    "@changesets/cli": "^2.29.7",
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^6.0.0",
     "@typescript-eslint/parser": "^6.0.0",
@@ -91,11 +91,32 @@
     "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"
   },
   "dependencies": {
     "ua-parser-js": "^2.0.6"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "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": "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",
+    "test:chaos": "vitest run src/transport/transport.resilience.test.ts src/transport/transport.advanced.test.ts",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix",
+    "format": "prettier --write src/**/*.{ts,tsx,js,jsx,json,css,md}",
+    "type-check": "tsc --noEmit",
+    "clean": "rimraf dist coverage"
   }
 }

package/dist/index-DUfFzniE.d.mts

@@ -1,274 +0,0 @@
-type AttributionIdentifiers = {
-    readonly fbclid?: string;
-    readonly fbp?: string;
-    readonly fbc?: string;
-    readonly gclid?: string;
-    readonly gbraid?: string;
-    readonly wbraid?: string;
-    readonly ga?: string;
-    readonly gid?: string;
-    readonly gclAu?: string;
-    readonly ttclid?: string;
-    readonly ttp?: string;
-    readonly msclkid?: string;
-    readonly liFatId?: string;
-    readonly epik?: string;
-    readonly customClickIds?: Readonly<Record<string, string>>;
-    readonly firstCollectedAt?: number;
-    readonly lastCollectedAt?: number;
-    readonly landingUrl?: string;
-    readonly referrer?: string;
-};
-type AttributionConfig = {
-    readonly enabled: boolean;
-    readonly ttlDays?: number;
-    readonly persist?: boolean;
-    readonly captureUrlParams?: boolean;
-    readonly captureCookies?: boolean;
-    readonly customClickIdParams?: string[];
-};
-declare const DEFAULT_ATTRIBUTION_CONFIG: AttributionConfig;
-declare const ATTRIBUTION_STORAGE_KEY = "attribution";
-interface AttributionService {
-    init(): void;
-    destroy(): void;
-    collect(): AttributionIdentifiers;
-    getSnapshot(): AttributionIdentifiers;
-    update(partial: Partial<AttributionIdentifiers>): AttributionIdentifiers;
-    clear(): void;
-}
-
-interface BasePixelEvent {
-    readonly type: string;
-    readonly timestamp: number;
-    readonly path?: string;
-    readonly url?: string;
-    readonly hostname?: string;
-    readonly language?: string;
-    readonly timezone?: string;
-    /** Attribution click IDs / cookies — anexados pelo BaseEventBuilder. */
-    readonly identifiers?: AttributionIdentifiers;
-}
-
-interface PageViewEvent extends BasePixelEvent {
-    readonly type: 'PAGE_VIEW';
-}
-
-type PixelEventCategory = 'ENGAGEMENT' | 'CONVERSION' | 'IDENTITY' | 'SESSION' | 'SYSTEM' | 'INTEGRATION';
-type EngagementEventCategory = 'ENGAGEMENT';
-type ConversionEventCategory = 'CONVERSION';
-
-interface ScrollEvent extends BasePixelEvent {
-    readonly type: 'SCROLL';
-    readonly category: EngagementEventCategory;
-    readonly maxScrollPercent: number;
-    readonly scrollEvents: number;
-    readonly scrollVelocityAvg?: number;
-    readonly lastScrollAt?: number;
-}
-
-interface ElementDescriptor {
-    readonly tagName?: string;
-    readonly id?: string;
-    readonly classes?: string[];
-    readonly text?: string;
-    readonly role?: string;
-    readonly name?: string;
-    readonly dataset?: Record<string, string>;
-}
-
-interface PageClickEvent extends BasePixelEvent {
-    readonly type: 'PAGE_CLICK';
-    readonly category: EngagementEventCategory;
-    readonly clickCount: number;
-    readonly lastClickAt: number;
-    readonly rageClickCount?: number;
-    readonly target?: ElementDescriptor;
-    readonly currentTarget?: ElementDescriptor;
-    readonly clientX?: number;
-    readonly clientY?: number;
-    readonly pageX?: number;
-    readonly pageY?: number;
-    readonly offsetX?: number;
-    readonly offsetY?: number;
-}
-
-interface RageClickEvent extends BasePixelEvent {
-    readonly type: 'RAGE_CLICK';
-    readonly category: EngagementEventCategory;
-    readonly threshold: number;
-    readonly windowMs: number;
-    readonly clickCount: number;
-    readonly target?: ElementDescriptor;
-}
-
-interface VisibilityChangeEvent extends BasePixelEvent {
-    readonly type: 'VISIBILITY_CHANGE';
-    readonly category: EngagementEventCategory;
-    readonly isVisible: boolean;
-    readonly visibleSince?: number;
-    readonly hiddenAt?: number | null;
-}
-
-interface UserIdleEvent extends BasePixelEvent {
-    readonly type: 'USER_IDLE';
-    readonly category: EngagementEventCategory;
-    readonly idleSince: number;
-    readonly thresholdMs: number;
-}
-
-interface UserActiveEvent extends BasePixelEvent {
-    readonly type: 'USER_ACTIVE';
-    readonly category: EngagementEventCategory;
-    readonly activeAt: number;
-    readonly previousIdleDurationMs?: number;
-}
-
-interface ExitIntentEvent extends BasePixelEvent {
-    readonly type: 'EXIT_INTENT';
-    readonly category: EngagementEventCategory;
-    readonly triggeredAt: number;
-    readonly clientY?: number;
-}
-
-interface SessionRenewedEvent extends BasePixelEvent {
-    readonly type: 'SESSION_RENEWED';
-    readonly sessionId: string;
-    readonly previousSessionId?: string;
-}
-
-interface SessionExpiredEvent extends BasePixelEvent {
-    readonly type: 'SESSION_EXPIRED';
-    readonly sessionId: string;
-}
-
-interface PixelItem {
-    readonly id?: string;
-    readonly name?: string;
-    readonly category?: string;
-    readonly price?: number;
-    readonly quantity?: number;
-}
-interface PurchaseData {
-    readonly value?: number;
-    readonly currency?: string;
-    readonly orderId?: string;
-    readonly items?: PixelItem[];
-}
-interface LeadData {
-    readonly email?: string;
-    readonly phone?: string;
-    readonly name?: string;
-    readonly fields?: Record<string, unknown>;
-}
-interface AddToCartData {
-    readonly productId?: string;
-    readonly productName?: string;
-    readonly price?: number;
-    readonly currency?: string;
-    readonly quantity?: number;
-}
-interface RemoveFromCartData {
-    readonly productId?: string;
-    readonly quantity?: number;
-}
-interface InitiateCheckoutData {
-    readonly value?: number;
-    readonly currency?: string;
-    readonly items?: PixelItem[];
-}
-type PaymentMethod = 'CREDIT_CARD' | 'PIX' | 'BOLETO' | 'PAYPAL' | 'OTHER';
-interface AddPaymentInfoData {
-    readonly paymentMethod?: PaymentMethod;
-}
-interface ViewContentData {
-    readonly contentId?: string;
-    readonly contentType?: string;
-    readonly category?: string;
-    readonly value?: number;
-    readonly currency?: string;
-}
-interface SearchData {
-    readonly query: string;
-}
-type ConversionEventData = PurchaseData | LeadData | AddToCartData | RemoveFromCartData | InitiateCheckoutData | AddPaymentInfoData | ViewContentData | SearchData;
-
-interface PurchaseEvent extends BasePixelEvent {
-    readonly type: 'PURCHASE';
-    readonly category: ConversionEventCategory;
-    readonly data: PurchaseData;
-}
-
-interface LeadEvent extends BasePixelEvent {
-    readonly type: 'LEAD';
-    readonly category: ConversionEventCategory;
-    readonly data: LeadData;
-}
-
-interface AddToCartEvent extends BasePixelEvent {
-    readonly type: 'ADD_TO_CART';
-    readonly category: ConversionEventCategory;
-    readonly data: AddToCartData;
-}
-
-interface RemoveFromCartEvent extends BasePixelEvent {
-    readonly type: 'REMOVE_FROM_CART';
-    readonly category: ConversionEventCategory;
-    readonly data: RemoveFromCartData;
-}
-
-interface InitiateCheckoutEvent extends BasePixelEvent {
-    readonly type: 'INITIATE_CHECKOUT';
-    readonly category: ConversionEventCategory;
-    readonly data: InitiateCheckoutData;
-}
-
-interface AddPaymentInfoEvent extends BasePixelEvent {
-    readonly type: 'ADD_PAYMENT_INFO';
-    readonly category: ConversionEventCategory;
-    readonly data: AddPaymentInfoData;
-}
-
-interface ViewContentEvent extends BasePixelEvent {
-    readonly type: 'VIEW_CONTENT';
-    readonly category: ConversionEventCategory;
-    readonly data: ViewContentData;
-}
-
-interface SearchEvent extends BasePixelEvent {
-    readonly type: 'SEARCH';
-    readonly category: ConversionEventCategory;
-    readonly data: SearchData;
-}
-
-type PixelEvent = PageViewEvent | SessionRenewedEvent | SessionExpiredEvent | ScrollEvent | PageClickEvent | RageClickEvent | VisibilityChangeEvent | UserIdleEvent | UserActiveEvent | ExitIntentEvent | PurchaseEvent | LeadEvent | AddToCartEvent | RemoveFromCartEvent | InitiateCheckoutEvent | AddPaymentInfoEvent | ViewContentEvent | SearchEvent;
-
-interface BrowserMetadata {
-    readonly url?: string;
-    readonly path?: string;
-    readonly hostname?: string;
-    readonly origin?: string;
-    readonly title?: string;
-    readonly referrer?: string;
-    readonly language?: string;
-    readonly timezone?: string;
-    readonly userAgent?: string;
-    readonly platform?: string;
-    readonly screenWidth?: number;
-    readonly screenHeight?: number;
-    readonly colorDepth?: number;
-}
-interface BrowserMetadataService {
-    getMetadata(): BrowserMetadata;
-}
-
-declare class BaseEventBuilder {
-    private readonly metadataService;
-    private readonly attribution;
-    constructor(metadataService: BrowserMetadataService, attribution?: AttributionService | null);
-    build<T extends {
-        type: string;
-    }>(event: T): T & BasePixelEvent;
-}
-
-export { type AttributionService as A, type BrowserMetadataService as B, type ConversionEventData as C, DEFAULT_ATTRIBUTION_CONFIG as D, type ExitIntentEvent as E, type PixelEventCategory as F, type EngagementEventCategory as G, type ConversionEventCategory as H, type InitiateCheckoutData as I, type ElementDescriptor as J, type LeadData as L, type PixelEvent as P, type RemoveFromCartData as R, type SessionRenewedEvent as S, type UserIdleEvent as U, type ViewContentData as V, BaseEventBuilder as a, type AttributionConfig as b, type AttributionIdentifiers as c, type BrowserMetadata as d, type BasePixelEvent as e, type PageViewEvent as f, type SessionExpiredEvent as g, ATTRIBUTION_STORAGE_KEY as h, type PurchaseData as i, type AddToCartData as j, type AddPaymentInfoData as k, type SearchData as l, type ScrollEvent as m, type PageClickEvent as n, type RageClickEvent as o, type VisibilityChangeEvent as p, type UserActiveEvent as q, type PurchaseEvent as r, type LeadEvent as s, type AddToCartEvent as t, type RemoveFromCartEvent as u, type InitiateCheckoutEvent as v, type AddPaymentInfoEvent as w, type ViewContentEvent as x, type SearchEvent as y, type PixelItem as z };