cdp-edge 1.9.0 → 1.11.0

package/bin/cdp-edge.js

@@ -11,6 +11,7 @@ import { runAnalyze } from '../dist/commands/analyze.js';
 import { runServer } from '../dist/commands/server.js';
 import { runValidate } from '../dist/commands/validate.js';
 import { runInfra } from '../dist/commands/infra.js';
+import { runInstall } from '../dist/commands/install.js';
 
 const program = new Command();
 
@@ -50,4 +51,11 @@ program
   .description('Mostra guia de setup de infraestrutura Cloudflare')
   .action(runInfra);
 
+program
+  .command('install [dir]')
+  .description('Instala o CDP Edge em um projeto cliente e habilita /cdp no Claude Code')
+  .option('-n, --name <name>', 'Nome do projeto')
+  .option('--cursor', 'Criar .cursorrules para Cursor IDE')
+  .action(runInstall);
+
 program.parse(process.argv);

package/docs/CI-CD-SETUP.md

@@ -0,0 +1,217 @@
+# CDP Edge - Setup CI/CD e Versionamento Automático
+
+## Fluxo Escolhido
+
+Escolha **UMA** das opções:
+
+| Opção | Versão | Quando usar |
+|-------|--------|------------|
+| **semantic-release** | Automática | Commits convencionais, time pequeno |
+| **Manual workflow** | Controlada | Quer aprovar cada release |
+
+---
+
+## PASSO 1: Criar Conta e Token no npm
+
+```bash
+# 1. Criar conta em https://www.npmjs.com/signup
+
+# 2. Login
+npm login
+
+# 3. Criar token de automação
+# Vá em: https://www.npmjs.com/settings/tokens
+# - Clique "Create New Token"
+# - Nome: "GitHub Actions"
+# - Tipo: "Automation"
+# - Copie o token gerado
+```
+
+---
+
+## PASSO 2: Configurar Secrets no GitHub
+
+Vá no repositório: `Settings` → `Secrets and variables` → `Actions` → `New repository secret`
+
+**Adicione:**
+
+| Nome | Valor |
+|------|-------|
+| `NPM_TOKEN` | Token do passo 1 |
+| `GITHUB_TOKEN` | Já existe automaticamente (não precisa criar) |
+
+---
+
+## PASSO 3: Configurar o Workflow
+
+### Opção A: semantic-release (Automática)
+
+```bash
+# 1. Adicionar dependências
+npm install -D semantic-release @semantic-release/changelog @semantic-release/commit-analyzer @semantic-release/github @semantic-release/npm @semantic-release/release-notes-generator
+
+# 2. O arquivo .releaserc.json já está criado
+# 3. O workflow .github/workflows/release.yml já está criado
+# 4. Commit e push
+git add .
+git commit -m "ci: add semantic-release automation"
+git push
+```
+
+**Como usar:**
+
+```bash
+# Nova feature
+git commit -m "feat: add Reddit support"
+
+# Bugfix
+git commit -m "fix: correct TikTok endpoint"
+
+# Breaking change
+git commit -m "feat!: remove GTM support"
+# ou
+git commit -m "feat: add new API
+
+BREAKING CHANGE: requires Node 20+"
+```
+
+Ao fazer push no `main`, o release é automático!
+
+---
+
+### Opção B: Manual Workflow
+
+```bash
+# 1. O arquivo .github/workflows/publish.yml já está criado
+# 2. Commit e push
+git add .
+git commit -m "ci: add manual publish workflow"
+git push
+```
+
+**Como usar:**
+
+1. Vá em: `Actions` → `Publish to npm`
+2. Clique `Run workflow`
+3. Escolha o tipo: `patch`, `minor` ou `major`
+4. Clique `Run workflow`
+
+---
+
+## PASSO 4: Configurar Conventional Commits (Opcional mas recomendado)
+
+```bash
+# Instalar commitlint
+npm install -D @commitlint/cli @commitlint/config-conventional
+
+# Criar commitlint.config.js
+echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js
+
+# Adicionar ao package.json scripts
+# "prepare": "husky install"
+# "commitlint": "commitlint --edit"
+
+# Instalar husky
+npm install -D husky
+npx husky install
+npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'
+```
+
+Agora commits inválidos são bloqueados!
+
+---
+
+## Fluxo Completo de Desenvolvimento
+
+```
+Desenvolvimento
+      ↓
+git commit -m "feat: nova funcionalidade"
+      ↓
+git push origin main
+      ↓
+GitHub Actions detecta push
+      ↓
+    ┌─────────┐
+    │ semantic-│  (se Opção A)
+    │ release  │──→ Calcula versão
+    └─────────┘
+      ↓
+    ┌─────────┐
+    │  CI/CD  │──→ Build + Test
+    └─────────┘
+      ↓
+    ┌─────────┐
+    │ Publish │──→ npm publish
+    │  npm    │
+    └─────────┘
+      ↓
+    ┌─────────┐
+    │GitHub   │──→ Criar Release
+    │ Release │    + Changelog
+    └─────────┘
+```
+
+---
+
+## Verificação
+
+```bash
+# Ver releases criados
+npm view cdp-edge versions
+
+# Ver changelog
+# Vá em: https://github.com/seu-usuario/cdp-edge/releases
+```
+
+---
+
+## Solução de Problemas
+
+### Erro: "401 Unauthorized"
+→ Verifique se `NPM_TOKEN` está correto no GitHub Secrets
+
+### Erro: "403 Forbidden"
+→ Verifique se o nome do pacote está disponível no npm
+
+### Release não aparece
+→ Verifique se o workflow falhou em `Actions`
+
+---
+
+## Dicas Avançadas
+
+### Pre-release (beta, alpha)
+
+```bash
+git commit -m "feat: add beta feature
+
+Release: 1.1.0-beta.1"
+```
+
+### Ignorar commits no release
+
+```
+# .releaserc.json
+{
+  "branches": ["main"],
+  "tagFormat": "v${version}",
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    {
+      "preset": "conventionalcommits",
+      "releaseRules": [
+        { "type": "chore", "scope": "deps", "release": "patch" }
+      ]
+    }
+  ]
+}
+```
+
+### Multiple publish channels
+
+Use scopes para diferentes canais:
+```bash
+npm publish --tag beta    # @beta
+npm publish --tag next    # @next
+```

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