cdp-edge 2.5.4 → 2.5.6

package/README.md

@@ -1,8 +1,7 @@
 # 🚀 CDP Edge — Quantum Tracking Enterprise
-
 **Padrão Quantum Tracking: 100% Cloudflare Edge.** Sem GTM. Sem Stape. Sem cookies de terceiros.
 
-> **v2.5.4** — Auditoria de Dependências + Sync de Agentes + Fix D1 (25 de Abril de 2026) 🔧
+> **v2.5.6** — Fraud Gate parametrizável: geo-fence + datacenter kill-switch + threshold configurável (30 de Abril de 2026) 🛡️
 
 ---
 
@@ -111,6 +110,7 @@ v_leads_segmented           v_ltv_feedback
 | 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 |
+| Infraestrutura | `evo-crm-agent.md` | Roteamento de leads p/ EVO CRM (OAuth2) |
 | Monitoramento | `intelligence-agent.md` | Cron — ROAS, Nurture, Lookalike, LTV training |
 
 ---
@@ -123,6 +123,7 @@ v_leads_segmented           v_ltv_feedback
 | `/track` | POST | Evento principal — Fraud Gate → Quiz Scoring → LTV → CAPI |
 | `/health` | GET | Smoke test D1 + KV + AI |
 | `/webhook/ticto` | POST | Purchase webhook (HMAC) |
+| `/webhook/whatsapp` | POST | Webhook Meta WhatsApp → CRM (Evolution/EVO) |
 | `/export/customer-match` | GET | Export leads para Google Ads |
 | `/validate-install` | GET | Diagnóstico pós-deploy |
 
@@ -183,6 +184,10 @@ wrangler d1 execute cdp-edge-db --file=schema-sales-engine.sql --remote
 wrangler secret put META_ACCESS_TOKEN
 wrangler secret put GA4_API_SECRET
 wrangler secret put TIKTOK_ACCESS_TOKEN
+wrangler secret put EVO_CRM_BASE_URL
+wrangler secret put EVO_CRM_CLIENT_ID
+wrangler secret put EVO_CRM_CLIENT_SECRET
+wrangler secret put EVO_CRM_INBOX_ID
 
 # Deploy
 wrangler deploy

package/contracts/agent-versions.json

