cdp-edge 1.9.0 → 1.11.0

package/docs/installation.md

@@ -0,0 +1,155 @@
+# CDP Edge — Instalação em Projetos de Clientes
+
+Como integrar o CDP Edge em qualquer projeto para que Claude Code, VS Code, Cursor e outras IDEs com IA o reconheçam automaticamente.
+
+---
+
+## Estrutura recomendada
+
+```
+meu-projeto-cliente/          ← abrir esta pasta no Claude Code / VS Code
+├── CLAUDE.md                 ← ⭐ faz o Claude Code ativar o CDP Edge automaticamente
+├── .cursorrules              ← (opcional) para Cursor IDE
+├── cdp-edge/                 ← CDP Edge instalado aqui
+│   ├── extracted-skill/
+│   ├── server-edge-tracker/
+│   ├── templates/
+│   └── docs/
+├── src/                      ← código do projeto do cliente
+└── ...
+```
+
+---
+
+## Passo 1 — Instalar o CDP Edge na pasta do projeto
+
+```bash
+# Dentro da pasta do projeto do cliente:
+cd meu-projeto-cliente
+
+# Opção A — clonar o CDP Edge como subpasta
+git clone https://github.com/ricardosoli777/CDP-Edge-Premium cdp-edge
+
+# Opção B — copiar manualmente
+# Copiar a pasta CDP-Edge inteira e renomear para cdp-edge/
+```
+
+---
+
+## Passo 2 — Criar o CLAUDE.md na raiz do projeto
+
+Copiar o template de ativação:
+
+```bash
+cp cdp-edge/templates/install/CLAUDE.md ./CLAUDE.md
+```
+
+Editar o `CLAUDE.md` e substituir `[NOME DO PROJETO]` pelo nome real do projeto.
+
+**Por que isso funciona:**
+O Claude Code lê o `CLAUDE.md` da raiz do diretório aberto automaticamente. Quando encontra a instrução de leitura do `master-orchestrator.md`, ativa o sistema imediatamente na abertura da sessão.
+
+---
+
+## Passo 3 — Abrir o projeto no Claude Code
+
+```bash
+# Na pasta do projeto (não dentro do cdp-edge):
+claude .
+```
+
+O Claude Code vai:
+1. Ler o `CLAUDE.md` da raiz
+2. Encontrar a instrução de ativação do CDP Edge
+3. Carregar o `master-orchestrator.md`
+4. Exibir a mensagem de boas-vindas automaticamente
+
+---
+
+## Para VS Code com extensão Claude
+
+O mesmo mecanismo funciona. O `CLAUDE.md` é lido pela extensão Claude Code no VS Code quando você abre a pasta do projeto.
+
+```bash
+code meu-projeto-cliente/
+```
+
+---
+
+## Para Cursor IDE
+
+Criar adicionalmente um `.cursorrules` na raiz:
+
+```bash
+cp cdp-edge/templates/install/CLAUDE.md .cursorrules
+```
+
+O Cursor lê `.cursorrules` automaticamente e aplica as instruções ao agente AI.
+
+---
+
+## Para qualquer outra IDE com AI
+
+Qualquer IDE que suporte arquivos de instrução (`.aidioms`, `system-prompt.md`, etc.) pode usar o mesmo conteúdo do `CLAUDE.md` adaptado para o formato da IDE.
+
+---
+
+## Verificar se funcionou
+
+Ao abrir o projeto no Claude Code, você deve ver imediatamente:
+
+```
+👋 Olá! Bem-vindo ao CDP Edge — Quantum Tracking.
+
+Sou o seu Orquestrador de Rastreamento. Vou configurar toda a
+infraestrutura de tracking server-side para o seu projeto...
+```
+
+Se não aparecer automaticamente, digitar:
+
+```
+/cdp
+```
+
+ou simplesmente:
+
+```
+ative o master orchestrator do cdp edge
+```
+
+---
+
+## Se o CDP Edge estiver em um caminho diferente
+
+Editar o `CLAUDE.md` na raiz e ajustar o path:
+
+```markdown
+<!-- Padrão: -->
+Leia o arquivo: `cdp-edge/extracted-skill/tracking-events-generator/agents/master-orchestrator.md`
+
+<!-- Se instalado em outro lugar: -->
+Leia o arquivo: `ferramentas/cdp/extracted-skill/tracking-events-generator/agents/master-orchestrator.md`
+```
+
+---
+
+## Estrutura de múltiplos projetos (workspace compartilhado)
+
+Se você trabalha com vários clientes e quer uma instalação única do CDP Edge:
+
+```
+workspace/
+├── cdp-edge/                 ← instalação única compartilhada
+├── cliente-1/
+│   ├── CLAUDE.md             ← aponta para ../cdp-edge/...
+│   └── src/
+├── cliente-2/
+│   ├── CLAUDE.md             ← aponta para ../cdp-edge/...
+│   └── src/
+```
+
+No `CLAUDE.md` de cada cliente, usar path relativo:
+
+```markdown
+Leia o arquivo: `../cdp-edge/extracted-skill/tracking-events-generator/agents/master-orchestrator.md`
+```

