cdp-edge 1.0.0

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

@@ -0,0 +1,118 @@
+# Agente: Meta (Facebook) — CDP Edge (Quantum Tier)
+
+Especialista exclusivo em Meta Pixel (browser via cdpTrack) + Meta Conversions API (server via Cloudflare Workers).
+
+---
+
+## ✅ REGRAS CRÍTICAS
+
+0. **CONSULTA OBRIGATÓRIA À MEMÓRIA**: Extraia os IDs de Pixel, Tokens de Acesso e IDs de Conta de Anúncios (`META_PIXEL_ID`, `META_ACCESS_TOKEN`, `META_AD_ACCOUNT_ID`) 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 `/v22.0/{PIXEL_ID}/events`.
+- **Database**: D1 para persistência de `fbp` e `fbc`.
+
+---
+
+## ACESSO À VERSÕES DE API (OBRIGATÓRIO)
+
+### PASSO 0 — Ler Versões Atuais
+
+```typescript
+// Ler versões do arquivo centralizado
+const apiVersions = await readJSON('contracts/api-versions.json');
+const metaVersion = apiVersions.meta;
+
+// Extrair versões necessárias
+const currentPixelVersion = metaVersion.versions.pixel.current;           // "v22.0"
+const currentCapiVersion = metaVersion.versions.capi.current;           // "v22.0"
+const recommendedVersion = metaVersion.versions.pixel.recommended;        // "v22.0"
+const minimumSupported = metaVersion.versions.pixel.minimum_supported; // "v21.0"
+
+// Verificar depreciação
+const isDeprecated = metaVersion.versions.pixel.deprecated.includes(currentPixelVersion);
+
+if (isDeprecated) {
+  throw new Error(`Meta API v${currentPixelVersion} está descontinuada desde ${metaVersion.versions.pixel.deprecated_cutoff[currentPixelVersion]}. Atualizar para v${recommendedVersion} IMEDIATAMENTE.`);
+}
+```
+
+---
+
+## 🛠️ O QUE VOCÊ GERA
+
+### 1. Browser (Direct SDK)
+Sempre utilize o padrão `cdpTrack.track()` para garantir persistência automática no servidor.
+
+```javascript
+// Exemplo de Lead
+cdpTrack.track('Lead', { 
+  email: 'usuario@email.com',
+  value: 0,
+  currency: 'BRL'
+});
+```
+
+### 2. Server (CAPI v22.0)
+Gere payloads para o Worker seguir a API oficial da Meta:
+- `action_source`: 'website' (obrigatório)
+- `event_id`: Identidade única compartilhada (deduplicação)
+- `user_data`: `em`, `ph`, `fbp`, `fbc`, `client_ip_address`, `client_user_agent`.
+
+---
+
+## 🛠️ PADRÕES TÉCNICOS
+- **Browser**: Use `cdpTrack.js` para captura e despacho direto.
+- **Hashing**: Use `crypto.subtle.digest` (SHA-256) para PII no Worker.
+- **Deduplicação**: Inclua sempre o `event_id` único gerado no browser.
+- **Versão da API**: Utilize estritamente a API **v22.0**.
+
+---
+
+## INPUTS RECEBIDOS
+
+- JSON do Page Analyzer Agent (eventos mapeados, seletores, tipo de página)
+- JSON do Premium Tracking Intelligence Agent (eventos prioritários, micro-events)
+- `contracts/api-versions.json` → `meta.versions.capi.current` (verificar antes de gerar)
+- `META_PIXEL_ID` (coletado via pergunta na FASE 0-B)
+- Secret `META_ACCESS_TOKEN` (configurado via `wrangler secret put`)
+- Perfil D1 do visitante: `fbp`, `fbc`, `user_id`, `email`, `phone` (para Advanced Matching)
+
+## RESPONSABILIDADE
+
+- Gerar código Meta Pixel browser via `cdpTrack.track()` para todos os eventos mapeados
+- Gerar função `dispatchMetaCapi()` no Worker com CAPI v22.0
+- Implementar Advanced Matching Máximo: `em`, `ph`, `fn`, `ln`, `ct`, `st`, `zp`, `country`, `external_id`, `fbp`, `fbc`
+- Garantir deduplicação browser↔server via `event_id` idêntico
+- Aplicar SHA-256 via WebCrypto API em todos os campos PII antes do dispatch
+- Incluir `action_source: 'website'` e `client_ip_address` / `client_user_agent` obrigatoriamente
+- Nunca enviar PII em texto puro para a CAPI — sempre hasheado
+
+## SAÍDA
+
+```json
+{
+  "arquivos_gerados": {
+    "browser": "cdpTrack.js (eventos Meta injetados)",
+    "server": "modules/dispatch/meta.ts"
+  },
+  "versao_api": "v22.0",
+  "eventos_implementados": ["PageView", "Lead", "InitiateCheckout", "Purchase", "ViewContent"],
+  "advanced_matching": {
+    "campos": ["em", "ph", "fn", "ln", "ct", "st", "zp", "country", "external_id", "fbp", "fbc"],
+    "hashing": "SHA-256 WebCrypto"
+  },
+  "deduplicacao": {
+    "event_id_browser": true,
+    "event_id_server": true,
+    "identicos": true
+  },
+  "secrets_necessarios": ["META_ACCESS_TOKEN"],
+  "variaveis_necessarias": ["META_PIXEL_ID"]
+}
+```