cdp-edge 1.2.0

package/docs/events-reference.md

@@ -0,0 +1,359 @@
+# CDP Edge — Events Reference
+> Catálogo completo de todos os eventos, payloads e mapeamento por plataforma.
+
+---
+
+## Como enviar um evento
+
+### Via SDK browser (cdpTrack.js)
+```javascript
+// Genérico
+window.cdpTrack.track('EventName', { param1: 'valor', param2: 'valor' });
+
+// Atalhos
+window.cdpTrack.trackLead({ email: '...', phone: '...' });
+window.cdpTrack.trackPurchase({ value: 97, currency: 'BRL', order_id: '...' });
+window.cdpTrack.trackViewContent({ content_name: '...', value: 97 });
+window.cdpTrack.trackAddToCart({ content_id: '...', value: 97 });
+```
+
+### Via Worker direto (server-to-server)
+```bash
+curl -X POST https://track.seudominio.com.br/track \
+  -H "Content-Type: application/json" \
+  -d '{ "event": "Lead", "email": "fulano@exemplo.com", "phone": "11999998888" }'
+```
+
+---
+
+## Eventos Principais
+
+### PageView
+Disparado automaticamente pelo SDK ao carregar qualquer página.
+
+```json
+{
+  "event": "PageView",
+  "url": "https://seudominio.com.br/pagina",
+  "title": "Título da Página"
+}
+```
+
+| Plataforma | Nome do evento |
+|---|---|
+| Meta CAPI | `PageView` |
+| GA4 | `page_view` |
+| TikTok | `PageView` |
+
+---
+
+### Lead
+Captura de lead com dados pessoais. O Worker faz SHA256 automaticamente — enviar dados crus.
+
+```json
+{
+  "event": "Lead",
+  "email": "fulano@exemplo.com",
+  "phone": "11999998888",
+  "firstName": "João",
+  "lastName": "Silva",
+  "city": "São Paulo",
+  "state": "SP",
+  "zip": "01310100",
+  "country": "BR"
+}
+```
+
+| Plataforma | Nome do evento |
+|---|---|
+| Meta CAPI | `Lead` |
+| GA4 | `generate_lead` |
+| TikTok | `SubmitForm` |
+| Pinterest | `lead` |
+| Reddit | `Lead` |
+| LinkedIn | `LEAD` |
+
+**Campos obrigatórios:** pelo menos um entre `email` ou `phone`.
+
+---
+
+### Purchase
+Compra confirmada. Pode vir do browser ou do webhook de gateway.
+
+```json
+{
+  "event": "Purchase",
+  "value": 297.00,
+  "currency": "BRL",
+  "order_id": "ORD-12345",
+  "email": "fulano@exemplo.com",
+  "phone": "11999998888",
+  "content_name": "Curso XYZ",
+  "content_ids": ["SKU-001"]
+}
+```
+
+| Plataforma | Nome do evento |
+|---|---|
+| Meta CAPI | `Purchase` |
+| GA4 | `purchase` |
+| TikTok | `CompletePayment` |
+| Pinterest | `checkout` |
+| Reddit | `Purchase` |
+| LinkedIn | `PURCHASE` |
+
+**Campos obrigatórios:** `value`, `currency`.
+
+---
+
+### InitiateCheckout
+Clique no botão de compra ou entrada na página de checkout.
+
+```json
+{
+  "event": "InitiateCheckout",
+  "value": 297.00,
+  "currency": "BRL",
+  "content_name": "Curso XYZ",
+  "content_ids": ["SKU-001"]
+}
+```
+
+| Plataforma | Nome do evento |
+|---|---|
+| Meta CAPI | `InitiateCheckout` |
+| GA4 | `begin_checkout` |
+| TikTok | `InitiateCheckout` |
+
+---
+
+### ViewContent
+Visualização de produto, oferta ou conteúdo de valor.
+
+```json
+{
+  "event": "ViewContent",
+  "content_name": "Página de Vendas — Curso XYZ",
+  "content_type": "product",
+  "value": 297.00,
+  "currency": "BRL",
+  "content_ids": ["SKU-001"]
+}
+```
+
+| Plataforma | Nome do evento |
+|---|---|
+| Meta CAPI | `ViewContent` |
+| GA4 | `view_item` |
+| TikTok | `ViewContent` |
+| Pinterest | `pagevisit` |
+| Reddit | `ViewContent` |
+
+---
+
+### AddToCart
+Adição ao carrinho (e-commerce ou checkout multi-produto).
+
+```json
+{
+  "event": "AddToCart",
+  "value": 97.00,
+  "currency": "BRL",
+  "content_name": "Produto XYZ",
+  "content_ids": ["SKU-002"],
+  "num_items": 1
+}
+```
+
+| Plataforma | Nome do evento |
+|---|---|
+| Meta CAPI | `AddToCart` |
+| GA4 | `add_to_cart` |
+| TikTok | `AddToCart` |
+| Pinterest | `addtocart` |
+| Reddit | `AddToCart` |
+
+---
+
+### CompleteRegistration
+Cadastro completo (criação de conta, inscrição em lista, acesso liberado).
+
+```json
+{
+  "event": "CompleteRegistration",
+  "email": "fulano@exemplo.com",
+  "content_name": "Webinar Gratuito XYZ"
+}
+```
+
+| Plataforma | Nome do evento |
+|---|---|
+| Meta CAPI | `CompleteRegistration` |
+| GA4 | `sign_up` |
+| TikTok | `CompleteRegistration` |
+| LinkedIn | `REGISTRATION` |
+| Spotify | `SIGN_UP` |
+
+---
+
+### Contact
+Contato via WhatsApp (CTWA — Click to WhatsApp). Disparado automaticamente pelo webhook.
+
+```json
+{
+  "event": "Contact",
+  "phone": "5511999998888",
+  "ctwa_clid": "ARAkLgFgg...",
+  "action_source": "chat"
+}
+```
+
+| Plataforma | Nome do evento |
+|---|---|
+| Meta CAPI | `Contact` (action_source: "chat") |
+
+**Nota:** Este evento é gerado automaticamente pelo `processWhatsAppWebhook()` — não precisa ser disparado manualmente.
+
+---
+
+## Eventos de Micro-Engajamento
+
+Gerados automaticamente pelo `micro-events.js`. Salvos no D1 (`behavioral_events`). Contribuem para o engagement score mas **não são enviados às plataformas de anúncio** individualmente.
+
+### Scroll
+```json
+{
+  "event": "Scroll",
+  "scroll_depth": 75,
+  "scroll_percent": 78,
+  "signal_strength": 3.0,
+  "time_on_page": 45
+}
+```
+
+### TimeOnPage
+```json
+{
+  "event": "TimeOnPage",
+  "time_on_page": 180,
+  "intention_level": "comprador",
+  "signal_strength": 4.0
+}
+```
+**Níveis:** `curioso` (10s) → `interessado` (60s) → `comprador` (180s)
+
+### VideoPlay / VideoProgress / VideoComplete
+```json
+{
+  "event": "VideoProgress",
+  "video_id": "vsl-principal",
+  "video_platform": "youtube",
+  "progress_percent": 75,
+  "progress_second": 423,
+  "engagement_score": 5.0,
+  "video_summary": {
+    "totalVideos": 1,
+    "startedCount": 1,
+    "completedCount": 0,
+    "maxProgress": 75
+  }
+}
+```
+**Plataformas suportadas:** `html5`, `youtube`, `vimeo`
+
+### VideoDropout
+Registra o segundo exato em que o usuário parou de assistir.
+```json
+{
+  "event": "VideoDropout",
+  "video_id": "vsl-principal",
+  "dropout_percent": 62,
+  "dropout_second": 743,
+  "engagement_score": 2.5
+}
+```
+**Disparado em:** pause sem retomada + `beforeunload` da página.
+
+### Click
+```json
+{
+  "event": "Click",
+  "click_category": "cta",
+  "position": { "x": 640, "y": 980, "relativeX": 50, "relativeY": 72 },
+  "time_on_page": 120
+}
+```
+**Categorias:** `button`, `link`, `input`, `cta`, `price`, `whatsapp`, `email`, `phone`, `generic`
+
+### CTAHover
+```json
+{
+  "event": "CTAHover",
+  "cta_selector": "a[href*='checkout']",
+  "hover_time_seconds": 4,
+  "engagement_score": 3.0
+}
+```
+Dispara apenas após 3 segundos de hover no botão de compra.
+
+---
+
+## Engagement Score
+
+Calculado pelo Worker para cada evento recebido. Salvo em `leads.engagement_score`.
+
+| Dimensão | Range | Descrição |
+|---|---|---|
+| `time_level` | 0–4.0 | Tempo na página |
+| `scroll_score` | 0–4.0 | Profundidade de scroll |
+| `click_score` | 0–2.5 | Cliques em CTAs |
+| `video_score` | 0–5.0 | Progresso de vídeo |
+| `hover_score` | 0–3.0 | Hover no botão de compra |
+| **totalScore** | **0–5.0** | Média ponderada |
+
+**Intention levels baseados no score:**
+
+| Score | Label | Ação recomendada |
+|---|---|---|
+| 0.0–1.5 | `curioso` | Retargeting leve |
+| 1.5–3.0 | `interessado` | Retargeting com oferta |
+| 3.0–5.0 | `comprador` | Lookalike de alta qualidade |
+
+---
+
+## Webhooks de Gateway de Pagamento
+
+Recebidos pelo Worker. Disparam `Purchase` automaticamente.
+
+| Endpoint | Gateway | Autenticação |
+|---|---|---|
+| `POST /webhook/hotmart` | Hotmart | `HOTMART_HOTTOK` header |
+| `POST /webhook/kiwify` | Kiwify | `KIWIFY_SECRET` HMAC |
+| `POST /webhook/ticto` | Ticto | `TICTO_SECRET` HMAC-SHA256 |
+
+---
+
+## WhatsApp Webhook
+
+| Endpoint | Método | Descrição |
+|---|---|---|
+| `/webhook/whatsapp` | `GET` | Verificação do Meta (challenge) |
+| `/webhook/whatsapp` | `POST` | Recebe mensagens CTWA |
+
+Configurar no Meta Business Suite → WhatsApp → Configuração → Webhook.
+
+---
+
+## Campos Normalizados Automaticamente
+
+O Worker normaliza antes de fazer SHA256:
+
+| Campo | Normalização |
+|---|---|
+| `email` | `lowercase` + `trim` |
+| `phone` | Somente dígitos + DDI `55` (Brasil) |
+| `firstName` / `lastName` | `Title Case` |
+| `city` | `lowercase` + remove acentos |
+| `state` | `uppercase` (ex: `SP`, `RJ`) |
+| `zip` | Somente dígitos |
+| `country` | `lowercase` (ex: `br`) |

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