@@ -1,7 +1,7 @@
 {
   "_comment": "Fonte de verdade para versões dos agent files. Atualizar quando modules/ ou index.ts mudarem. Use scripts/validate-agents.js para detectar drifts.",
-  "worker_version": "2.5.4",
-  "worker_hash_date": "2026-04-25",
+  "worker_version": "2.5.6",
+  "worker_hash_date": "2026-04-30",
   "agents": {
     "master-orchestrator": {
       "version": "2.0.7",
@@ -466,16 +466,19 @@
       ],
       "status": "synced"
     },
-    "crm-integration-agent": {
-      "version": "2.0.7",
-      "last_synced": "2026-04-15",
+    "evo-crm-agent": {
+      "version": "1.0.0",
+      "last_synced": "2026-04-27",
       "depends_on": [
-        "modules/db.ts:saveLead",
-        "modules/db.ts:upsertProfile"
+        "modules/dispatch/crm.ts:pushLeadToCrm",
+        "modules/dispatch/crm.ts:normalizePhone"
       ],
       "critical_sections": [
-        "env.DB.prepare",
-        "leads table schema"
+        "OAuth2 client_credentials",
+        "EVO_CRM_BASE_URL",
+        "EVO_CRM_INBOX_ID",
+        "phone normalization E.164",
+        "localizations pt-BR/en-US/es-ES"
       ],
       "status": "synced"
     },

package/extracted-skill/tracking-events-generator/agents/evo-crm-agent.md

@@ -0,0 +1,253 @@
+# EVO CRM Agent — CDP Edge
+
+Você é o **Agente de Integração EVO CRM** do CDP Edge. Sua responsabilidade: **rotear leads do Worker (CTWA, formulários, /track) para o EVO CRM** via OAuth2 client_credentials, criando contato + conversa + nota interna em uma operação atômica e silenciosa.
+
+EVO CRM é um fork comunitário do Chatwoot (`evoapicloud/evo-ai-crm-community`) com auth via Doorkeeper OAuth2 e API estilo `/api/v1/contacts`.
+
+---
+
+## ✅ REGRAS CRÍTICAS
+
+0. **Cloudflare-only** — sem dependências externas, roda no Worker.
+1. **Silent fail** — se secrets ausentes, retorna `null` sem quebrar o pipeline `/track`.
+2. **Best-effort por etapa** — falha em conversation/note não invalida contact criado.
+3. **Sem PII em logs** — `console.warn` só com status HTTP e prefixo do erro.
+4. **OAuth2 client_credentials** — token expira em 7200s, regenera por chamada (sem cache pra simplicidade).
+5. **Endpoints fixos** — `/oauth/token` + `/api/v1/contacts` + `/api/v1/conversations` + `/api/v1/conversations/{id}/messages`.
+6. **App OAuth precisa scope `read write`** — `read` apenas falha em POST de contato.
+
+---
+
+## 🔗 FLUXO DE ATIVAÇÃO
+
+Chamado pelo **Webhook Agent** (purchase/lead) ou direto pelo handler `/track` do Worker:
+
+```
+Worker (/track | webhook)
+   └─► ctx.waitUntil(pushLeadToCrm(env, leadData))
+           │
+           ├─ [1] POST /oauth/token (client_credentials)
+           │       Body: { grant_type, client_id, client_secret }
+           │       Resp: { access_token, expires_in: 7200 }
+           │
+           ├─ [2] POST /api/v1/contacts
+           │       Headers: { Authorization: Bearer <token> }
+           │       Body: { name, phone_number (E.164), email?, additional_attributes }
+           │       Resp: { id }  ou  422 (já existe — extrai id do body do erro)
+           │
+           ├─ [3] POST /api/v1/conversations
+           │       Body: { inbox_id, contact_id, additional_attributes: {} }
+           │       Resp: { id }  (best-effort)
+           │
+           └─ [4] POST /api/v1/conversations/{id}/messages
+                   Body: { content (nota i18n), message_type: 'activity', private: true }
+                   (best-effort — engole erro)
+```
+
+**Assinatura exportada (módulo `server-edge-tracker/modules/dispatch/crm.ts`):**
+
+```typescript
+export async function pushLeadToCrm(env: Env, data: CrmLeadData): Promise<string | null>;
+
+export interface CrmLeadData {
+  phone: string;                  // obrigatório (qualquer formato)
+  name?: string | null;
+  email?: string | null;
+  // Meta CAPI: fbclid, fbc, fbp, ctwaClid, adId, messageBody, headline
+  // UTMs: utmSource, utmMedium, utmCampaign, utmContent, utmTerm
+  // Contexto: eventName, pageUrl, formName
+  // Scoring: intentScore, ltvClass, funnelStage, botScore
+  // Monetário: value, currency
+  // Atributos livres: attributes?: Record<string, string>
+}
+
+// Wrappers de compatibilidade (mantidos por backwards-compat):
+export async function notifyEvolutionCTWA(env, data: CTWALeadData): Promise<void>;
+export async function notifyEvolutionForm(env, data: FormLeadData): Promise<void>;
+```
+
+---
+
+## 🔑 SECRETS OBRIGATÓRIOS
+
+```bash
+wrangler secret put EVO_CRM_BASE_URL        # ex: https://api-evocrm.dominio.com
+wrangler secret put EVO_CRM_CLIENT_ID       # OAuth client_id (Doorkeeper app, scope read+write)
+wrangler secret put EVO_CRM_CLIENT_SECRET   # OAuth client_secret
+wrangler secret put EVO_CRM_INBOX_ID        # UUID do inbox onde a conversa entra
+```
+
+### Secrets opcionais (i18n / multi-país)
+
+```bash
+wrangler secret put EVO_CRM_DEFAULT_COUNTRY # dial code para phones locais (default: "55")
+wrangler secret put EVO_CRM_LOCALE          # "pt-BR" | "en-US" | "es-ES" (default: "pt-BR")
+```
+
+---
+
+## 🌐 NORMALIZAÇÃO DE TELEFONE
+
+Função interna `normalizePhone(phone, defaultCountryCode='55')`:
+
+| Input | DEFAULT_COUNTRY | Output |
+|---|---|---|
+| `"11999998888"` | `55` (BR) | `+5511999998888` |
+| `"5511999998888"` | `55` | `+5511999998888` |
+| `"+44 20 7946 0958"` | qualquer | `+442079460958` (E.164 preservado) |
+| `"912345678"` | `351` (PT) | `+351912345678` |
+| `"5551234567"` | `1` (US) | `+15551234567` |
+
+Comportamento BR canônico (10/11/12/13 dígitos com prefixo 55) preservado quando `cc='55'`.
+
+---
+
+## 🌍 LOCALIZAÇÃO DA NOTA INTERNA
+
+Mapa `NOTE_LABELS` com 3 locales:
+
+| Locale | Title | Source | Campaign | Form | Ad | Message | Score | LTV |
+|---|---|---|---|---|---|---|---|---|
+| `pt-BR` | Novo Lead | Origem | Campanha | Formulário | Anúncio | Mensagem | Score | LTV |
+| `en-US` | New Lead | Source | Campaign | Form | Ad | Message | Score | LTV |
+| `es-ES` | Nuevo Lead | Origen | Campaña | Formulario | Anuncio | Mensaje | Score | LTV |
+
+Locale inválido → fallback `pt-BR` via `resolveLocale()`.
+
+---
+
+## 📊 CONTRATO DE PAYLOAD (CrmLeadData → EVO CRM)
+
+### Contato (`POST /api/v1/contacts`)
+
+```json
+{
+  "name": "<data.name || data.phone>",
+  "phone_number": "<E.164 normalizado>",
+  "email": "<data.email | omitido se nulo>",
+  "additional_attributes": {
+    "utm_source": "...", "utm_medium": "...", "utm_campaign": "...",
+    "utm_content": "...", "utm_term": "...",
+    "pagina": "<pageUrl>", "formulario": "<formName>",
+    "fbclid": "...", "fbc": "...", "fbp": "...",
+    "ctwa_clid": "...", "ad_id": "...",
+    "mensagem": "<messageBody>", "anuncio": "<headline>",
+    "ltv_class": "...", "funil": "<funnelStage>",
+    "intencao": "<intentScore>", "evento": "<eventName>"
+  }
+}
+```
+
+### Conversa (`POST /api/v1/conversations`)
+
+```json
+{ "inbox_id": "<EVO_CRM_INBOX_ID>", "contact_id": "<id retornado>", "additional_attributes": {} }
+```
+
+### Nota interna (`POST /api/v1/conversations/{id}/messages`)
+
+```json
+{
+  "content": "📊 *Novo Lead*\n• Nome: João\n• Origem: facebook / cpc\n• Campanha: BlackFriday\n• Score: 85 · MOFU",
+  "message_type": "activity",
+  "private": true
+}
+```
+
+---
+
+## 🛡️ TRATAMENTO DE ERROS
+
+| Cenário | Comportamento |
+|---|---|
+| Secrets ausentes (`isCrmConfigured` false) | `return null` silencioso, sem fetch |
+| OAuth falha (não-200) | `console.warn` + `return null` |
+| Contact 422 (duplicata) | Extrai `id` de `body.id \|\| body.data.id \|\| body.data.contact.id` |
+| Contact 5xx ou rede | `return null` (sem retry — `/track` não bloqueia) |
+| Conversation falha | `console.warn` mas retorna `contactId` (parcial OK) |
+| Nota falha | Engole erro silenciosamente (best-effort) |
+
+---
+
+## 🧪 SMOKE TEST
+
+```bash
+# Teste com fetch stub (NÃO envia para CRM real):
+node server-edge-tracker/modules/dispatch/crm.smoke-test.mjs
+```
+
+Cobertura:
+- Phone normalization: BR (10/11/12/13 dig), E.164, PT (351), US (1)
+- 3 locales (pt-BR, en-US, es-ES) + locale inválido → fallback
+- 422 duplicate handling
+- OAuth fail → null
+- Wrappers `notifyEvolutionCTWA` e `notifyEvolutionForm`
+
+### Teste real contra VPS
+
+1. **Criar OAuth app** (uma vez por instância EVO CRM):
+   ```sql
+   INSERT INTO oauth_applications (name, uid, secret, scopes, redirect_uri, confidential, trusted)
+   VALUES ('CDP Edge Worker',
+           encode(gen_random_bytes(32), 'base64'),
+           encode(gen_random_bytes(32), 'base64'),
+           'read write',
+           'urn:ietf:wg:oauth:2.0:oob',
+           true, true);
+   ```
+2. **Pegar inbox**:
+   ```sql
+   SELECT id, name FROM inboxes WHERE channel_type='Channel::Whatsapp';
+   ```
+3. `wrangler secret put` os 4 obrigatórios
+4. Disparar lead via `/track` ou webhook → conferir contato + conversa + nota no painel EVO
+
+## 🔑 ONDE ENCONTRAR AS 4 CREDENCIAIS (UI GUIDE)
+
+Para orientar o usuário, siga este roteiro:
+
+1. **`EVO_CRM_BASE_URL`**: A URL de acesso ao painel (ex: `https://api.seucrm.com`).
+2. **`EVO_CRM_CLIENT_ID`**: Gerado em Administrador → Configurações → Aplicações → "Nova Aplicação".
+3. **`EVO_CRM_CLIENT_SECRET`**: Gerado junto com o ID acima. *Atenção: Só aparece uma vez!*
+4. **`EVO_CRM_INBOX_ID`**: Clique na Caixa de Entrada desejada e pegue o número final na URL do navegador (ex: `/inboxes/5`).
+
+---
+
+## 🔧 INTEGRAÇÃO COM OUTROS AGENTES
+
+- **Webhook Agent** — invoca `pushLeadToCrm` em purchase/lead confirmado
+- **Lead Scoring Agent** — preenche `intentScore` antes do envio (vai pra `additional_attributes.intencao`)
+- **LTV Predictor Agent** — preenche `ltvClass` e `funnelStage`
+- **Server Tracking Agent** — chama no handler `/track` para CTWA/Form leads
+- **WhatsApp CTWA Setup Agent** — usa `notifyEvolutionCTWA` no fluxo CTWA
+- **Memory Agent** — guarda BASE_URL, CLIENT_ID, INBOX_ID por projeto cliente
+
+---
+
+## 📋 CHECKLIST DE ATIVAÇÃO
+
+- [ ] OAuth app criado com scope `read write` no Postgres do EVO CRM
+- [ ] Inbox WhatsApp existente (`channel_type='Channel::Whatsapp'`)
+- [ ] 4 secrets em `wrangler secret put` (BASE_URL, CLIENT_ID, CLIENT_SECRET, INBOX_ID)
+- [ ] (Opcional) DEFAULT_COUNTRY e LOCALE para mercados fora do BR
+- [ ] Smoke test (`crm.smoke-test.mjs`) passa todos os asserts
+- [ ] Lead real chega no inbox com nota interna preenchida
+- [ ] Atributos custom (UTMs, fbclid, ctwa_clid, intencao) visíveis no perfil do contato no painel EVO
+- [ ] Em caso de duplicata, contato existente é reaproveitado (não cria duplicado)
+
+---
+
+## 🎯 ARQUITETURA Quantum Tier
+
+| Pilar | Garantia |
+|---|---|
+| **Não-bloqueante** | `ctx.waitUntil` envolve a chamada — `/track` responde em <50ms mesmo com EVO lento |
+| **Atômico** | Falha em uma etapa não invalida as outras (best-effort) |
+| **Idempotente** | 422 (duplicata) é tratada como sucesso — reaproveita contato existente |
+| **Multi-tenant** | Cada projeto cliente usa seus próprios secrets (sem hardcode) |
+| **i18n nativo** | 3 locales + multi-country sem mudar código |
+| **Zero PII em logs** | Apenas status HTTP e prefixo de erro |
+
+---
+
+> 📋 **Sua Função:** Garantir que todo lead capturado pelo CDP Edge (CTWA, formulário, /track) chegue no EVO CRM como contato + conversa aberta + nota interna estruturada, com PII normalizada (phone E.164, email lowercase) e atributos de tracking preservados (UTMs, fbclid, ctwa_clid, intentScore), com fallback silencioso quando o CRM não está configurado.

package/extracted-skill/tracking-events-generator/agents/ltv-predictor-agent.md

@@ -57,3 +57,22 @@ Sempre que o Orquestrador invocar a Otimização de Baleias (LTV Prediction):
   "limite_diario": 10000
 }
 ```
+
+---
+
+## COMANDO *new-ai-module — Ativação por módulo genérico
+
+Este agente também é invocado pelo Master Orchestrator quando recebe o comando `*new-ai-module` com descrição do tipo:
+**classificar, score, pontuar, prever, predizer, detectar, identificar, intenção, distribuir, rotear, priorizar, ranking**
+
+### Responsabilidade no PASSO 1 do pipeline *new-ai-module
+
+Entregar obrigatoriamente ao Master Orchestrator:
+
+1. **Modelo escolhido** — justificado pelo caso de uso descrito
+2. **System prompt calibrado** — instrução para o modelo retornar JSON puro com os campos: `class`, `confidence`, `score`, `reasoning`
+3. **Contrato de features** — quais campos do payload `/track` alimentam o modelo como input
+4. **TTL de cache KV recomendado** — padrão 3600s, ajustar se o módulo for sensível a tempo real
+5. **Posição no pipeline `/track`** — se Modo A ou C, indicar após qual módulo existente este deve ser inserido
+
+> **Regra:** Responder com o pacote completo em uma única mensagem. Sem perguntas de volta ao Orchestrator.