cdp-edge 1.0.0

package/README.md

@@ -0,0 +1,324 @@
+# 🚀 CDP Edge — Quantum Tracking Enterprise
+
+**Padrão Quantum Tracking: 100% Cloudflare Edge.** Sem GTM. Sem Stape. Sem cookies de terceiros.
+
+> **v2.5.2** — Auditoria Completa + Sync Total de Agentes + Fix D1 (15 de Abril de 2026) 🔧
+> **v2.5.1** — SDK Bundle + Diagnóstico Pós-Deploy + Gap Fixes (15 de Abril de 2026) 🛠️
+> **v2.3.9** — Quiz Scoring Engine + Sales Engine (14 de Abril de 2026) 🤖💰
+
+---
+
+## 📋 CHANGELOG v2.5.2 — Auditoria Completa + Sync Total de Agentes + Fix D1 (15 de Abril de 2026) 🔧
+
+### Bug Fix Crítico
+- `schema-ltv-feedback.sql` adicionado à ordem de migração — `recordLtvFeedback()` falhava silenciosamente em todo Purchase, quebrando o ciclo preditivo LTV
+
+### Fix de Compatibilidade D1
+- `schema-utm.sql`: `ADD COLUMN IF NOT EXISTS` → `ADD COLUMN` — D1/SQLite não suporta IF NOT EXISTS em ALTER TABLE
+
+### Sincronização Total de Agentes
+- `contracts/agent-versions.json`: worker_version `2.2.3 → 2.5.2`, 49 agentes registrados (eram 26), `depends_on` `.js → .ts`, event count `19 → 25`, table count `24 → 31`
+- `database-agent.md`: `main = "worker.js" → "index.ts"`, 24 → 31 tabelas, roadmap atualizado
+- `devops-agent.md`: `RESEND_API_KEY`, `RESEND_FROM_EMAIL`, `WEBHOOK_SECRET_TICTO` adicionados ao `*secrets`
+
+### D1 Produção
+- 31 tabelas aplicadas em `cdp-edge-db` — todos os schemas confirmados
+- Worker deployado: Version ID `37776c1a` — `/health` status: `ok`
+
+---
+
+## 📋 CHANGELOG v2.5.1 — SDK Bundle + Diagnóstico Pós-Deploy + Gap Fixes (15 de Abril de 2026) 🛠️
+
+### SDK Bundle — cdpTrack.min.js pronto para `<script src="">`
+- `npm run sdk:build` → `dist/sdk/cdpTrack.min.js` (41.6 kB, IIFE, `window.cdpTrack`)
+- Um único arquivo sem dependências externas — cola no site e funciona
+- `dist/sdk/install-snippet.html` com snippet pronto para antes do `</body>`
+
+### Diagnóstico Pós-Deploy — `cdp-edge validate <url>`
+```bash
+cdp-edge validate https://meusite.com.br
+cdp-edge validate https://meusite.com.br --worker https://worker.meusite.workers.dev
+```
+Verifica automaticamente:
+- Página carrega `cdpTrack.min.js` e Meta Pixel
+- Worker `/health` (D1, KV, AI, secrets)
+- Worker `/validate-install` (D1 write+read, KV, AI, secrets críticos)
+- `POST /track` aceita evento sintético → 200
+
+### Gap Fixes Críticos
+- **Endpoint**: `/api/tracking` → `/track` em todos os módulos SDK
+- **utm_term**: injetado pelo Worker após quiz scoring (nunca pelo cliente)
+- **TikTok ttp**: cookie `_ttp` capturado e enviado ao Worker
+- **ROAS por origem**: segmentado por `utm_content` (quiz_* vs video_* vs landing_* vs ctwa_*)
+
+### Novos Agentes
+- `lead-scoring-agent.md` — quiz de qualificação + análise dimensional Granite
+- `match-quality-agent.md` — guardião EMQ com cron 2h e alerta CallMeBot
+
+---
+
+## 📋 CHANGELOG v2.3.9 — Quiz Scoring Engine + Sales Engine (14 de Abril de 2026) 🤖💰
+
+### O que foi adicionado
+
+**ROAS Feedback Loop** (`modules/ml/roas.ts`)
+- Cruza leads com compras reais por campanha no D1
+- Calcula: `conversion_rate`, `revenue_per_lead`, `ltv_accuracy` (valida o modelo preditivo)
+- Recomendação automática de bid: `increase | maintain | decrease | pause`
+- Relatório semanal via CallMeBot com top campanhas e alertas
+- Persiste histórico em `roas_reports` + VIEW `v_roas_latest`
+
+**Nurture Engine** (`modules/nurture.ts`)
+- Sequências automáticas pós-quiz por qualificação:
+  - `interessado` → D+1, D+3, D+7 (WhatsApp)
+  - `curioso` → D+2, D+5 (conteúdo)
+  - `comprador` → contato imediato via hot lead (já existente)
+  - `perdido` → `cohort_label = excluded` (remove do remarketing)
+- `scheduleNurture()` chamado no QuizComplete em background
+- `runNurtureQueue()` executado pelo Intelligence Agent (cron diário)
+- D1: `nurture_sequences` + VIEWs de fila e stats
+
+**Lookalike Dinâmico** (`syncMetaLookalikeSeed()` em intelligence.ts)
+- Seed de Lookalike com compradores CONFIRMADOS (Purchase event) — não apenas high_intent
+- Une compradores reais + leads qualificados como `comprador` no quiz
+- Atualiza `cohort_label = buyer_confirmed` nos perfis
+- Persiste histórico em `lookalike_seeds`
+- Roda automaticamente no cron semanal do Intelligence Agent
+
+**Schema D1**: `schema-sales-engine.sql` — `roas_reports`, `nurture_sequences`, `lookalike_seeds` + 5 VIEWs
+
+### Migração
+```bash
+cd server-edge-tracker
+wrangler d1 execute cdp-edge-db --file=schema-sales-engine.sql --remote
+wrangler deploy
+```
+
+---
+
+## 📋 CHANGELOG v2.4.0 — Quiz Scoring Engine (14 de Abril de 2026) 🤖
+
+**Quiz Scoring Engine** (`modules/ml/quiz.ts`) — análise dimensional automática via Granite 4.0 Micro:
+- Detecta o TIPO de cada pergunta: `urgency | budget | timeline | fit | engagement | awareness | objection`
+- Atribui peso automático por dimensão (budget/urgency=5, fit=4, timeline=3, engagement=2)
+- Score ponderado → `comprador | interessado | curioso | perdido`
+- Fallback heurístico por palavras-chave quando AI indisponível
+- `quiz_sessions` no D1 com breakdown completo por dimensão
+
+**Integração no pipeline `/track`**:
+- `QuizComplete` + `quiz_answers[]` → scoring antes do LTV
+- `intentionLevel` qualificado alimenta LTV Prediction → `comprador` = LTV High automático
+- `QuizComplete` adicionado ao `LTV_EVENTS`
+
+**Migração**: `wrangler d1 execute cdp-edge-db --file=schema-quiz.sql --remote`
+
+---
+
+## 📋 CHANGELOG v2.3.8 — Fix Definitivo: api-versions.json (14 de Abril de 2026) 🔒
+
+`build.js` copia `extracted-skill/.../contracts/` → `contracts/` no `prepare` script. A fonte estava na v1.0.0, sobrescrevendo o arquivo correto a cada `npm publish`. Ambos os arquivos agora sincronizados em v1.1.0.
+
+---
+
+> ⚠️ **REGRA DE OURO (SQUAD):** Todas as atualizações devem ser documentadas de forma sincronizada em `README.md`, `CLAUDE.md` e `CDP-EDGE-BUSINESS-BOOK.md`. Nenhuma alteração passa sem esse tripé.
+
+---
+
+## 🤖 MANIFESTO: EU, CDP EDGE
+
+*Eu não sou um simples "script de pixel". Eu sou uma arquitetura **Enterprise Tier 10** nascida e construída 100% nativa na infraestrutura da Cloudflare.*
+
+Quando um evento de Lead bate no endpoint `/track`:
+1. **Fraud Gate:** Bloqueio bots silenciosamente antes de qualquer processamento (~2ms via KV)
+2. **Quiz Scoring Engine:** Classifico as respostas do quiz com Granite 4.0 Micro — `comprador | interessado | curioso | perdido`
+3. **A/B LTV Testing:** Sorteio de prompt via KV Cache em ~0ms
+4. **LTV Predictor:** Machine Learning para qualificar intenção e gerar valor preditivo em BRL
+5. **Nurture Scheduler:** Agendar sequência de follow-up baseada na qualificação (background)
+6. **CAPI Dispatch:** Meta/GA4/TikTok recebem payload limpo com LTV e intention injetados
+7. **Sales Engine:** Semanalmente, calculo ROAS real por campanha e atualizo o seed de Lookalike com compradores confirmados
+
+---
+
+## 🏗️ ARQUITETURA QUANTUM ENTERPRISE
+
+```
+POST /track (QuizComplete)
+  │
+  ├─ [1] 🛡️  Fraud Gate (KV blocklist + velocity) ~2ms
+  ├─ [2] 🤖  Quiz Scoring Engine (Granite 4.0 Micro) → comprador/interessado/curioso/perdido
+  ├─ [3] 🔮  A/B LTV Sorting (KV cache ~0ms)
+  ├─ [4] 🧮  LTV Prediction (Granite 4.0 Micro) — intent qualificado → High LTV
+  ├─ [5] 💾  D1 Writes background (quiz_sessions + leads + nurture_sequences)
+  └─ [6] 📡  CAPI paralelo (Meta v22.0 + GA4 + TikTok v1.3)
+
+Cron semanal (Intelligence Agent):
+  ├─ ROAS Feedback — cruza leads × purchases por campanha → bid recommendation
+  ├─ Nurture Queue — envia D+1/D+3/D+7 para leads qualificados
+  ├─ Lookalike Seed — compradores confirmados → Meta Custom Audience
+  ├─ LTV Model Training — regressão logística com dados reais
+  └─ A/B LTV Auto-winner — declara vencedor quando amostra suficiente
+```
+
+---
+
+## 📊 BANCO DE DADOS D1 — 25 Tabelas + 12 VIEWs
+
+```
+CORE TRACKING          ML & INTELLIGENCE         SALES ENGINE
+──────────────         ─────────────────────     ──────────────────
+leads                  ml_segments               roas_reports
+events                 ml_segment_members        nurture_sequences
+sessions               bid_recommendations       lookalike_seeds
+webhook_events         ltv_ab_tests              quiz_sessions
+api_failures           ltv_ab_variations
+device_graph           ltv_ab_assignments
+user_profiles          fraud_signals
+intelligence_logs      fraud_alerts
+messaging_history      match_quality_logs
+automation_rules       utm_mappings
+edge_fingerprints
+
+VIEWS (12)
+──────────────────────────────────────────────────────────────────
+v_active_segments           v_active_bid_recs
+v_ab_test_performance       v_fraud_dashboard
+v_quiz_qualification_summary v_quiz_dimension_impact
+v_roas_latest               v_nurture_pending
+v_nurture_stats             v_quiz_session_summary
+v_leads_segmented           v_ltv_feedback
+```
+
+---
+
+## 🧠 CATÁLOGO DE MÓDULOS ML
+
+| Módulo | Arquivo | Função |
+|---|---|---|
+| **Quiz Scoring** | `modules/ml/quiz.ts` | Análise dimensional automática das respostas |
+| **LTV Prediction** | `modules/ml/ltv.ts` | Score 0-100 + valor BRL via Granite + A/B test |
+| **Fraud Gate** | `modules/ml/fraud.ts` | Detecção de bots e fraude na borda |
+| **ML Clustering** | `modules/ml/segmentation.ts` | K-means vetorial com bge-m3 embeddings |
+| **Bidding ML** | `modules/ml/bidding.ts` | Recomendação de bid por segmento × plataforma |
+| **ROAS Feedback** | `modules/ml/roas.ts` | ROAS real por campanha, alimenta bidding |
+| **Match Quality** | `modules/ml/matchquality.ts` | Score de qualidade de dados para CAPI |
+| **Logistic** | `modules/ml/logistic.ts` | Regressão logística para LTV model treinável |
+| **Nurture Engine** | `modules/nurture.ts` | Sequências automáticas pós-qualificação |
+
+---
+
+## 🧠 CATÁLOGO DE AGENTES
+
+| Categoria | Agente | Função |
+|---|---|---|
+| Orquestração | `master-orchestrator.md` | Coordena todo o setup |
+| Análise | `page-analyzer.md` | Detecta CTAs, forms e nicho |
+| Plataformas | `meta-agent.md`, `google-agent.md`, `tiktok-agent.md`... | Especialistas por plataforma |
+| Infra | `server-tracking.md`, `devops-agent.md` | Arquitetura Cloudflare |
+| Enterprise | `ml-clustering-agent.md` | Segmentação dinâmica ML |
+| Enterprise | `bidding-agent.md` | Bids ML por segmento |
+| Enterprise | `ab-ltv-agent.md` | A/B testing de prompts LTV |
+| Enterprise | `fraud-detection-agent.md` | Detecção de fraude na borda |
+| Monitoramento | `intelligence-agent.md` | Cron — ROAS, Nurture, Lookalike, LTV training |
+
+---
+
+## 📋 TODOS OS ENDPOINTS
+
+### Core
+| Rota | Método | Função |
+|---|---|---|
+| `/track` | POST | Evento principal — Fraud Gate → Quiz Scoring → LTV → CAPI |
+| `/health` | GET | Smoke test D1 + KV + AI |
+| `/webhook/ticto` | POST | Purchase webhook (HMAC) |
+| `/export/customer-match` | GET | Export leads para Google Ads |
+
+### ML Clustering (Fase 1)
+| Rota | Método | Função |
+|---|---|---|
+| `/api/segmentation/cluster` | POST | K-means vetorial (bge-m3 + Granite) |
+| `/api/segmentation/list` | GET | Segmentos ativos |
+| `/api/segmentation/outliers` | GET | Outliers comportamentais |
+| `/api/segmentation/update` | PUT | Atualiza metadados |
+
+### Bidding (Fase 2)
+| Rota | Método | Função |
+|---|---|---|
+| `/api/bidding/recommend` | POST | Bid por segmento × plataforma |
+| `/api/bidding/history` | GET | Histórico de recomendações |
+| `/api/bidding/status` | GET | Snapshot atual |
+
+### A/B LTV (Fase 3)
+| Rota | Método | Função |
+|---|---|---|
+| `/api/ltv/ab-test/create` | POST | Cria experimento |
+| `/api/ltv/ab-test/list` | GET | Lista experimentos |
+| `/api/ltv/ab-test/results` | GET | Accuracy por variação |
+| `/api/ltv/ab-test/winner` | POST | Declara vencedor |
+
+### Fraud (Fase 4)
+| Rota | Método | Função |
+|---|---|---|
+| `/api/fraud/stats` | GET | Dashboard 24h |
+| `/api/fraud/alerts` | GET | Log de sinais |
+| `/api/fraud/blocklist` | GET | IPs bloqueados |
+| `/api/fraud/blocklist/add` | POST | Bloquear |
+| `/api/fraud/blocklist/remove` | DELETE | Desbloquear |
+
+---
+
+## 🚀 DEPLOY COMPLETO
+
+```bash
+cd server-edge-tracker
+
+# Schemas D1 (ordem correta — todos idempotentes)
+wrangler d1 execute cdp-edge-db --file=schema.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v6.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-segmentation.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-indexes.sql --remote
+wrangler d1 execute cdp-edge-db --file=migrate-v7.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-ltv-feedback.sql --remote  # Fase 5b: colunas LTV em user_profiles
+wrangler d1 execute cdp-edge-db --file=schema-utm.sql --remote
+wrangler d1 execute cdp-edge-db --file=schema-quiz.sql --remote        # Fase 6
+wrangler d1 execute cdp-edge-db --file=schema-sales-engine.sql --remote # Fase 7
+
+# Secrets
+wrangler secret put META_ACCESS_TOKEN
+wrangler secret put GA4_API_SECRET
+wrangler secret put TIKTOK_ACCESS_TOKEN
+
+# Deploy
+wrangler deploy
+```
+
+---
+
+## 💻 INSTALAÇÃO
+
+```bash
+npx cdp-edge install
+# ou
+npm install -g cdp-edge
+cdp-edge install . --name "Nome do Projeto"
+```
+
+---
+
+## 🗺️ GRAPHIFY — Navegando o Código
+
+```bash
+/graphify .                                          # gera o mapa
+/graphify query "como funciona o quiz scoring?"      # exploração BFS
+/graphify query "nurture engine → meta audience"     # exploração DFS
+/graphify path "quiz_answers" "meta capi"            # menor caminho
+```
+
+---
+
+### **CDP Edge — By Rica Soares**
+> "Dados sem inteligência são apenas ruído. No Quantum Tier Enterprise, transformamos dados em ROAS."
+
+© 2026 CDP Edge Premium. Todos os direitos reservados.

