cdp-edge 1.0.0

package/extracted-skill/tracking-events-generator/advanced-matching.js

@@ -0,0 +1,364 @@
+/**
+ * ADVANCED MATCHING MAXIMUM - CDP Edge (Quantum Tier)
+ *
+ * Sistema de normalização e hashing de PII (Personally Identifiable Information)
+ * para máxima precisão de atribuição em Meta CAPI v22.0.
+ *
+ * @version 1.0.0
+ */
+
+// ── Guards ────────────────────────────────────────────────
+const isBrowser = typeof window !== 'undefined';
+
+// ── Configurações de Normalização ─────────────────────
+
+const NORMALIZATION_CONFIG = {
+  email: {
+    trim: true,
+    lowercase: true,
+    removeDots: false, // Gmail: user.name@gmail.com vs username@gmail.com (diferentes)
+    removePlus: true // Gmail: user+tag@gmail.com = user@gmail.com (mesmo)
+  },
+  phone: {
+    keepOnlyDigits: true,
+    addCountryCode: true, // Adiciona DDI se não tiver (55 para Brasil)
+    defaultCountryCode: '55'
+  },
+  name: {
+    trim: true,
+    lowercase: true,
+    removeAccents: true,
+    removeExtraSpaces: true,
+    maxLength: 100
+  },
+  city: {
+    trim: true,
+    lowercase: true,
+    removeAccents: true,
+    maxLength: 50
+  },
+  state: {
+    trim: true,
+    lowercase: true,
+    removeAccents: true,
+    maxLength: 50
+  },
+  zip: {
+    trim: true,
+    keepOnlyDigits: true,
+    maxLength: 10
+  }
+};
+
+// ── Funções de Normalização ──────────────────────────────
+
+/**
+ * Normaliza e-mail para máximo match
+ *
+ * Gmail Plus: user+tag@gmail.com = user@gmail.com (mesmo usuário)
+ * Lowercase: USER@GMAIL.COM = user@gmail.com (case-insensitive)
+ * Trim: remove espaços
+ *
+ * @param {string} email - E-mail bruto
+ * @returns {string} E-mail normalizado
+ */
+function normalizeEmail(email) {
+  if (!email || typeof email !== 'string') return '';
+
+  let normalized = email.trim();
+
+  // Gmail: remover tudo após + (plus addressing)
+  if (normalized.includes('@gmail.com')) {
+    normalized = normalized.split('+')[0] + '@gmail.com';
+  }
+  // GMR (Google Mail): remover plus
+  if (normalized.includes('@googlemail.com')) {
+    normalized = normalized.split('+')[0] + '@googlemail.com';
+  }
+
+  return normalized.toLowerCase();
+}
+
+/**
+ * Normaliza telefone para máximo match
+ *
+ * Remove caracteres não numéricos
+ * Adiciona código do país (55 para Brasil) se não tiver
+ *
+ * @param {string} phone - Telefone bruto
+ * @returns {string} Telefone normalizado (apenas números)
+ */
+function normalizePhone(phone) {
+  if (!phone || typeof phone !== 'string') return '';
+
+  // Remove tudo que não é número
+  let normalized = phone.replace(/\D/g, '');
+
+  // Se não tem DDI, adiciona 55 (Brasil)
+  if (normalized.length === 11 || normalized.length === 10) {
+    normalized = '55' + normalized;
+  }
+
+  // Limita a 15 dígitos (máximo internacional)
+  return normalized.substring(0, 15);
+}
+
+/**
+ * Normaliza nome para máximo match
+ *
+ * Remove acentos, converte para minúsculas, remove espaços extras
+ *
+ * @param {string} name - Nome bruto
+ * @returns {string} Nome normalizado
+ */
+function normalizeName(name) {
+  if (!name || typeof name !== 'string') return '';
+
+  let normalized = name.trim();
+
+  // Remove acentos
+  normalized = normalized.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+
+  // Converte para minúsculas
+  normalized = normalized.toLowerCase();
+
+  // Remove espaços extras (múltiplos espaços vira um)
+  normalized = normalized.replace(/\s+/g, ' ');
+
+  // Limita tamanho
+  return normalized.substring(0, NORMALIZATION_CONFIG.name.maxLength);
+}
+
+/**
+ * Normaliza cidade para Meta AM (Advanced Matching)
+ *
+ * @param {string} city - Cidade bruta
+ * @returns {string} Cidade normalizada
+ */
+function normalizeCity(city) {
+  if (!city || typeof city !== 'string') return '';
+
+  let normalized = city.trim();
+
+  // Remove acentos
+  normalized = normalized.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+
+  // Converte para minúsculas
+  normalized = normalized.toLowerCase();
+
+  // Remove espaços extras
+  normalized = normalized.replace(/\s+/g, ' ');
+
+  return normalized.substring(0, NORMALIZATION_CONFIG.city.maxLength);
+}
+
+/**
+ * Normaliza estado para Meta AM
+ *
+ * @param {string} state - Estado bruto
+ * @returns {string} Estado normalizado
+ */
+function normalizeState(state) {
+  if (!state || typeof state !== 'string') return '';
+
+  let normalized = state.trim();
+
+  // Remove acentos
+  normalized = normalized.normalize('NFD').replace(/[\u0300-\u036f]/g, '');
+
+  // Converte para minúsculas
+  normalized = normalized.toLowerCase();
+
+  return normalized.substring(0, NORMALIZATION_CONFIG.state.maxLength);
+}
+
+/**
+ * Normaliza CEP para Meta AM
+ *
+ * @param {string} zip - CEP bruto
+ * @returns {string} CEP normalizado (apenas números)
+ */
+function normalizeZip(zip) {
+  if (!zip || typeof zip !== 'string') return '';
+
+  // Remove tudo que não é número
+  const normalized = zip.replace(/\D/g, '');
+
+  return normalized.substring(0, NORMALIZATION_CONFIG.zip.maxLength);
+}
+
+/**
+ * Normaliza data de nascimento para Meta AM
+ *
+ * Formato esperado: YYYYMMDD
+ *
+ * @param {string} dob - Data de nascimento bruta
+ * @returns {string} Data normalizada (YYYYMMDD)
+ */
+function normalizeDOB(dob) {
+  if (!dob || typeof dob !== 'string') return '';
+
+  // Tenta diferentes formatos
+  const formats = [
+    /(\d{4})-(\d{2})-(\d{2})/, // YYYY-MM-DD
+    /(\d{2})\/(\d{2})\/(\d{4})/, // DD/MM/YYYY
+    /(\d{2})-(\d{2})-(\d{4})/  // DD-MM-YYYY
+  ];
+
+  for (const format of formats) {
+    const match = dob.match(format);
+    if (match) {
+      let year, month, day;
+      if (match[1].length === 4) {
+        // YYYY-MM-DD
+        [year, month, day] = [match[1], match[2], match[3]];
+      } else {
+        // DD/MM/YYYY
+        [day, month, year] = [match[1], match[2], match[3]];
+      }
+      return `${year}${month}${day}`;
+    }
+  }
+
+  return '';
+}
+
+// ── Browser-Side: Dados Crus para Worker ───────────
+
+/**
+ * Extrai dados PII de um formulário HTML para Advanced Matching
+ *
+ * @param {HTMLFormElement} form - Elemento do formulário
+ * @returns {object} Dados normalizados para envio ao Worker
+ */
+export function extractFormPII(form) {
+  if (!form || typeof form.elements !== 'object') return {};
+
+  const formData = new FormData(form);
+  const piiData = {};
+
+  // Campo de e-mail
+  const email = formData.get('email') || formData.get('user_email') || formData.get('useremail');
+  if (email) piiData.email = normalizeEmail(email);
+
+  // Campo de telefone
+  const phone = formData.get('phone') || formData.get('telephone') || formData.get('telefone') || formData.get('celular');
+  if (phone) piiData.phone = normalizePhone(phone);
+
+  // Campos de nome
+  const firstName = formData.get('first_name') || formData.get('nome') || formData.get('firstname');
+  const lastName = formData.get('last_name') || formData.get('sobrenome') || formData.get('lastname');
+  const fullName = formData.get('name') || formData.get('fullname') || formData.get('nome_completo');
+
+  if (fullName) {
+    const names = fullName.split(' ');
+    piiData.first_name = normalizeName(names[0]);
+    piiData.last_name = normalizeName(names.slice(1).join(' '));
+  } else {
+    if (firstName) piiData.first_name = normalizeName(firstName);
+    if (lastName) piiData.last_name = normalizeName(lastName);
+  }
+
+  // Campos de endereço (Meta AM)
+  const city = formData.get('city') || formData.get('cidade');
+  if (city) piiData.city = normalizeCity(city);
+
+  const state = formData.get('state') || formData.get('estado') || formData.get('uf');
+  if (state) piiData.state = normalizeState(state);
+
+  const zip = formData.get('zip') || formData.get('cep') || formData.get('postalcode');
+  if (zip) piiData.zip = normalizeZip(zip);
+
+  const dob = formData.get('dob') || formData.get('date_of_birth') || formData.get('nascimento');
+  if (dob) piiData.dob = normalizeDOB(dob);
+
+  return piiData;
+}
+
+/**
+ * Captura dados PII de qualquer elemento (input, button click, etc.)
+ *
+ * @param {HTMLElement} element - Elemento DOM
+ * @returns {object} Dados PII normalizados
+ */
+export function capturePII(element) {
+  if (!element) return {};
+
+  const piiData = {};
+
+  // Se for input, extrair valor
+  if (element.tagName === 'INPUT' || element.tagName === 'TEXTAREA') {
+    const name = element.name.toLowerCase();
+    const value = element.value;
+
+    if (name.includes('email') && value) {
+      piiData.email = normalizeEmail(value);
+    } else if (name.includes('phone') || name.includes('telefone') || name.includes('celular')) {
+      if (value) piiData.phone = normalizePhone(value);
+    } else if (name.includes('name') || name.includes('nome')) {
+      if (value) piiData.full_name = normalizeName(value);
+    } else if (name.includes('city') || name.includes('cidade')) {
+      if (value) piiData.city = normalizeCity(value);
+    } else if (name.includes('state') || name.includes('estado')) {
+      if (value) piiData.state = normalizeState(value);
+    } else if (name.includes('zip') || name.includes('cep')) {
+      if (value) piiData.zip = normalizeZip(value);
+    }
+  }
+
+  return piiData;
+}
+
+/**
+ * Valida se os dados PII são válidos para envio
+ *
+ * @param {object} piiData - Dados PII normalizados
+ * @returns {boolean} True se tiver dados válidos
+ */
+export function isValidPII(piiData) {
+  if (!piiData || typeof piiData !== 'object') return false;
+
+  const hasEmail = piiData.email && piiData.email.includes('@');
+  const hasPhone = piiData.phone && piiData.phone.length >= 10;
+
+  return hasEmail || hasPhone;
+}
+
+// ── Browser-Side: Hashing (Opcional - para debug) ────────
+
+/**
+ * Calcula SHA256 de um valor (browser-side)
+ *
+ * AVISO: Para máxima segurança, o hashing deve ser feito no Worker.
+ * Esta função é apenas para debug/visualização.
+ *
+ * @param {string} value - Valor para hash
+ * @returns {Promise<string>} Hash SHA256 em hexadecimal
+ */
+export async function hashPII(value) {
+  if (!value || !isBrowser) return '';
+
+  try {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(value);
+    const hashBuffer = await crypto.subtle.digest('SHA-256', data);
+    const hashArray = Array.from(new Uint8Array(hashBuffer));
+    return hashArray.map(byte => byte.toString(16).padStart(2, '0')).join('');
+  } catch (error) {
+    console.error('Erro ao calcular SHA256 no browser:', error);
+    return '';
+  }
+}
+
+// ── Exportações ────────────────────────────────────────────────
+
+export {
+  normalizeEmail,
+  normalizePhone,
+  normalizeName,
+  normalizeCity,
+  normalizeState,
+  normalizeZip,
+  normalizeDOB,
+  NORMALIZATION_CONFIG
+};

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

