cdp-edge 2.5.4 → 2.5.5

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.5** — Integração EVO CRM (OAuth2) + Sync Total de Agentes (27 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.5",
+  "worker_hash_date": "2026-04-27",
   "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,244 @@
+# 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
+
+---
+
+## 🔧 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/master-orchestrator.md

@@ -91,7 +91,7 @@ Master Orchestrator (você)
 │   ├── Database Agent                     → migrações D1, schema, índices
 │   ├── Domain Setup Agent                 → conecta track.clientdomain.com + cookie first-party
 │   ├── R2 Setup Agent                     → habilita R2, cria bucket, ativa audit log imutável
-│   └── CRM Integration Agent             → integração com CRMs externos (HubSpot, etc)
+│   └── EVO CRM Agent                     → roteia leads p/ EVO CRM (OAuth2 Doorkeeper)
 │
 ├── 💬 COMUNICAÇÃO E NOTIFICAÇÕES
 │   ├── WhatsApp Agent                     → automação Meta Cloud API + CallMeBot
@@ -173,7 +173,7 @@ SKILL_BASE: [diretório da skill tracking-events-generator]
     ├── database-agent.md                     ← migrações D1, schema, índices
     ├── domain-setup-agent.md                 ← track.clientdomain.com + Worker Route + cookie first-party
     ├── r2-setup-agent.md                     ← R2 bucket + audit log /events/YYYY-MM-DD/{uuid}.json
-    ├── crm-integration-agent.md              ← integração CRMs externos
+    ├── evo-crm-agent.md                      ← Agente EVO CRM (OAuth2)
     │
     ├── ── COMUNICAÇÃO ──
     ├── whatsapp-agent.md                     ← Meta Cloud API + CallMeBot Bridge
@@ -897,7 +897,8 @@ FASE 5 (Geração em paralelo):
   ├─ FASE 5-J: YouTube Agent        (gclid/wbraid/gbraid + video milestones)
   ├─ FASE 5-K: Microsoft Ads Agent  (UET Tag + Enhanced Conversions)
   ├─ FASE 5-D: Server Tracking Agent (index.ts — todos os platforms)
-  └─ FASE 5-E: Webhook Agent         (gateways: Hotmart, Kiwify, Eduzz, Ticto, etc.)
+  ├─ FASE 5-E: Webhook Agent         (gateways: Hotmart, Kiwify, Eduzz, Ticto, etc.)
+  └─ FASE 5-L: EVO CRM Agent         (roteia leads p/ EVO CRM)
 ```
 
 FASE 6 (Enterprise Features — ordem de configuração):
@@ -1079,8 +1080,13 @@ Exibir:
 **Bloco CartPanda** (incluir se CartPanda selecionado):
 > - `CARTPANDA_TOKEN` — Token CartPanda webhook
 
-**Bloco Monetizze** (incluir se Monetizze selecionado):
-> - `MONETIZZE_TOKEN` — Token Monetizze webhook
+**Bloco EVO CRM (OAuth2)** (incluir se CRM selecionado):
+> - `EVO_CRM_BASE_URL` — URL base (ex: https://api-evocrm.dominio.com)
+> - `EVO_CRM_CLIENT_ID` — OAuth client_id
+> - `EVO_CRM_CLIENT_SECRET` — OAuth client_secret
+> - `EVO_CRM_INBOX_ID` — ID do inbox no CRM
+> - `EVO_CRM_DEFAULT_COUNTRY` — Dial code default (ex: 55)
+> - `EVO_CRM_LOCALE` — Locale das notas (pt-BR | en-US | es-ES)
 
 **Sempre incluir:**
 > - `SITE_URL` — URL do seu funil/site (ex: https://meusite.com.br)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-edge",
-  "version": "2.5.4",
+  "version": "2.5.5",
   "description": "CDP Edge - Quantum Tracking - Sistema multi-agente para tracking digital Cloudflare Native (Workers + D1)",
   "main": "dist/index.js",
   "type": "module",

package/server-edge-tracker/INSTALAR.md

@@ -366,8 +366,8 @@ pattern  = "SEU_DOMINIO/track*"      # ← Substituir pelo domínio real
 zone_name = "SEU_DOMINIO"            # ← Substituir pelo domínio real
 
 # Exemplo real:
-# pattern  = "lancamentosabc.com.br/track*"
-# zone_name = "lancamentosabc.com.br"
+# pattern  = "cliente.com.br/track*"
+# zone_name = "cliente.com.br"
 ```
 
 #### 3. Fazer o deploy com as rotas

package/server-edge-tracker/index.ts

@@ -63,6 +63,9 @@ import {
   processWhatsAppWebhook,
   verifyHmac,
 } from './modules/dispatch/whatsapp';
+import {
+  pushLeadToCrm,
+} from './modules/dispatch/crm';
 
 // ── ML — LTV + A/B Testing ────────────────────────────────────────────────────
 import {
@@ -239,6 +242,9 @@ export default {
         WA_NOTIFY_NUMBER:         env.WA_NOTIFY_NUMBER         ? 'set' : 'not set (optional - only for auto-reply)',
         TIKTOK_ACCESS_TOKEN:      env.TIKTOK_ACCESS_TOKEN      ? 'set' : 'not set (optional)',
         CALLMEBOT_PHONE:          env.CALLMEBOT_PHONE          ? 'set' : 'not set (optional)',
+        EVO_CRM_BASE_URL:         env.EVO_CRM_BASE_URL         ? 'set' : 'not set (optional - EVO CRM)',
+        EVO_CRM_CLIENT_ID:        env.EVO_CRM_CLIENT_ID        ? 'set' : 'not set (optional - EVO CRM)',
+        EVO_CRM_INBOX_ID:         env.EVO_CRM_INBOX_ID         ? 'set' : 'not set (optional - EVO CRM)',
       };
 
       const hasMissing =
@@ -793,6 +799,39 @@ export default {
           : []),
       ]);
 