package/bin/cdp-edge.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+
+/**
+ * CDP Edge CLI - Entry Point
+ * Sistema multi-agente para tracking digital Quantum Tier
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { Command } from 'commander';
+import { runSetupWizard } from '../dist/commands/setup.js';
+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';
+
+// Ler versão do package.json
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = path.join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+const CDP_VERSION = packageJson.version;
+
+const program = new Command();
+
+program
+  .name('cdp-edge')
+  .description('CDP Edge Quantum Tier - Sistema multi-agente para tracking digital Cloudflare Native')
+  .version(CDP_VERSION);
+
+// Comando padrão (wizard interativo)
+program
+  .argument('[dir]', 'Diretório do projeto', '.')
+  .action(runSetupWizard);
+
+// Comandos específicos
+program
+  .command('setup [dir]')
+  .description('Configuração completa com wizard interativo')
+  .action(runSetupWizard);
+
+program
+  .command('analyze <dir>')
+  .description('Analisa páginas e detecta eventos de tracking')
+  .action(runAnalyze);
+
+program
+  .command('server <dir>')
+  .description('Gera apenas infraestrutura Cloudflare Workers + D1')
+  .action(runServer);
+
+program
+  .command('validate <url>')
+  .description('Diagnóstico pós-deploy — verifica se o tracking está funcionando de ponta a ponta')
+  .option('--worker <url>', 'URL do Worker se diferente do site (ex: https://worker.meusite.workers.dev)')
+  .action(runValidate);
+
+program
+  .command('infra')
+  .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);