cdp-edge 1.9.0 → 1.11.0

package/docs/whatsapp-ctwa.md

@@ -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

@@ -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

package/extracted-skill/tracking-events-generator/INSTALACAO-CDPEDGE.md

@@ -0,0 +1,58 @@
+# Instalação: CDP Edge (Quantum Tier)
+
+O **CDP Edge** é um sistema de tracking digital completo que opera de forma nativa na Cloudflare. Ele analisa os arquivos do seu projeto, identifica formulários e botões automaticamente, e gera todo o código de tracking para Meta, Google, TikTok e mais — incluindo servidor na borda e banco de dados D1, garantindo alta precisão e soberania total de dados.
+
+---
+
+## 🚀 PASSO A PASSO DA INSTALAÇÃO
+
+### 1. Preparação da Conta Cloudflare
+- Acesse [cloudflare.com](https://cloudflare.com).
+- Ative o banco de dados **D1**.
+- Crie um **Worker** para processamento de eventos.
+
+### 2. Implantação do SDK (Site)
+- Adicione o script `cdpTrack.js` ao `<head>` do seu site.
+- Configure os IDs (Meta, TikTok, GA4) no `cdpConfig.js`.
+
+### 3. Configuração do Servidor (Worker)
+- Faça o deploy do código gerado pelo **Server Agent**.
+- Conecte o banco D1 ao seu Worker via `wrangler.toml`.
+- Configure as Variáveis de Ambiente (Tokens de API).
+
+---
+
+## ⚡ ARQUITETURA TÉCNICA (Quantum Tier SUPREME)
+| Componente | Função | Vantagem |
+|---|---|---|
+| **cdpTrack.js** | SDK do Site | Envio direto via Fetch para o Worker |
+| **Workers** | Processamento | Execução na borda com baixa latência |
+| **D1 Database** | Persistência | Armazenamento seguro de leads e eventos |
+| **CAPI v22.0** | Despacho | Atribuição de alta qualidade via servidor |
+
+### Plataformas Suportadas (Server-Side)
+| Plataforma | Status | Protocolo |
+|---|---|---|
+| Meta / Facebook Pixel | ✅ | ✅ CAPI v22.0 |
+| Google Analytics 4 | ✅ | ✅ Measurement Protocol |
+| Google Ads | ✅ | ✅ Conversão + User-provided Data |
+| TikTok Pixel | ✅ | ✅ Events API v1.3 |
+| Pinterest Tag | ✅ | — |
+| Bing / Microsoft Ads | ✅ | — |
+
+### Tipos de página reconhecidos automaticamente
+| Tipo | Quando usa |
+|---|---|
+| Captura de Lead | Formulário com email/nome/telefone |
+| Lead + Evento Externo | Formulário + compra em plataforma externa (Hotmart/Kiwify) |
+| Tráfego Direto | Página de vendas sem formulário → checkout externo |
+| Checkout Próprio | Cartão/Stripe/MercadoPago na página |
+| Página de Obrigado | Thank-you page pós-compra |
+
+---
+
+## 🏁 INICIANDO O SETUP
+Para começar, utilize o comando:
+> "/setup"
+
+O CDP Edge irá analisar seu site e gerar a infraestrutura necessária automaticamente.