package/docs/quick-start.md

@@ -0,0 +1,185 @@
+# CDP Edge — Quick Start
+> Do zero ao primeiro evento em produção.
+
+---
+
+## Pré-requisitos
+
+| Ferramenta | Instalar |
+|---|---|
+| Node.js 18+ | nodejs.org |
+| Wrangler CLI | `npm install -g wrangler` |
+| Conta Cloudflare | cloudflare.com (plano gratuito suficiente) |
+| Conta Meta (Pixel + token CAPI) | business.facebook.com |
+
+---
+
+## 1. Autenticar no Cloudflare
+
+```bash
+wrangler login
+```
+
+---
+
+## 2. Criar o banco D1
+
+```bash
+wrangler d1 create cdp-edge-db
+```
+
+Copie o `database_id` retornado e cole no `wrangler.toml`:
+
+```toml
+[[d1_databases]]
+binding      = "DB"
+database_name = "cdp-edge-db"
+database_id  = "COLE_O_ID_AQUI"
+```
+
+---
+
+## 3. Aplicar o schema
+
+```bash
+cd server-edge-tracker
+
+wrangler d1 execute cdp-edge-db --file=schema.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v2.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v3.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v4.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v5.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote
+```
+
+---
+
+## 4. Configurar secrets
+
+```bash
+wrangler secret put META_ACCESS_TOKEN
+wrangler secret put GA4_API_SECRET
+wrangler secret put TIKTOK_ACCESS_TOKEN
+```
+
+Para WhatsApp CTWA (opcional):
+```bash
+wrangler secret put WA_WEBHOOK_VERIFY_TOKEN
+wrangler secret put WHATSAPP_TOKEN
+wrangler secret put WHATSAPP_PHONE_NUMBER_ID
+```
+
+---
+
+## 5. Atualizar variáveis públicas no wrangler.toml
+
+```toml
+[vars]
+META_PIXEL_ID      = "SEU_PIXEL_ID"
+GA4_MEASUREMENT_ID = "G-XXXXXXXXXX"
+TIKTOK_PIXEL_ID    = "CXXXXXXXXXXXXXXX"
+SITE_DOMAIN        = "seudominio.com.br"
+```
+
+---
+
+## 6. Deploy
+
+```bash
+wrangler deploy
+```
+
+O Worker ficará disponível em:
+```
+https://server-edge-tracker.SEU-USUARIO.workers.dev
+```
+
+---
+
+## 7. Testar o Worker
+
+```bash
+# Health check
+curl https://server-edge-tracker.SEU-USUARIO.workers.dev/health
+
+# Evento de teste
+curl -X POST https://server-edge-tracker.SEU-USUARIO.workers.dev/track \
+  -H "Content-Type: application/json" \
+  -d '{
+    "event": "PageView",
+    "url": "https://seudominio.com.br/",
+    "email": "teste@exemplo.com"
+  }'
+```
+
+Resposta esperada: `{"success":true}`
+
+---
+
+## 8. Instalar o SDK no site
+
+```html
+<!-- No <head> de todas as páginas -->
+<script>
+  window.CDP_CONFIG = {
+    endpoint: 'https://server-edge-tracker.SEU-USUARIO.workers.dev/track',
+    pixelId: 'SEU_PIXEL_ID'
+  };
+</script>
+<script src="/js/cdpTrack.js" type="module" async></script>
+```
+
+O SDK inicializa automaticamente e dispara `PageView` ao carregar.
+
+---
+
+## 9. Verificar no Meta Events Manager
+
+```
+Meta Business Suite
+  → Gerenciador de Eventos
+  → Seu Pixel
+  → Atividade de Teste
+  → Filtrar por "Servidor"
+```
+
+Você deve ver o `PageView` chegando com `action_source: website`.
+
+---
+
+## 10. (Opcional) Conectar domínio próprio
+
+Para máxima eficácia (cookie first-party no domínio do cliente):
+
+```
+Cloudflare Dashboard → DNS → Add record
+  Type:   CNAME
+  Name:   track
+  Target: server-edge-tracker.SEU-USUARIO.workers.dev
+  Proxy:  ✅ (nuvem laranja)
+```
+
+Adicionar ao `wrangler.toml`:
+```toml
+[[routes]]
+pattern   = "track.seudominio.com.br/*"
+zone_name = "seudominio.com.br"
+```
+
+```bash
+wrangler deploy
+```
+
+Ver detalhes: `agents/domain-setup-agent.md`
+
+---
+
+## Próximos passos
+
+| O que fazer | Onde está |
+|---|---|
+| Configurar WhatsApp CTWA | `agents/whatsapp-ctwa-setup-agent.md` |
+| Ativar R2 audit log | `agents/r2-setup-agent.md` |
+| Configurar gateways de pagamento | `agents/webhook-agent.md` |
+| Ver todos os eventos disponíveis | `docs/events-reference.md` |
+| Ver API do SDK browser | `docs/sdk-reference.md` |

package/docs/sdk-reference.md

@@ -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
+};
+```