npm - cdp-edge - Versions diffs - 1.2.0 - Mend

cdp-edge 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (128) hide show

package/docs/sdk-reference.md ADDED Viewed

@@ -0,0 +1,371 @@
+# CDP Edge — SDK Reference
+> API pública do `cdpTrack.js` — todas as funções, parâmetros e exemplos.
+---
+## Instalação
+```html
+<!-- No <head> -->
+<script type="module">
+  import { init } from '/js/cdpTrack.js';
+  await init();
+</script>
+```
+Após `init()`, todas as funções ficam disponíveis em `window.cdpTrack`.
+---
+## init()
+Inicializa o SDK completo. Deve ser chamado uma vez por página.
+```javascript
+import { init } from '/js/cdpTrack.js';
+await init();
+```
+**O que faz internamente:**
+1. Google Consent Mode v2 (defaults negados — LGPD compliant)
+2. Anti-blocking (retry automático com beacon fallback)
+3. Micro-events (scroll, tempo, vídeo, clique, hover)
+4. Auto-captura de formulários de lead
+5. Salva contexto de afiliado no localStorage (UTM resurrection)
+6. passCheckoutParams (injeta `_cdp_uid` nos links de checkout)
+7. Behavior Engine (scoring avançado)
+---
+## track(eventName, data?)
+Função principal. Envia qualquer evento para o Worker.
+```javascript
+await window.cdpTrack.track('EventName', {
+  // dados do evento
+});
+```
+**Parâmetros:**
+| Parâmetro | Tipo | Descrição |
+|---|---|---|
+| `eventName` | `string` | Nome do evento (ver Events Reference) |
+| `data` | `object` | Dados do evento (opcional) |
+**O que é enviado automaticamente** (sem precisar passar):
+- `event_id` — UUID único gerado no browser
+- `user_id` — `_cdp_uid` (cookie first-party)
+- `session_id` — sessionStorage ID
+- `utms` — utm_source, utm_medium, utm_campaign, utm_content, utm_term
+- `click_ids` — fbp, fbc, gclid, wbraid, gbraid, ttclid, rclid
+- `page_url` — `window.location.href`
+- `referrer` — `document.referrer`
+- `user_agent` — `navigator.userAgent`
+- `behavioral_data` — engagement score completo
+**Retorno:**
+```javascript
+{
+  success: true,
+  event_id: "1711234567890_abc123def",
+  result: { ... }
+}
+// ou em caso de erro:
+{
+  success: false,
+  error: "mensagem de erro",
+  event_id: "...",
+  attempts: 3
+}
+```
+---
+## trackLead(userData, form?)
+Atalho para captura de lead. Aceita dados crus — o Worker faz SHA256.
+```javascript
+await window.cdpTrack.trackLead({
+  email: 'fulano@exemplo.com',
+  phone: '11999998888',
+  firstName: 'João',
+  lastName: 'Silva'
+});
+// Com formulário HTML (extrai campos automaticamente)
+const form = document.querySelector('#form-lead');
+await window.cdpTrack.trackLead({}, form);
+```
+**Parâmetros aceitos:**
+| Campo | Tipo | Normalização automática |
+|---|---|---|
+| `email` | string | lowercase + trim |
+| `phone` | string | DDI 55 + somente dígitos |
+| `firstName` | string | Title Case |
+| `lastName` | string | Title Case |
+| `city` | string | lowercase + sem acentos |
+| `state` | string | uppercase |
+| `zip` | string | somente dígitos |
+| `country` | string | lowercase |
+---
+## trackPurchase(orderData)
+Atalho para compra confirmada.
+```javascript
+await window.cdpTrack.trackPurchase({
+  value: 297.00,
+  currency: 'BRL',
+  order_id: 'ORD-12345',
+  email: 'fulano@exemplo.com',
+  content_name: 'Curso XYZ',
+  content_ids: ['SKU-001']
+});
+```
+---
+## trackViewContent(contentData)
+Visualização de produto ou oferta.
+```javascript
+await window.cdpTrack.trackViewContent({
+  content_name: 'Página de Vendas — Curso XYZ',
+  content_type: 'product',
+  value: 297.00,
+  currency: 'BRL'
+});
+```
+---
+## trackAddToCart(cartData)
+Adição ao carrinho.
+```javascript
+await window.cdpTrack.trackAddToCart({
+  content_id: 'SKU-001',
+  content_name: 'Produto XYZ',
+  value: 97.00,
+  currency: 'BRL',
+  num_items: 1
+});
+```
+---
+## updateConsent(params)
+Atualiza o Google Consent Mode v2 após o usuário aceitar o banner de cookies.
+```javascript
+// Usuário aceitou tudo
+window.cdpTrack.updateConsent({ analytics: true, ads: true });
+// Só analytics, rejeitou anúncios
+window.cdpTrack.updateConsent({ analytics: true, ads: false });
+// Rejeitou tudo
+window.cdpTrack.updateConsent({ analytics: false, ads: false });
+```
+O consentimento é persistido no `localStorage` e restaurado automaticamente em visitas futuras.
+---
+## getUserId()
+Retorna o `_cdp_uid` (cookie first-party, 365 dias).
+```javascript
+const uid = window.cdpTrack.getUserId();
+// "1711234567890_abc123def"
+```
+---
+## getUserIdWithFallback()
+Retorna o `_cdp_uid` com fallback para o `localStorage` (útil para afiliados e links em nova aba).
+```javascript
+const uid = window.cdpTrack.getUserIdWithFallback();
+```
+**Prioridade:** cookie → localStorage (`_cdp_aff`) → string vazia.
+---
+## getUTMs()
+Retorna os UTMs capturados da URL atual.
+```javascript
+const utms = window.cdpTrack.getUTMs();
+// {
+//   utm_source: "meta",
+//   utm_medium: "paid",
+//   utm_campaign: "curso-xyz",
+//   utm_content: "video-1",
+//   utm_term: ""
+// }
+```
+---
+## getUTMsWithFallback()
+Retorna UTMs da URL ou do localStorage (fallback de 30 dias — attribution resurrection para afiliados).
+```javascript
+const utms = window.cdpTrack.getUTMsWithFallback();
+```
+**Prioridade:** URL params → localStorage (`_cdp_aff`) → objeto vazio.
+---
+## getSessionId()
+Retorna o session ID (cross-tab, expira ao fechar o browser).
+```javascript
+const sid = window.cdpTrack.getSessionId();
+// "1711234567890_xyz456abc"
+```
+---
+## passCheckoutParams(options?)
+Injeta UTMs e `_cdp_uid` nos links de checkout externos. Chamado automaticamente em `init()`.
+```javascript
+// Chamada manual com configuração customizada
+passCheckoutParams({
+  platforms: ['hotmart', 'kiwify', 'ticto'],
+  domains: ['meusite.com/checkout']  // domínios customizados
+});
+```
+**Plataformas suportadas e parâmetros injetados:**
+| Plataforma | Parâmetros |
+|---|---|
+| Hotmart | `xcod` (user_id) + `sck` (utm_source\|medium\|campaign\|content\|term) |
+| Kiwify | `src` (utm_source) + `utm_medium` + `utm_campaign` |
+| Eduzz | `src` (utm_source) |
+| Monetizze | `src` (utm_source) |
+| CartPanda | utm_* passthrough direto |
+| Ticto | utm_* + `user_id` |
+| Custom | utm_* + `cdp_uid` |
+**Nota:** links adicionados dinamicamente (lazy load, pop-ups) são rastreados automaticamente via `MutationObserver`.
+---
+## setupAutoFormCapture()
+Intercepta submits de formulários com campos de email ou telefone e dispara `trackLead()` automaticamente. Chamado em `init()` por padrão.
+```javascript
+// Já é chamado em init(). Para uso manual:
+setupAutoFormCapture();
+```
+Para desabilitar:
+```javascript
+// Em tracking.config.js
+export default {
+  autoCaptureForms: false,
+  // ...
+}
+```
+---
+## Micro-events — getVideoSummary()
+Retorna o estado agregado de todos os vídeos na página (útil para VSL multi-vídeo).
+```javascript
+import { getVideoSummary } from '/js/micro-events.js';
+const summary = getVideoSummary();
+// {
+//   totalVideos: 2,
+//   startedCount: 1,
+//   completedCount: 0,
+//   maxProgress: 75    // maior % atingida entre todos os vídeos
+// }
+```
+---
+## Eventos DOM customizados
+O `micro-events.js` emite eventos DOM que a página pode ouvir para reagir ao comportamento do usuário:
+```javascript
+// Destravar CTA quando vídeo atingir 75%
+window.addEventListener('cdp:VideoProgress', (e) => {
+  if (e.detail.progress_percent >= 75) {
+    document.getElementById('cta').style.display = 'block';
+  }
+});
+// Mostrar formulário de lead ao 50% do scroll
+window.addEventListener('cdp:Scroll', (e) => {
+  if (e.detail.scroll_depth >= 50) {
+    document.getElementById('lead-form').classList.remove('hidden');
+  }
+});
+// Eventos disponíveis:
+// cdp:Scroll, cdp:TimeOnPage, cdp:VideoPlay, cdp:VideoProgress,
+// cdp:VideoComplete, cdp:VideoDropout, cdp:VideoPause, cdp:VideoSeek,
+// cdp:Click, cdp:CTAHover, cdp:RapidClicks
+```
+---
+## tracking.config.js — Configuração do SDK
+```javascript
+// extracted-skill/tracking-events-generator/tracking.config.js
+export default {
+  // IDs de plataformas
+  metaPixelId:     'SEU_PIXEL_ID',
+  ga4Id:           'G-XXXXXXXXXX',
+  tiktokPixelId:   'CXXXXXXXXXXXXXXX',
+  // Endpoint do Worker
+  endpoint: 'https://track.seudominio.com.br/track',
+  // Comportamento
+  autoCaptureForms:   true,   // captura formulários automaticamente
+  passCheckoutParams: true,   // injeta params em links de checkout
+  initBehaviorEngine: true,   // scoring avançado
+  // Plataformas para passCheckoutParams
+  platforms: ['hotmart', 'kiwify', 'ticto'],
+  // Google Consent Mode v2
+  consent: {
+    defaultDenied:  true,   // começa negado (LGPD compliant)
+    waitForUpdate:  500,    // ms aguardar CMP
+    urlPassthrough: true,   // preserva gclid/fbclid sem consent
+  },
+  debug: false  // true para logs no console
+};
+```