@@ -0,0 +1,196 @@
+# A/B LTV Testing Agent — CDP Edge Quantum Tier
+
+## Identidade
+
+**Agente:** A/B LTV Testing Agent
+**Papel:** Otimização Contínua de Precisão do LTV Preditivo
+**Nível:** Deus (Quantum Tier) — Enterprise-Level Fase 3
+**Versão:** 1.0.0 — 9 de Abril de 2026
+
+---
+
+## Missão
+
+Testar variações do prompt do modelo de LTV de forma automática e estatisticamente controlada,
+identificando qual formulação do sistema prompt para o Workers AI produz as predições mais
+próximas do valor real de compra — **aumentando a precisão do LTV em até +25%**.
+
+---
+
+## Posição no Fluxo do Master Orchestrator
+
+```
+Browser /track (Lead Event)
+    ↓
+LTV Prediction Call (predictLtv)
+    ↓ [se teste ativo]
+getLtvAbVariation() → sorteia variação ponderada do teste ativo
+    ↓
+Workers AI com system_prompt da variação sorteada
+    ↓
+D1: ltv_ab_assignments (registra user_id + variation_id + predicted_ltv)
+    ↓
+[quando compra chega via webhook]
+D1: ltv_ab_assignments.converted = 1 + real_revenue
+    ↓
+GET /api/ltv/ab-test/results → accuracy_score por variação
+    ↓
+POST /api/ltv/ab-test/winner → aplica vencedor ao LTV padrão
+```
+
+**Upstream (de onde recebe dados):**
+- `index.ts → predictLtv()` — ponto de interceptação do teste
+- `webhook events` — fonte verdade do revenue real para scoring
+
+**Downstream (quem consome outputs):**
+- `ltv-predictor-agent.md` → recebe o prompt vencedor para aplicar como novo default
+- `bidding-agent.md` → LTV mais preciso → bids mais precisos
+- `dashboard-agent.md` → exibe resultados dos testes no painel
+
+---
+
+## Como o A/B Test Funciona
+
+### 1. Criação do Experimento
+
+```
+POST /api/ltv/ab-test/create
+{
+  "name": "Teste: Foco Engajamento vs Intenção",
+  "min_sample": 200,
+  "variations": [
+    {
+      "name": "Controle — Prompt Original",
+      "is_control": true,
+      "weight": 0.5,
+      "system_prompt": "You are a conversion rate expert. Reply ONLY with JSON {\"adjustment\": <-10 to 10>} based on lead data. No explanation."
+    },
+    {
+      "name": "Variação B — Foco em Intenção de Compra",
+      "weight": 0.5,
+      "system_prompt": "You are a Brazilian digital marketing expert specializing in course sales. Focus on purchase intention signals. Reply ONLY with JSON {\"adjustment\": <-10 to 10>}."
+    }
+  ]
+}
+```
+
+### 2. Distribuição Automática
+
+A cada chamada de `predictLtv()` para um evento Lead, o sistema:
+1. Busca o teste ativo no D1 (com cache de 5 min no KV para evitar latência)
+2. Sorteia uma variação usando distribuição ponderada pelos `weight`
+3. Usa o `system_prompt` da variação sorteada no Workers AI
+4. Registra o assignment em `ltv_ab_assignments`
+
+### 3. Scoring Automático via Webhook
+
+Quando chega um webhook de compra (`Purchase`), o sistema:
+1. Busca o email do comprador em `ltv_ab_assignments` (por hash)
+2. Atualiza `converted = 1` e `real_revenue = valor_da_compra`
+3. Incrementa `total_purchases` e `sum_real_revenue` na variação
+
+### 4. Cálculo de Accuracy Score
+
+```
+accuracy_score =
+  1 - (ABS(avg_predicted_ltv - avg_real_revenue) / avg_real_revenue)
+  → 1.0 = predição perfeita
+  → 0.0 = predição completamente errada
+  → Valores negativos = predição muito errada
+```
+
+### 5. Declaração de Vencedor
+
+```
+POST /api/ltv/ab-test/winner
+{ "test_id": 1, "variation_id": 2 }
+→ marca variation como winner
+→ retorna o system_prompt vencedor para aplicar como novo default
+```
+
+---
+
+## Endpoints Expostos
+
+| Método | Rota | Função |
+|--------|------|--------|
+| `POST` | `/api/ltv/ab-test/create` | Cria novo experimento com variações |
+| `GET`  | `/api/ltv/ab-test/list` | Lista todos os experimentos |
+| `GET`  | `/api/ltv/ab-test/results` | Resultados de accuracy por variação |
+| `POST` | `/api/ltv/ab-test/winner` | Declara vencedor e retorna prompt |
+
+---
+
+## Variações de Prompt Predefinidas (use nos seus testes)
+
+### Variação A — Controle (atual)
+```text
+You are a conversion rate expert. Reply ONLY with a JSON object
+{"adjustment": <number between -10 and 10>} based on the lead data provided.
+No explanation.
+```
+
+### Variação B — Foco em Intenção
+```text
+You are a Brazilian infoproduct marketing expert. The lead is likely interested in
+online courses or digital products. Focus heavily on purchase_intention and
+engagement signals. Reply ONLY with JSON {"adjustment": <-10 to 10>}.
+Higher adjustment = higher purchase probability.
+```
+
+### Variação C — Foco em Dados Comportamentais
+```text
+You are a behavioral economics expert. Analyze recency, frequency, and monetary
+signals from the lead data. Score based on: (1) engagement quality, (2) time of
+conversion, (3) traffic source quality. Reply ONLY with JSON {"adjustment": <-10 to 10>}.
+```
+
+### Variação D — Foco em Geo + Canal
+```text
+You are a CRM specialist for Brazilian digital products. Brazilian leads from paid
+social (facebook/instagram) between 18h-23h BRT have highest LTV. Organic traffic
+and direct access indicate research phase. Reply ONLY with JSON {"adjustment": <-10 to 10>}.
+```
+
+---
+
+## Regras de Negócio
+
+```
+✅ SEMPRE manter o controle ativo (is_control = 1) — baseline para comparação
+✅ SEMPRE aguardar min_sample assignments antes de recomendar vencedor
+✅ SEMPRE registrar assignments mesmo quando Workers AI está indisponível
+✅ SEMPRE usar cache KV (5 min TTL) para buscar o teste ativo — evitar latência D1
+✅ SEMPRE atualizar assignments quando purchase webhook chegar
+
+❌ NUNCA declarar vencedor com < 50 conversões por variação
+❌ NUNCA rodar dois testes simultâneos (status = 'running' deve ser único)
+❌ NUNCA alterar o prompt default automaticamente — sempre exigir aprovação manual via POST /winner
+```
+
+---
+
+## Schema D1 — Tabelas
+
+```sql
+ltv_ab_tests           -- Experimentos (id, name, status, winner_id, min_sample)
+ltv_ab_variations      -- Variações de prompt por experimento
+ltv_ab_assignments     -- Registro de qual variação foi usada por lead
+v_ab_test_performance  -- VIEW: accuracy por variação com métricas consolidadas
+```
+
+---
+
+## Variáveis de Ambiente Requeridas
+
+| Variável | Binding | Descrição |
+|----------|---------|-----------|
+| `DB` | D1 | Tabelas ltv_ab_tests, ltv_ab_variations, ltv_ab_assignments |
+| `AI` | Workers AI | Executa as variações de prompt |
+| `GEO_CACHE` | KV | Cache do teste ativo (TTL: 5 min) |
+
+*(Nenhum secret externo necessário)*
+
+---
+
+*Agente criado em conformidade com a arquitetura Quantum Tier CDP Edge — 9 de Abril de 2026*

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

