🚀 CDP Edge — Quantum Tracking Enterprise

Padrão Quantum Tracking: 100% Cloudflare Edge. Sem GTM. Sem Stape. Sem cookies de terceiros.

v2.3.0 — TypeScript Nativo · Worker 100% tipado · types.ts centralizado · tsconfig.json · tsc --noEmit zero erros · Cloudflare Workers · Meta CAPI v22.0 · GA4 MP · TikTok Events API v1.3

⚠️ REGRA DE OURO (SQUAD): Todas as atualizações, correções ou novas features devem OBRIGATORIAMENTE ser documentadas de forma sincronizada neste README.md, no arquivo de instruções CLAUDE.md e no dossiê de diretoria 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.

A Linha de Montagem Sincronizada (A Prova de Latência) Meu ecossistema opera como um Cérebro de Conversão Privado na borda. Quando um evento de Lead bate no endpoint /track:

1. O Escudo Frontal (Fraud Gate): Inspeciono IP, ASN e Velocity na borda. Bloqueio bots silenciosamente antes mesmo deles carregarem.
2. A Roleta Invisível (A/B LTV): Faço o sorteio de prompts para testes A/B via KV Cache em ~0ms.
3. O Cérebro Financeiro (LTV Predictor): Rodo Machine Learning (Granite 4.0 Micro) para qualificar a intenção e gerar o LTV Preditivo.
4. Envio para as Plataformas: O Facebook/Google/LinkedIn recebem um payload limpo (sem bot) recheado com valor financeiro de intenção extrema.
5. Máquina Autônoma (Background): Meu banco SQLite (D1) retroalimenta os processos de Clustering (Fase 1) e Bidding (Fase 2) de forma autônoma pelas costas do usuário (ctx.waitUntil).

Minha Vantagem Absoluta (A "Killer Feature")

• A Extinção da Latência: Destruo concorrentes como GTM/Stape mitigando a latência do servidor (+150ms) para as antenas da Cloudflare Brasileira (~5ms). Custando absurdamente menos (Tier Free ou $5/mês na infraestrutura).
• Cookies Indestrutíveis: Meus First-Party Cookies Seguros originam diretamente da nuvem, imunes hoje às varreduras massivas de 24 horas usadas por AdBlockers e Safari (Apple ITP).
• Filas Inquebráveis (Fail-Safe + Queues): Se a AI Cloudflare cair ocasionalmente, eu recuo pro LTV $0. Se a Meta CAPI espirrar 500 downtime, o sistema guarda religiosamente os seus eventos caros em Cloudflare Queues e faz o retry sucessivo. Sou incansável na garantia de Event Match Quality (EMQ).

📋 CHANGELOG v2.3.0 — TypeScript Nativo (12 de Abril de 2026)

🔷 Worker 100% TypeScript — Migração Completa

Todo o código server-side (server-edge-tracker/) foi migrado de JavaScript para TypeScript nativo. O Wrangler compila diretamente o .ts via esbuild — sem etapa de build separada, sem configuração extra.

Por que TypeScript muda o jogo no CDP Edge:

• Env tipado — typos em nomes de secrets (META_ACCESS_TOKEN, GEO_CACHE, DB) viram erros em build time, nunca em produção
• TrackPayload contratado — o shape do payload entre browser e Worker é garantido pelo compilador
• Cloudflare types nativos — D1, KV, R2, Workers AI com autocomplete e validação de métodos
• Fraud Gate e ML seguros — checkFraudGate(env: Env, request: Request, payload: TrackPayload) — nenhum undefined passa despercebido
• Refatoração segura — renomear qualquer campo do TrackPayload lista automaticamente todos os pontos de quebra

Arquivos migrados (JS → TS) — 16 módulos:

• index.ts — entry point do Worker
• types.ts — novo — contratos centralizados: Env, TrackPayload, BehavioralData, HotmartWebhook, KiwifyWebhook, TictoWebhook, QueueMessage, PromiseResult<T>
• modules/utils.ts, modules/db.ts, modules/intelligence.ts
• modules/dispatch/ — meta.ts, ga4.ts, tiktok.ts, platforms.ts, whatsapp.ts
• modules/ml/ — ltv.ts, fraud.ts, bidding.ts, segmentation.ts, logistic.ts, matchquality.ts