+      // ── EVO CRM — cria contato + conversa + nota interna ─────────────────
+      // Silencioso se EVO_CRM_BASE_URL / EVO_CRM_CLIENT_ID não estiverem configurados.
+      const CRM_EVENTS = ['Lead', 'Contact', 'CompleteRegistration'];
+      if (CRM_EVENTS.includes(eventName) && trackPayload.phone) {
+        ctx.waitUntil(
+          pushLeadToCrm(env, {
+            phone:        trackPayload.phone,
+            name:         [trackPayload.firstName, trackPayload.lastName].filter(Boolean).join(' ') || null,
+            email:        trackPayload.email        || null,
+            fbclid:       trackPayload.fbclid       || null,
+            fbc:          trackPayload.fbc          || null,
+            fbp:          trackPayload.fbp          || null,
+            utmSource:    trackPayload.utmSource    || null,
+            utmMedium:    trackPayload.utmMedium    || null,
+            utmCampaign:  trackPayload.utmCampaign  || null,
+            utmContent:   trackPayload.utmContent   || null,
+            utmTerm:      trackPayload.utmTerm      || null,
+            pageUrl:      trackPayload.pageUrl      || null,
+            formName:     trackPayload.contentName  || trackPayload.productName || eventName,
+            eventName,
+            intentScore:  typeof trackPayload.intent_score === 'number'
+                            ? trackPayload.intent_score
+                            : typeof trackPayload.intentScoreNum === 'number'
+                              ? trackPayload.intentScoreNum
+                              : null,
+            ltvClass:     trackPayload.ltvClass     || null,
+            funnelStage:  trackPayload.funnel_stage || trackPayload.funnelDepth || null,
+            value:        trackPayload.value        ?? null,
+            currency:     trackPayload.currency     || null,
+          })
+        );
+      }
+
       // Automação de mensagens
       const AUTOMATION_EVENTS = ['Lead', 'Purchase', 'InitiateCheckout'];
       if (AUTOMATION_EVENTS.includes(eventName) && env.DB) {