npm - cdp-edge - Versions diffs - 1.2.0 → 1.3.0 - Mend

cdp-edge 1.2.0 → 1.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (142) hide show

package/extracted-skill/tracking-events-generator/agents/google-agent.md CHANGED Viewed

@@ -4,6 +4,14 @@ Especialista exclusivo em GA4 (Measurement Protocol) + Google Ads (Enhanced Conv
 ---
+## ✅ REGRAS CRÍTICAS
+0. **CONSULTA OBRIGATÓRIA À MEMÓRIA**: Extraia o ID de Medição GA4 e Secret da API (`GA4_MEASUREMENT_ID`, `GA4_API_SECRET`) consultando ativamente o "memory-agent.json". Solicite ao Orquestrador tudo o que faltar. Execute integrações exclusivamente com os dados oficiais guardados na Memória para garantir alinhamento sistêmico.
+1. Cloudflare-Only: Sem dependências externas.
+2. Same-Domain: Worker no domínio do site (anti-adblock).
+---
 ## 🏗️ ARQUITETURA Quantum Tier
 - **Browser**: Use `cdpTrack.js` para captura direta.
 - **Server**: Cloudflare Worker enviando para `google-analytics.com/mp/collect`.
@@ -15,7 +23,7 @@ Especialista exclusivo em GA4 (Measurement Protocol) + Google Ads (Enhanced Conv
 ### PASSO 0 — Ler Versões Atuais
-```javascript
+```typescript
 // Ler versões do arquivo centralizado
 const apiVersions = await readJSON('contracts/api-versions.json');
 const googleVersions = apiVersions.google;
@@ -35,6 +43,124 @@ if (isVersionConflict) {
 ---
+## 🛡️ GOOGLE CONSENT MODE V2 — IMPLEMENTAÇÃO OBRIGATÓRIA
+> **CRÍTICO**: Sem Consent Mode v2, campanhas Google Ads em audiências europeias são rejeitadas.
+> Obrigatório para conformidade com GDPR (UE), LGPD (BR) e CCPA (EUA).
+### PASSO 1 — Inicialização (ANTES do gtag.js)
+Inserir **antes** do snippet do gtag.js no `<head>`:
+```html
+<!-- Google Consent Mode v2 — Inicializar NEGADO por padrão -->
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag() { dataLayer.push(arguments); }
+  // OBRIGATÓRIO: definir consent ANTES de qualquer gtag() de medição
+  gtag('consent', 'default', {
+    'ad_storage':            'denied',   // cookies de anúncio bloqueados até opt-in
+    'analytics_storage':     'denied',   // cookies de analytics bloqueados até opt-in
+    'ad_user_data':          'denied',   // envio de dados de usuário para Google Ads
+    'ad_personalization':    'denied',   // personalização de anúncios
+    'wait_for_update':       500         // aguardar CMP atualizar consentimento (ms)
+  });
+  // url_passthrough: preserva gclid/gbraid/wbraid na URL sem cookie
+  // Permite atribuição de cliques mesmo sem consent de analytics_storage
+  gtag('set', 'url_passthrough', true);
+  // ads_data_redaction: quando ad_storage=denied, reduz dados de clique enviados
+  gtag('set', 'ads_data_redaction', true);
+</script>
+<!-- Carregar gtag.js normalmente após o bloco acima -->
+<script async src="https://www.googletagmanager.com/gtag/js?id=GA4_MEASUREMENT_ID"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag() { dataLayer.push(arguments); }
+  gtag('js', new Date());
+  gtag('config', 'GA4_MEASUREMENT_ID', {
+    'send_page_view': false  // cdpTrack controla page_view manualmente
+  });
+</script>
+```
+### PASSO 2 — Atualizar Consent após Opt-in do usuário
+Integrar com o banner de cookies do site (LGPD/GDPR):
+```javascript
+// Chamar quando usuário ACEITAR todos os cookies
+function onConsentAccepted() {
+  gtag('consent', 'update', {
+    'ad_storage':         'granted',
+    'analytics_storage':  'granted',
+    'ad_user_data':       'granted',
+    'ad_personalization': 'granted'
+  });
+  // Opcional: disparar page_view após consent (se necessário)
+  gtag('event', 'page_view');
+}
+// Chamar quando usuário RECUSAR cookies não essenciais
+function onConsentDeclined() {
+  gtag('consent', 'update', {
+    'ad_storage':         'denied',
+    'analytics_storage':  'denied',
+    'ad_user_data':       'denied',
+    'ad_personalization': 'denied'
+  });
+}
+// Aceitar apenas cookies analíticos (sem ads)
+function onConsentAnalyticsOnly() {
+  gtag('consent', 'update', {
+    'ad_storage':         'denied',
+    'analytics_storage':  'granted',
+    'ad_user_data':       'denied',
+    'ad_personalization': 'denied'
+  });
+}
+```
+### PASSO 3 — Verificação (via Intelligence Agent)
+O Intelligence Agent verifica mensalmente se o Consent Mode está implementado:
+```javascript
+// Checklist mínimo no código gerado (browser tracking):
+// ✅ gtag('consent', 'default', {...}) ANTES do gtag.js
+// ✅ ad_storage: 'denied' no default
+// ✅ analytics_storage: 'denied' no default
+// ✅ ad_user_data: 'denied' no default
+// ✅ ad_personalization: 'denied' no default
+// ✅ url_passthrough: true ativo
+// ✅ gtag('consent', 'update', {...}) no callback do CMP/banner
+```
+### PASSO 4 — Integração com cdpTrack (Preservação de gclid)
+```javascript
+// O cdpTrack.js deve capturar gclid/gbraid/wbraid da URL mesmo sem consent
+// url_passthrough: true garante que os parâmetros são passados como parâmetros de URL,
+// não como cookies — respeitando consent de analytics_storage
+function captureGoogleClickId() {
+  const params = new URLSearchParams(window.location.search);
+  return {
+    gclid:  params.get('gclid')  || null,
+    gbraid: params.get('gbraid') || null,
+    wbraid: params.get('wbraid') || null
+  };
+}
+// Esses IDs são enviados para o Worker e salvos no D1 para Enhanced Conversions offline
+```
+---
 ## 🛠️ O QUE VOCÊ GERA
 ### 1. Browser (Direct SDK)
@@ -87,7 +213,7 @@ Gere payloads para o Worker seguir o protocolo oficial:
 {
   "arquivos_gerados": {
     "browser": "cdpTrack.js (eventos GA4 injetados)",
-    "server": "cloudflare/google-mp.js"
+    "server": "modules/dispatch/ga4.ts"
   },
   "versao_api": {
     "ga4_mp": "latest",

package/extracted-skill/tracking-events-generator/agents/intelligence-agent.md CHANGED Viewed

@@ -51,40 +51,34 @@ O Master Orchestrator DEVE configurar o Intelligence Agent para rodar nos seguin
 ### IMPLEMENTAÇÃO DO SCHEDULING (No Worker)
-Adicionar ao `wrangler.toml` e `worker.js`:
+Adicionar ao `wrangler.toml` e `index.ts`:
 ```toml
 # wrangler.toml — Adicionar triggers de cron
 [[triggers.crons]]
 cron = "0 2 * * 0"           # Domingo 02:00 UTC — Semanal
-schedule = "weekly-intelligence-check"
 [[triggers.crons]]
 cron = "0 3 1 * *"          # 1º do mês 03:00 UTC — Mensal
-schedule = "monthly-privacy-audit"
 ```
-```javascript
-// worker.js — Adicionar handler de cron
+```typescript
+// index.ts — Handler scheduled() (Cloudflare usa scheduled, não fetch para crons)
 export default {
-  async fetch(request, env, ctx) {
-    const url = new URL(request.url);
-    // Handler principal
-    if (url.pathname === '/api/track') {
-      return handleTracking(request, env, ctx);
-    }
-    // Handlers de Intelligence Agent (schedulados)
-    if (url.pathname === '/cron/intelligence-weekly') {
-      return await runIntelligenceWeekly(env, ctx);
-    }
-    if (url.pathname === '/cron/intelligence-monthly') {
-      return await runIntelligenceMonthly(env, ctx);
-    }
-    return new Response('Not Found', { status: 404 });
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    // Handler principal de eventos
+    return handleRequest(request, env, ctx);
+  },
+  async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext) {
+    const cron = event.cron;
+    const isMonthly = cron === '0 3 1 * *';
+    ctx.waitUntil(
+      isMonthly
+        ? runIntelligenceMonthly(env)
+        : runIntelligenceWeekly(env)
+    );
   }
 };
@@ -157,12 +151,12 @@ Timestamp: ${new Date().toISOString()}
   `.trim();
   // Enviar via WhatsApp Agent
-  if (env.WA_PHONE_ID && env.ADMIN_PHONE_NUMBER) {
-    await fetch(`https://graph.facebook.com/v22.0/${env.WA_PHONE_ID}/messages`, {
+  if (env.WHATSAPP_PHONE_NUMBER_ID && env.ADMIN_PHONE_NUMBER) {
+    await fetch(`https://graph.facebook.com/v22.0/${env.WHATSAPP_PHONE_NUMBER_ID}/messages`, {
       method: 'POST',
       headers: {
         'Content-Type': 'application/json',
-        'Authorization': `Bearer ${env.WA_ACCESS_TOKEN}`
+        'Authorization': `Bearer ${env.WHATSAPP_ACCESS_TOKEN}`
       },
       body: JSON.stringify({
         messaging_product: 'whatsapp',
@@ -202,7 +196,7 @@ Quando o Intelligence Agent detectar API desatualizada, emitir alerta estruturad
     ],
     "action_required": {
       "urgency": "IMMEDIATO",
-      "files_to_update": ["worker.js", "meta-agent.md"],
+      "files_to_update": ["index.ts", "meta-agent.md"],
       "migration_guide": "https://developers.facebook.com/docs/graph-changelog",
       "estimated_time": "30 minutos"
     },
@@ -221,7 +215,7 @@ Quando o Intelligence Agent detectar API desatualizada, emitir alerta estruturad
 O Intelligence Agent DEVE executar auditoria completa mensal de LGPD/GDPR/CCPA:
-```javascript
+```typescript
 async function auditPrivacyCompliance(env) {
   const issues = [];
@@ -243,7 +237,7 @@ async function auditPrivacyCompliance(env) {
       platform: 'meta/tiktok/pinterest/reddit',
       issue: 'PII enviada sem SHA-256 hashing',
       severity: 'CRITICAL',
-      fix: 'Usar crypto.subtle.digest para email/phone no worker.js'
+      fix: 'Usar crypto.subtle.digest para email/phone no index.ts'
     });
   }
@@ -271,7 +265,7 @@ async function auditPrivacyCompliance(env) {
 O Intelligence Agent DEVE verificar se alguma API está prestes a ser descontinuada:
-```javascript
+```typescript
 async function checkApiDepreciations(env) {
   const deprecationSchedule = {
     meta: {
@@ -306,11 +300,38 @@ async function checkApiDepreciations(env) {
 ---
+### MONITORAMENTO AUTOMÁTICO DE MATCH QUALITY (CRON SEMANAL)
+O Intelligence Agent monitora a qualidade dos dados enviados ao Meta CAPI a cada execução do cron.
+Os dados são lidos da tabela `match_quality_log` (populada automaticamente pelo Worker a cada dispatch).
+**Thresholds obrigatórios — alertar via CallMeBot se:**
+| Métrica | Threshold mínimo | Ação automática |
+|---|---|---|
+| `email_rate` | 40% dos eventos com email | Alerta ⚠️ — verificar Identity Graph |
+| `fbp_rate` | 30% dos eventos com cookie fbp | Alerta ⚠️ — verificar cdpTrack.js |
+| `composite_score` | 45% (email×0.4 + fbp×0.3 + phone×0.2 + fbc×0.1) | Alerta 🚨 CRÍTICO |
+**O cron semanal executa automaticamente (sem intervenção manual):**
+1. `_trainLtvModel(env)` — re-treina regressão logística com últimos 5000 leads do D1; pesos salvos em `ltv_model_weights` e cache KV invalidado
+2. `_autoDecideAbWinner(env)` — declara winner de A/B LTV se melhoria ≥ 5pp vs controle; alerta WhatsApp automático
+3. `_analyzeMatchQuality(env)` — analisa janela 2h; dispara alertas CallMeBot se abaixo dos thresholds
+4. `syncMetaCustomAudience(env)` — sincroniza leads high_intent com Meta Custom Audience
+**Auto-recuperação integrada ao dispatch:**
+- Antes de cada envio ao Meta CAPI, o Worker tenta enriquecer automaticamente o payload consultando o Identity Graph pelo `userId` (recupera email, fbp, fbc, phone ausentes)
+- Resultado de recuperação é logado em `match_quality_log.was_email_recovered`
+**Pré-requisito de infraestrutura:** `migrate-v7.sql` deve estar aplicada no D1 (tabelas `ltv_model_weights` + `match_quality_log`).
+---
 ### CHECK DE NOVOS PARÂMETROS DE EVENT MATCH QUALITY
 O Intelligence Agent DEVE buscar novos parâmetros que melhoram a nota de atribuição:
-```javascript
+```typescript
 async function checkNewMatchQualityParams(env) {
   const platforms = {
     meta: 'https://developers.facebook.com/docs/marketing-api/conversions-api/parameters',
@@ -363,3 +384,142 @@ INTELLIGENCE_SCHEDULE_MONTHLY = "0 3 1 * *"
 3. **Alerta Pré-ativo**: Antes de uma API ser descontinuada, alertar com 30 dias de antecedência
 4. **False-Positive Safe**: Se houver dúvida sobre versão de API, marcar como "verificação manual necessária" em vez de alerta
 5. **Backoff de Check**: Se o check falhar (API indisponível), tentar novamente em 1 hora (não disparar alerta imediato)
+6. **Anti-Spam**: Não disparar alerta se o mesmo problema já foi reportado nas últimas 24h
+7. **Prioridade Correta**: CRITICAL (agora), HIGH (até 1h), MEDIUM (no relatório)
+8. **Log de Falhas de Alerta**: Se WhatsApp falhar 3× consecutivas, registrar no D1 e tentar via CallMeBot fallback
+---
+## 🗄️ SCHEMA D1 — intelligence_logs
+Adicionar ao `server-edge-tracker/schema.sql`:
+```sql
+-- TABELA DE LOGS DO INTELLIGENCE AGENT
+CREATE TABLE IF NOT EXISTS intelligence_logs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  run_type TEXT NOT NULL,              -- 'weekly' | 'monthly' | 'on-demand'
+  platforms_checked TEXT,              -- JSON array de plataformas verificadas
+  issues_found TEXT,                   -- JSON array de issues encontradas
+  issues_count INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_intel_logs_type    ON intelligence_logs(run_type);
+CREATE INDEX IF NOT EXISTS idx_intel_logs_created ON intelligence_logs(created_at);
+```
+---
+## ✅ CHECKLIST DE IMPLEMENTAÇÃO
+Antes de considerar o scheduling implementado, verificar:
+- [ ] Cron triggers adicionados ao `wrangler.toml` (`0 2 * * 7` e `0 3 1 * *`)
+- [ ] Handlers `scheduled()` adicionados ao `index.ts` (Cloudflare usa `scheduled`, não `fetch`)
+- [ ] Schema D1 atualizado com tabela `intelligence_logs`
+- [ ] Funções de check de versão implementadas com endpoints reais
+- [ ] Funções de auditoria de privacidade implementadas
+- [ ] Sistema de alerta (WhatsApp/CallMeBot) integrado com anti-spam 24h
+- [ ] Logs de execução sendo salvos no D1
+- [ ] Memory Agent atualizado após cada check
+- [ ] Backoff implementado para evitar spam de alertas
+- [ ] Teste manual executado (`GET /api/intelligence/check`)
+---
+## INPUTS RECEBIDOS
+- `wrangler.toml` do Worker (para injetar Cron Triggers)
+- `index.ts` (para injetar handlers de `scheduled` events)
+- `schema.sql` (para adicionar tabela `intelligence_logs`)
+- Secrets: `WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_ACCESS_TOKEN`, `ADMIN_PHONE_NUMBER` (para alertas)
+- `contracts/api-versions.json` (fonte de verdade das versões atuais)
+## RESPONSABILIDADE
+- Configurar Cron Triggers no `wrangler.toml`: semanal (domingo 02:00 UTC) e mensal (1º do mês 03:00 UTC)
+- Implementar handler `scheduled(event, env, ctx)` no Worker
+- Chamar `runIntelligenceWeekly()` quando `event.cron === "0 2 * * 7"`
+- Chamar `runIntelligenceMonthly()` quando `event.cron === "0 3 1 * *"`
+- Adicionar tabela `intelligence_logs` ao schema D1
+- Disparar alertas WhatsApp/CallMeBot ao admin apenas quando houver issues críticos
+- Evitar spam: não repetir alerta do mesmo issue em menos de 24h
+- Registrar resultado de cada execução no D1 (`intelligence_logs`)
+---
+## 🔄 CRON DE NEGÓCIO — Sales Engine (Quando Lead Scoring habilitado)
+Além do cron técnico de versões de API, o Intelligence Agent é responsável pelo **cron de negócio semanal** que alimenta o Sales Engine. Ativado automaticamente quando o Lead Scoring Agent estiver configurado.
+### Cron Semanal de Negócio (`runIntelligenceWeekly`)
+```
+Domingo 02:00 UTC — executa sequencialmente:
+│
+├─ 1. ROAS Feedback Loop (modules/ml/roas.ts)
+│     → cruza leads × Purchase events dos últimos 30 dias por campanha
+│     → agrupa por utm_source × utm_campaign × utm_content (quiz_* vs video_* vs landing_* vs ctwa_*)
+│     → calcula: conversion_rate, revenue_per_lead, ltv_accuracy por origem de funil
+│     → gera bid_recommendation: increase | maintain | decrease | pause
+│     → persiste em roas_reports (inclui utm_content), envia relatório via CallMeBot
+│
+├─ 2. Nurture Queue (modules/nurture.ts)
+│     → processa fila de follow-up pós-quiz por qualification:
+│         comprador  → contato imediato (já disparado no QuizComplete)
+│         interessado → D+1, D+3, D+7 via WhatsApp
+│         curioso    → D+2, D+5 (conteúdo/isca)
+│         perdido    → cohort_label = excluded (remove do remarketing)
+│     → envia mensagens WhatsApp via Meta Cloud API / CallMeBot
+│
+├─ 3. Lookalike Seed (syncMetaLookalikeSeed)
+│     → seed com compradores CONFIRMADOS (Purchase nos últimos 60 dias)
+│     → une com leads qualificados como comprador no quiz
+│     → atualiza cohort_label = buyer_confirmed nos perfis
+│     → persiste histórico em lookalike_seeds
+│
+├─ 4. LTV Model Training (modules/ml/logistic.ts)
+│     → regressão logística com dados reais de conversão acumulados
+│     → atualiza ltv_model_weights no D1
+│
+└─ 5. A/B LTV Auto-winner
+      → declara vencedor quando amostra suficiente (p-value < 0.05)
+```
+### Schema necessário para o Sales Engine
+```bash
+# Aplicado automaticamente pelo DevOps Agent quando Lead Scoring habilitado
+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
+```
+**Tabelas gerenciadas pelo cron de negócio:**
+- `roas_reports` — histórico de ROAS por campanha
+- `nurture_sequences` — fila de follow-up por lead
+- `lookalike_seeds` — histórico de seeds de Lookalike enviados ao Meta
+## SAÍDA
+```json
+{
+  "arquivos_modificados": [
+    "wrangler.toml (cron triggers adicionados)",
+    "index.ts (handler scheduled() adicionado)",
+    "schema.sql (tabela intelligence_logs adicionada)"
+  ],
+  "crons_configurados": {
+    "semanal": "0 2 * * 7 (domingo 02:00 UTC — check de versões)",
+    "mensal":  "0 3 1 * * (dia 1 03:00 UTC — auditoria privacidade)"
+  },
+  "endpoint_manual": "GET /api/intelligence/check",
+  "alertas": {
+    "canal_primario": "WhatsApp Meta Cloud API v22.0",
+    "canal_fallback": "CallMeBot",
+    "anti_spam": "24h cooldown por issue"
+  },
+  "d1_tabela": "intelligence_logs",
+  "secrets_necessarios": ["WHATSAPP_PHONE_NUMBER_ID", "WHATSAPP_ACCESS_TOKEN", "ADMIN_PHONE_NUMBER"]
+}
+```