package/docs/whatsapp-ctwa.md ADDED Viewed

@@ -0,0 +1,209 @@
+# WhatsApp CTWA — Click to WhatsApp Tracking
+## O que é CTWA
+Click to WhatsApp (CTWA) é um formato de anúncio no Facebook/Instagram onde o botão
+de ação abre diretamente o WhatsApp em vez de direcionar para uma landing page.
+O problema clássico: sem landing page, o pixel do browser não dispara, e a Meta
+não consegue atribuir a conversão ao anúncio automaticamente.
+A solução implementada aqui: o webhook do WhatsApp Business recebe cada mensagem
+recebida, extrai o `ctwa_clid` (identificador do clique no anúncio) e envia um
+evento `Contact` para a Meta Conversions API com `action_source: "chat"`.
+Isso fecha o loop clique → conversa e aparece no Gerenciador de Eventos.
+---
+## Fluxo Completo
+```
+[Anúncio Meta — Click to WhatsApp]
+          ↓
+Usuário clica no botão "Enviar Mensagem"
+          ↓
+Meta injeta ctwa_clid no deep link do WhatsApp
+          ↓
+WhatsApp abre → usuário envia mensagem
+          ↓
+Meta Cloud API → POST /webhook/whatsapp (worker)
+          ↓
+Worker extrai: phone + ctwa_clid + ad_id + headline
+          ↓
+D1 armazena em whatsapp_contacts
+          ↓
+Meta CAPI ← evento "Contact" com:
+   • ph        = SHA256(phone)   → Advanced Matching por telefone
+   • ctwa_clid = click ID        → atribuição ao anúncio
+   • action_source = "chat"      → obrigatório para CTWA
+          ↓
+[Gerenciador de Eventos mostra a conversão]
+```
+---
+## Dados Capturados
+| Campo | Origem | Enviado ao CAPI | Hasheado |
+|-------|--------|-----------------|----------|
+| Telefone | `message.from` | `ph` | SHA-256 |
+| Click ID | `message.referral.ctwa_clid` | `ctwa_clid` | Não |
+| ID do anúncio | `message.referral.source_id` | — (armazenado no D1) | — |
+| URL do anúncio | `message.referral.source_url` | `event_source_url` | Não |
+| Título do anúncio | `message.referral.headline` | — (armazenado no D1) | — |
+| IP | Header CF-Connecting-IP | `client_ip_address` | Não |
+| User-Agent | Header User-Agent | `client_user_agent` | Não |
+---
+## Endpoints
+### `GET /webhook/whatsapp`
+Verificação do webhook pela Meta (feita uma vez ao cadastrar).
+Parâmetros recebidos:
+- `hub.mode` = `subscribe`
+- `hub.verify_token` = valor do secret `WA_WEBHOOK_VERIFY_TOKEN`
+- `hub.challenge` = número aleatório que deve ser devolvido
+Resposta: devolve o `hub.challenge` como texto puro com status 200.
+### `POST /webhook/whatsapp`
+Recebe eventos de mensagens da Meta Cloud API.
+Processa apenas mensagens do tipo `messages` com `referral.ctwa_clid` (anúncios CTWA).
+Mensagens orgânicas (sem referral) são recebidas com 200 mas não geram evento no CAPI.
+Resposta: `{ "ok": true, "processed": N, "results": [...] }`
+---
+## Banco de Dados (D1)
+### Tabela `whatsapp_contacts`
+```sql
+CREATE TABLE whatsapp_contacts (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+  phone_hash    TEXT    NOT NULL,  -- SHA256(phone) — enviado ao CAPI como "ph"
+  phone_raw     TEXT    NOT NULL,  -- número normalizado (ex: 5511999998888)
+  wamid         TEXT    UNIQUE,    -- ID da mensagem (deduplicação)
+  ctwa_clid     TEXT,              -- click ID do anúncio (não hasheado)
+  ad_id         TEXT,              -- ID do anúncio
+  source_url    TEXT,              -- URL do anúncio
+  headline      TEXT,              -- título do anúncio
+  capi_sent     INTEGER DEFAULT 0, -- 0=pendente | 1=enviado
+  capi_event_id TEXT,              -- event_id para deduplicação no CAPI
+  message_body  TEXT               -- texto da primeira mensagem
+);
+```
+A coluna `capi_sent` é atualizada para `1` após confirmação de sucesso da CAPI.
+A coluna `wamid` tem índice UNIQUE — garante que a mesma mensagem não seja processada duas vezes.
+---
+## Secrets Necessários
+| Secret | Descrição | Como configurar |
+|--------|-----------|-----------------|
+| `WA_WEBHOOK_VERIFY_TOKEN` | Token de verificação do webhook (você define) | `wrangler secret put WA_WEBHOOK_VERIFY_TOKEN` |
+| `META_ACCESS_TOKEN` | Token da Meta Conversions API | Já configurado |
+| `META_PIXEL_ID` | ID do Pixel Meta | Já em `wrangler.toml` |
+---
+## Como Configurar no Meta Business Manager
+1. Acesse [business.facebook.com](https://business.facebook.com)
+2. Menu lateral → **WhatsApp** → **Configuration**
+3. Seção **Webhook** → clique em **Edit**
+4. Preencha:
+   - **Callback URL:** `https://server-edge-tracker.suporte-ed9.workers.dev/webhook/whatsapp`
+   - **Verify Token:** valor do secret `WA_WEBHOOK_VERIFY_TOKEN`
+5. Clique em **Verify and Save**
+6. Após verificar, clique em **Manage** → ative o campo **`messages`**
+---
+## Como Criar um Anúncio CTWA
+No Gerenciador de Anúncios (ads.manager.facebook.com):
+1. **Objetivo da campanha:** `Mensagens`
+2. **Destino:** `WhatsApp`
+3. **Número de WhatsApp:** selecione o número conectado ao Business Manager
+4. O anúncio vai gerar automaticamente o `ctwa_clid` para cada clique
+---
+## Eventos no Gerenciador de Eventos
+Após o primeiro contato via CTWA, no Gerenciador de Eventos da Meta você verá:
+- **Nome do evento:** `Contact`
+- **Origem do evento:** `chat`
+- **Correspondência:** `Telephone` (via Advanced Matching pelo telefone hasheado)
+- **ID do clique:** `ctwa_clid` vinculado ao anúncio
+---
+## Próximos Eventos (Qualificação no Funil)
+Depois do `Contact` inicial, você pode enviar eventos adicionais conforme o lead avança:
+| Momento | Endpoint | `eventName` | Dados extras |
+|---------|----------|-------------|-------------|
+| Lead qualificado no chat | `POST /track` | `Lead` | `phone`, `value` estimado |
+| Venda confirmada no chat | `POST /track` | `Purchase` | `phone`, `value`, `currency` |
+Exemplo de chamada para registrar uma venda fechada pelo WhatsApp:
+```javascript
+fetch('https://server-edge-tracker.suporte-ed9.workers.dev/track', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    eventName: 'Purchase',
+    phone:     '5511999998888',
+    value:     297.00,
+    currency:  'BRL',
+    pageUrl:   'https://wa.me/',
+  })
+});
+```
+---
+## Troubleshooting
+### Webhook não verifica
+- Confirme que o `WA_WEBHOOK_VERIFY_TOKEN` foi salvo com `wrangler secret put`
+- Confirme que o worker foi deployado após a configuração do secret
+- Teste manualmente: `GET /webhook/whatsapp?hub.mode=subscribe&hub.verify_token=SEU_TOKEN&hub.challenge=12345`
+### Evento não aparece no Gerenciador de Eventos
+- Confirme que `META_ACCESS_TOKEN` está configurado e válido
+- Verifique a tabela `whatsapp_contacts` no D1: `capi_sent = 0` indica falha no envio
+- Verifique a tabela `api_failures` para detalhes do erro
+### Mensagem recebida mas sem ctwa_clid
+- O usuário abriu o WhatsApp diretamente (não veio de anúncio CTWA)
+- O contato ainda é salvo no D1, mas sem atribuição ao anúncio
+- O evento `Contact` é enviado mesmo sem ctwa_clid (com apenas o telefone hasheado)
+---
+## Arquivos Relacionados
+| Arquivo | Descrição |
+|---------|-----------|
+| `server-edge-tracker/worker.js` | Função `processWhatsAppWebhook()` (linha ~943) e rotas (linha ~2182) |
+| `server-edge-tracker/migrate-v6.sql` | Migration que criou a tabela `whatsapp_contacts` |
+| `server-edge-tracker/wrangler.toml` | Secret `WA_WEBHOOK_VERIFY_TOKEN` documentado |
+| `server-edge-tracker/schema.sql` | Schema completo do D1 (referência) |
+---
+*Implementado em: 30 de março de 2026. CDP Edge v1.2 — WhatsApp CTWA Module.*

package/extracted-skill/tracking-events-generator/INDEX.md ADDED Viewed

@@ -0,0 +1,94 @@
+# Índice de Arquivos - CDP Edge
+**Última atualização:** 2026-03-28
+---
+## 📚 NÚCLEO
+| Categoria | Arquivos |
+|---------|----------|
+| **Orquestração** | `agents/master-orchestrator.md` |
+| **Documentação Principal** | `SKILL.md`, `knowledge-base.md` |
+| **Núcleo de Agentes** | `agents/` |
+| **Modelos de Cenário** | `models/scenarios/` |
+| **Infraestrutura** | `server-edge-tracker/` |
+---
+## 🗂️ AGENTES ORQUESTRADORES
+| Agente | Arquivo | Descrição |
+|---------|----------|----------|
+| **Master Orchestrator** | `agents/master-orchestrator.md` | Coordena todo o fluxo |
+| **Code Guardian** | `agents/code-guardian-agent.md` | Integridade contínua — padrões, nomenclatura, pré-commit |
+| **Browser Tracking** | `agents/browser-tracking.md` | SDK cdpTrack.js |
+| **Server Tracking** | `agents/server-tracking.md` | Infraestrutura Cloudflare |
+| **Database** | `agents/database-agent.md` | D1 Enterprise — Schema, queries, migrações |
+| **Page Analyzer** | `agents/page-analyzer.md` | Análise de páginas |
+| **Premium Tracking** | `agents/premium-tracking-intelligence-agent.md` | Estratégia de tracking |
+| **Meta** | `agents/meta-agent.md` | Facebook/Instagram Pixel + CAPI |
+| **Google** | `agents/google-agent.md` | GA4 + Google Ads |
+| **TikTok** | `agents/tiktok-agent.md` | TikTok Pixel + Events API |
+| **Spotify** | `agents/spotify-agent.md` | Spotify Ads Conversions |
+| **Validator** | `agents/validator-agent.md` | Controle de qualidade |
+| **LinkedIn** | `agents/linkedin-agent.md` | LinkedIn Conversions |
+| **Snapchat** | `agents/snapchat-agent.md` | Snapchat Pixel + Conversions |
+| **Twitter/X** | `agents/twitter-agent.md` | Twitter Conversions API |
+| **Pinterest** | `agents/pinterest-agent.md` | Pinterest Conversions |
+| **Reddit** | `agents/reddit-agent.md` | Reddit Conversions |
+| **Bing** | `agents/bing-agent.md` | Bing UET |
+| **WhatsApp** | `agents/whatsapp-agent.md` | Meta Cloud API |
+| **Email** | `agents/email-agent.md` | Resend Transacional |
+| **Dashboard** | `agents/dashboard-agent.md` | Métricas + Reports |
+| **Debug** | `agents/debug-agent.md` | Diagnóstico de falhas |
+| **Attribution** | `agents/attribution-agent.md` | Atribuição Multi-Touch |
+| **Security Enterprise** | `agents/security-enterprise-agent.md` | Rate Limiting + Audit |
+| **Performance** | `agents/performance-optimization-agent.md` | Caching + Otimização |
+| **Compliance** | `agents/compliance-agent.md` | GDPR/LGPD/CCPA |
+| **CRM Integration** | `agents/crm-integration-agent.md` | HubSpot/Salesforce |
+| **Fingerprint** | `agents/fingerprint-agent.md` | UTM + Lead Lock |
+| **Localization** | `agents/localization-agent.md` | Moedas/Checkout |
+| **LTV Predictor** | `agents/ltv-predictor-agent.md` | Predição de LTV |
+| **A/B Testing** | `agents/ab-testing-agent.md` | Edge Route Optimization |
+| **Webhook** | `agents/webhook-agent.md` | Hotmart/Kiwify/Eduzz |
+| **Tracking Plan** | `agents/tracking-plan-agent.md` | Plano de Tracking |
+---
+## 📖 MODELOS DE CENÁRIO
+| Categoria | Arquivos |
+|---------|----------|
+| **Comportamento** | `models/scenarios/behavior-engine.js` | Human-Behavior Engine |
+| **Lead Capture** | `models/captura-de-lead.md` |
+| **Lead + Webhook** | `models/captura-lead-evento-externo.md` |
+| **Checkout Próprio** | `models/checkout-proprio.md` |
+| **Trafego Direto** | `models/trafego-direto.md` |
+| **Página Obrigado** | `models/pagina-obrigado.md` |
+| **Webinar** | `models/webinar-registration.md` |
+| **Quiz Funnel** | `models/quiz-funnel.md` |
+---
+## 🔧 INFRAESTRURA
+| Arquivo | Descrição |
+|---------|----------|
+| **Worker Principal** | `server-edge-tracker/worker.js` | Handler `/api/*` |
+| **Schema D1** | `server-edge-tracker/schema.sql` | Banco de dados |
+| **Config Wrangler** | `server-edge-tracker/wrangler.toml` | Deploy config |
+---
+## 📝 CONTRATOS
+| Arquivo | Descrição |
+|---------|----------|
+| `package.json` | Configuração do pacote npx |
+| `bin/cdp-edge.js` | Entry point do CLI |
+| `dist/commands/` | Comandos do CLI (setup, analyze, server, validate, infra) |
+---
+**Total de arquivos indexados:** 40+ arquivos principais