Infraestrutura:

• tsconfig.json — target: ESNext, moduleResolution: "bundler", strict: true, @cloudflare/workers-types
• wrangler.toml — main = "index.ts" (TypeScript nativo via wrangler/esbuild)
• contracts/types.ts — tipos públicos exportados no pacote NPM: QuantumEventPayload, AgencyContext, ApiVersionsConfig
• npm run typecheck — tsc --noEmit (225 testes passando, zero erros de compilação)

Breaking change: nenhuma — API HTTP e comportamento em runtime são idênticos. TypeScript é invisível para o Cloudflare.

📋 CHANGELOG v2.2.5 (11 de Abril de 2026)

🔧 Correção de Versão Dinâmica

• Versão Dinâmica: bin/cdp-edge.js e dist/commands/install.js agora leem a versão do package.json dinamicamente
• Banner Corrigido: O banner de instalação agora mostra sempre a versão correta (cdp-edge --version)
• Compatibilidade: Garante que a versão exibida no CLI e banner esteja sempre sincronizada com o package.json

📋 CHANGELOG v2.2.0 (10 de Abril de 2026)

🤖 AI Engine Upgrade — Novos Modelos

• LTV Prediction: @cf/meta/llama-3.1-8b-instruct → @cf/ibm-granite/granite-4.0-h-micro (menor latência, otimizado para edge e function calling)
• ML Clustering: algoritmo LLM simulado → K-means vetorial real com embeddings @cf/baai/bge-m3 (distância cosseno, K-means++ inicialização, silhouette score real)
• Granite continua sendo usado para naming dos segmentos pós-clustering

🧹 Limpeza (Zero Lixo)

• Removido: detecção de emails descartáveis (mailinator, guerrilla, tempmail, etc.) do Fraud Gate e do agente fraud-detection-agent.md
• Removido: secrets WEBHOOK_SECRET_HOTMART e WEBHOOK_SECRET_KIWIFY (wrangler + wrangler.toml)

🔧 Observability

• Adicionado bloco [observability] no wrangler.toml (logs.enabled = true, traces.enabled = false)

📋 CHANGELOG v2.0.7 (10 de Abril de 2026)

🔧 Audit Completo — 45 Agentes

• Endpoints corrigidos: /api/tracking → /track, /api/wh/ → /webhook/ em todos os agentes
• Secrets WhatsApp: WA_PHONE_ID/WA_ACCESS_TOKEN/WHATSAPP_TOKEN → WHATSAPP_PHONE_NUMBER_ID/WHATSAPP_ACCESS_TOKEN
• env.DB.prepare: corrigido em 8 agentes (attribution, crm, dashboard, debug, performance, security, master-feedback-loop)
• env.GEO_CACHE: substituiu KV. bare em dashboard-agent, performance-agent, performance-optimization-agent
• YouTube events: video_milestone/video_progress_25/50/75 → video_25/video_50/video_75 (alinhado ao VALID_EVENT_NAMES do worker)
• LinkedIn CAPI: endpoint /rest/conversionEvents + header LinkedIn-Version: 202401 em contracts/api-versions.json
• Workers AI model: llama-3-8b-instruct → @cf/meta/llama-3.1-8b-instruct
• index.ts: Content-Length guard (413 se > 64KB), payload validation (allowlist 19 events, 512 chars, value range), PII removido dos logs
• Testes: bugs críticos em deduplication.test.js corrigidos (template literals escapados, prefixo errado)
• npm: lodash 4.17.23 → 4.18.1, node-fetch removido

📋 CHANGELOG v2.0.0 (9 de Abril de 2026)

🆕 Sprint Enterprise — Fases 1 a 4

✅ Fase 1 — ML Clustering (Segmentação Dinâmica)