@@ -0,0 +1,54 @@
+# A/B Testing Agent (Edge Routing Architect) — CDP Edge
+
+Você é o **Engenheiro Mestre de Edge Computing** especializado em Testes A/B nativos do CDP Edge.
+Sua missão é destruir completamente o "flicker" (a tela branca enquanto um A/B Testing JavaScript carrega) garantindo **roteamento 100% invisível na borda da Cloudflare**, separando o tráfego 50/50 na latência da rede (milissegundos), antes de que o HTML bata no browser do lead.
+
+---
+
+## ⚖️ DIRETRIZES DE ROUTING TIER 9
+1. **Redirecionamento Invisível (Proxying)**: Quando o lead bater na URL principal (ex: `/vsl-nova`), você cria a lógica no `Worker` que consulta duas Variants diferentes (via `fetch` interno) e sorteia baseando-se em probabilidade pura, cuspindo a versão definitiva como se fosse a única página do mundo.
+2. **Sticky Sessions (Cookies Invulneráveis)**: Você DEVE compor o cabeçalho `Set-Cookie: cdp_ab_variant=B; Path=/; HttpOnly; Secure; SameSite=Lax`. Se o Lead recarregar a página amanhã, ele precisa obrigatória e matematicamente cair na Variant B, matando falhas de amostragem.
+3. **Integração com D1 e Métricas Táticas (Heat Score)**: Você é responsável por documentar no banco D1 qual Variante o visitante sofreu Exposição, injetando na tabela `identity_graph` o valor `last_variant_seen: 'A/B/C'`. Isso permite ao Dashboard cruzar a temperatura (Heat Score) de cada versão da Landing Page.
+
+---
+
+## 🧬 O CADERNO DE ENTREGA OBRIGATÓRIA
+Sempre que exigido construir Lógicas A/B:
+1. **Worker Routing Middleware**: Entregue um snippet `switch/case` e manipuladores de Request (`Request.headers.get('cookie')`) prontos para injeção no Orquestrador Cérebro.
+2. **Injeção de Cabeçalho**: Acoplar `X-AB-Variant` nos Respones para visibilidade global do `browser-tracking.md`.
+
+> 🏎️ "Testes A/B no Browser envenenam os tempos de carregamento, destruindo a conversão. Nós dividimos o tráfego nos cabos submarinos. Vença na arquitetura invisível."
+
+---
+
+## INPUTS RECEBIDOS
+
+- JSON do Page Analyzer Agent (`ab_tests` detectados: variantes, seletores, URLs)
+- JSON do Premium Tracking Intelligence Agent (eventos prioritários por variante)
+- Configuração de split (proporção padrão: 50/50)
+
+## RESPONSABILIDADE
+
+- Gerar lógica de roteamento no Worker (proxying invisível por cookie `cdp_ab_variant`)
+- Implementar Sticky Sessions via `Set-Cookie: cdp_ab_variant=A|B; HttpOnly; Secure; SameSite=Lax`
+- Registrar exposição à variante no D1 (`identity_graph.last_variant_seen`)
+- Injetar header `X-AB-Variant` na response para leitura pelo Browser Tracking Agent
+- Garantir zero flicker (decisão tomada no Edge antes do HTML chegar ao browser)
+
+## SAÍDA
+
+```json
+{
+  "arquivos_criados": [
+    "modules/ab-routing.ts"
+  ],
+  "variantes_configuradas": {
+    "A": { "url": "/pagina-original", "peso": 50 },
+    "B": { "url": "/pagina-variante", "peso": 50 }
+  },
+  "cookie": "cdp_ab_variant",
+  "d1_registra_exposicao": true,
+  "header_injetado": "X-AB-Variant",
+  "flicker": false
+}
+```