• POST /api/segmentation/cluster — K-means / DBSCAN / Hierarchical via Workers AI
• GET /api/segmentation/list — Segmentos ativos com métricas
• GET /api/segmentation/outliers — Detecção de outliers comportamentais
• PUT /api/segmentation/update — Atualização de metadados de segmento
• Schema D1: ml_segments, ml_segment_members + VIEWs otimizadas
• Agente: ml-clustering-agent.md

✅ Fase 2 — Bidding Recommendations (Otimização de Bids ML)

• POST /api/bidding/recommend — Bid otimizado por segmento × plataforma (Meta/Google/TikTok), calculado com fórmula LTV × ROI target / CPA base
• GET /api/bidding/history — Histórico completo de recomendações
• GET /api/bidding/status — Snapshot atual das recomendações ativas por vertical
• Schema D1: bid_recommendations + VIEW v_active_bid_recommendations
• Agente: bidding-agent.md

✅ Fase 3 — A/B Testing de Prompts LTV

• POST /api/ltv/ab-test/create — Cria experimento com múltiplas variações de system prompt
• GET /api/ltv/ab-test/list — Lista experimentos com status e progresso
• GET /api/ltv/ab-test/results — Accuracy score por variação + recomendação automática de winner
• POST /api/ltv/ab-test/winner — Declara vencedor e retorna o prompt ganador
• Integração automática: cada evento Lead sorteia a variação ativa e registra o assignment via KV cache
• Schema D1: ltv_ab_tests, ltv_ab_variations, ltv_ab_assignments + VIEW v_ab_test_performance
• Agente: ab-ltv-agent.md

✅ Fase 4 — Fraud Detection Engine

• Fraud Gate automático em /track — roda ANTES de qualquer processamento (heurístico puro, ~2ms)
• Silent drop (retorna 200 falso) — bots não detectam a defesa
• GET /api/fraud/stats — Dashboard de fraude (últimas 24h)
• GET /api/fraud/alerts — Log de sinais detectados com filtros
• GET /api/fraud/blocklist — IPs/fingerprints atualmente bloqueados
• POST /api/fraud/blocklist/add — Bloquear IP ou fingerprint (via KV, efeito imediato)
• DELETE /api/fraud/blocklist/remove — Remover do blocklist
• Sinais detectados: bot_score, datacenter IP, velocity attack, headless UA, sem Accept-Language
• Schema D1: fraud_signals, fraud_alerts + VIEW v_fraud_dashboard
• Agente: fraud-detection-agent.md

🔧 Fix: wrangler.toml atualizado

• Todos os placeholders (SEU_D1_DATABASE_ID, SEU_KV_NAMESPACE_ID) substituídos pelos IDs reais da conta Cloudflare
• D1: SEU_DATABASE_ID
• KV: SEU_KV_ID

🏗️ ARQUITETURA QUANTUM ENTERPRISE (CLOUDFLARE NATIVE)

graph TD
    User((Usuário)) -->|Interação| SDK[cdpTrack SDK + Behavior Engine]
    SDK -->|Edge Fetch 1ª via KV blocklist| FraudGate{🛡️ Fraud Gate}
    FraudGate -->|score ≥ 80: Silent Drop 200| Void[/dev/null]
    FraudGate -->|score < 80: Permitido| Worker[Cloudflare Worker Agent]
    Worker -->|Identity Graph + _cdp_uid| D1[(D1 SQL — 21 tabelas)]
    Worker -->|LTV + A/B Prompt| AI[Workers AI Granite 4.0 Micro]
    Worker -->|Segmento ML| Cluster[ML Clustering Engine]
    Cluster -->|Bid otimizado| Bidding[Bidding Recommendations]
    Worker -->|Background| Queue[Cloudflare Queues]
    Queue -->|Server Dispatch| Meta[Meta CAPI v22.0]
    Queue -->|Server Dispatch| Google[GA4 / Google Ads]
    Queue -->|Server Dispatch| TikTok[TikTok API v1.3]
    D1 -->|Reports| Dash[Dashboard Agent]

🧠 CATÁLOGO DE AGENTES ESPECIALISTAS

O sistema é composto por 43+ agentes coordenados pelo Master Orchestrator:

🧠 Núcleo de Inteligência

🚀 Plataformas de Anúncio

🤖 Enterprise Intelligence (Fase 1–4)

🛡️ Módulos Enterprise

📊 BANCO DE DADOS D1 — 21 Tabelas

CORE TRACKING           ML & INTELLIGENCE        ENTERPRISE SECURITY
─────────────────        ─────────────────────    ─────────────────────
leads                   ml_segments               fraud_signals
events                  ml_segment_members        fraud_alerts
sessions                bid_recommendations       ltv_ab_tests
webhook_events          ltv_ab_tests              ltv_ab_variations
api_failures            ltv_ab_variations         ltv_ab_assignments

VIEWS
─────────────────────────────────────────────────
v_active_segments          → Segmentos ML ativos com contagem de membros
v_active_bid_recs          → Bids ativos por plataforma/vertical
v_ab_test_performance      → Accuracy por variação de prompt
v_fraud_dashboard          → Dashboard fraude 24h

🔄 FLUXO ENTERPRISE COMPLETO

POST /track (evento Lead)
  │
  ├─ [1] 🛡️ Fraud Gate (KV blocklist + velocity + heurísticas) ~2ms
  │         ├─ score < 40  → processa normalmente
  │         ├─ score 40-79 → processa + loga suspeito (background)
  │         └─ score ≥ 80  → silent drop 200 + loga (background)
  │
  ├─ [2] 🔮 A/B LTV Testing — sorteia variação ativa (KV cache ~0ms)
  │         └─ passa customSystemPrompt para predictLtv()
  │
  ├─ [3] 🧮 LTV Prediction — Workers AI Granite 4.0 Micro
  │         └─ Score 0-100 → class High/Medium/Low → valor em BRL
  │
  ├─ [4] 💾 D1 Writes (background via ctx.waitUntil)
  │         ├─ upsertLtvProfile() → tabela leads
  │         ├─ recordAbAssignment() → ltv_ab_assignments
  │         └─ resolveDeviceGraph() → cross-device linking
  │
  └─ [5] 📡 CAPI dispatch (Meta + GA4 + TikTok em paralelo)
            └─ com LTV injetado no value field

💻 INSTALAÇÃO E USO

OPÇÃO 1 — Instalação via npm (Recomendada)

Abra o terminal dentro da pasta do projeto do cliente e rode:

npx cdp-edge install

Ou instale globalmente e use em qualquer projeto:

npm install -g cdp-edge
cdp-edge install . --name "Nome do Projeto"

Já tem o CDP Edge instalado globalmente? Atualize para a versão mais recente:

npm install -g cdp-edge@latest

OPÇÃO 2 — Instalação via Git Clone

git clone https://github.com/ricardosoli777/CDP-Edge-Premium.git .

(O ponto no final garante que os arquivos desçam diretamente dentro da pasta atual).

Ativar no Claude Code

claude .

Dentro do Claude Code:

/cdp

🚀 DEPLOY COMPLETO (referência)

cd server-edge-tracker

# 1. Schemas D1 (todos em sequência)
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  # Fase 1
wrangler d1 execute cdp-edge-db --file=schema-bidding.sql --remote        # Fase 2
wrangler d1 execute cdp-edge-db --file=schema-ab-ltv.sql --remote         # Fase 3
wrangler d1 execute cdp-edge-db --file=schema-fraud.sql --remote           # Fase 4

# 2. Secrets
wrangler secret put META_ACCESS_TOKEN
wrangler secret put GA4_API_SECRET
wrangler secret put TIKTOK_ACCESS_TOKEN

# 3. Deploy
wrangler deploy

🖱️ HUMAN-BEHAVIOR ENGINE

📋 TODOS OS ENDPOINTS (referência rápida)

Core Tracking

Intelligence ML

A/B Testing LTV

Fraud Detection

📞 SUPORTE

• Issues: https://github.com/ricardosoli777/CDP-Edge-Premium/issues
• Releases: https://github.com/ricardosoli777/CDP-Edge-Premium/releases

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.