cdp-edge 1.2.2 → 1.4.0

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

@@ -40,7 +40,7 @@ Sempre que exigido construir Lógicas A/B:
 ```json
 {
   "arquivos_criados": [
-    "cloudflare/ab-routing.js"
+    "modules/ab-routing.ts"
   ],
   "variantes_configuradas": {
     "A": { "url": "/pagina-original", "peso": 50 },

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

@@ -44,7 +44,7 @@ Browser (Cliente)          Worker (Server-Side)           APIs (Meta/Google/TikT
 
 **Uso:** Campanhas de última milha, conversão rápida.
 
-```javascript
+```typescript
 function lastClickAttribution(touchpoints) {
   if (!touchpoints || touchpoints.length === 0) return [];
 
@@ -69,7 +69,7 @@ function lastClickAttribution(touchpoints) {
 
 **Uso:** Brand awareness, campanhas de descoberta.
 
-```javascript
+```typescript
 function firstClickAttribution(touchpoints) {
   if (!touchpoints || touchpoints.length === 0) return [];
 
@@ -94,7 +94,7 @@ function firstClickAttribution(touchpoints) {
 
 **Uso:** Jornadas longas, múltiplos touchpoints importantes.
 
-```javascript
+```typescript
 function linearAttribution(touchpoints) {
   if (!touchpoints || touchpoints.length === 0) return [];
 
@@ -122,7 +122,7 @@ function linearAttribution(touchpoints) {
 
 **Fórmula:** `Credit = 0.9^dias_desde_touchpoint`
 
-```javascript
+```typescript
 function timeDecayAttribution(touchpoints, decayFactor = 0.9) {
   if (!touchpoints || touchpoints.length === 0) return [];
 
@@ -165,7 +165,7 @@ function timeDecayAttribution(touchpoints, decayFactor = 0.9) {
 
 **Uso:** Funis com pesquisa (awareness) + conversão direta.
 
-```javascript
+```typescript
 function uShapeAttribution(touchpoints) {
   if (!touchpoints || touchpoints.length === 0) return [];
 
@@ -207,7 +207,7 @@ function uShapeAttribution(touchpoints) {
 
 **Uso:** Funis muito longos, jornada complexa.
 
-```javascript
+```typescript
 function wShapeAttribution(touchpoints) {
   if (!touchpoints || touchpoints.length === 0) return [];
 
@@ -262,9 +262,9 @@ function wShapeAttribution(touchpoints) {
 
 **Fórmula:** `Credit = BaseScore * CanalWeight * PositionWeight * ConversionRateWeight`
 
-```javascript
+```typescript
 // Modelo Data-Driven simplificado
-async function dataDrivenAttribution(touchpoints, userJourneyHistory) {
+async function dataDrivenAttribution(touchpoints, userJourneyHistory, env) {
   if (!touchpoints || touchpoints.length === 0) return [];
 
   // 1. Calcular pesos baseados em dados históricos
@@ -297,14 +297,14 @@ async function dataDrivenAttribution(touchpoints, userJourneyHistory) {
 }
 
 // Calcular peso de canal baseado em conversão histórica
-async function calculateChannelWeights(touchpoints, history) {
+async function calculateChannelWeights(touchpoints, history, env) {
   const weights = {};
 
   for (const tp of touchpoints) {
     const channel = tp.utm_source;
 
     // Buscar conversões históricas deste canal
-    const historicalConversions = await DB.prepare(`
+    const historicalConversions = await env.DB.prepare(`
       SELECT
         COUNT(*) as total_conversions,
         AVG(value) as avg_value
@@ -325,14 +325,14 @@ async function calculateChannelWeights(touchpoints, history) {
 }
 
 // Calcular peso de posição baseado em conversão histórica
-async function calculatePositionWeights(touchpoints, history) {
+async function calculatePositionWeights(touchpoints, history, env) {
   const weights = {};
 
   for (const tp of touchpoints) {
     const position = tp.position; // 0 = first, 1 = second, etc.
 
     // Buscar conversões históricas nesta posição
-    const historicalConversions = await DB.prepare(`
+    const historicalConversions = await env.DB.prepare(`
       SELECT
         COUNT(*) as total_conversions
       FROM multi_touch_attribution
@@ -456,9 +456,9 @@ CREATE INDEX IF NOT EXISTS idx_channel_model ON channel_performance(attribution_
 
 ### 2.1 Captura de Jornada Completa
 
-```javascript
+```typescript
 // Capturar touchpoint da jornada
-export async function captureTouchpoint(eventData, request) {
+export async function captureTouchpoint(eventData, request, env) {
   const {
     user_id,
     session_id,
@@ -485,7 +485,7 @@ export async function captureTouchpoint(eventData, request) {
   const position = await calculateJourneyPosition(user_id, event_timestamp);
 
   // Persistir touchpoint no D1
-  await DB.prepare(`
+  await env.DB.prepare(`
     INSERT INTO user_journeys
     (user_id, session_id, email, event_id, event_name,
      utm_source, utm_medium, utm_campaign, utm_content, utm_term,
@@ -512,8 +512,8 @@ export async function captureTouchpoint(eventData, request) {
 }
 
 // Calcular posição na jornada
-async function calculateJourneyPosition(userId, eventTimestamp) {
-  const result = await DB.prepare(`
+async function calculateJourneyPosition(userId, eventTimestamp, env) {
+  const result = await env.DB.prepare(`
     SELECT COUNT(*) as position
     FROM user_journeys
     WHERE user_id = ? AND event_timestamp < ?
@@ -523,7 +523,7 @@ async function calculateJourneyPosition(userId, eventTimestamp) {
 }
 
 // Agendar cálculo de atribuição (via Cloudflare Queue)
-async function scheduleAttributionCalculation(email, conversionId, eventName) {
+async function scheduleAttributionCalculation(email, conversionId, eventName, env) {
   await QUEUE.send('cdp-edge-attribution', {
     type: 'CALCULATE_ATTRIBUTION',
     email,
@@ -536,9 +536,9 @@ async function scheduleAttributionCalculation(email, conversionId, eventName) {
 
 ### 2.2 Cálculo de Atribuição Multi-Touch
 
-```javascript
+```typescript
 // Calcular atribuição multi-touch
-export async function calculateMultiTouchAttribution(conversionData) {
+export async function calculateMultiTouchAttribution(conversionData, env) {
   const {
     email,
     conversion_id,
@@ -548,7 +548,7 @@ export async function calculateMultiTouchAttribution(conversionData) {
   } = conversionData;
 
   // 1. Buscar jornada completa do usuário
-  const journey = await DB.prepare(`
+  const journey = await env.DB.prepare(`
     SELECT
       user_id,
       session_id,
@@ -594,7 +594,7 @@ export async function calculateMultiTouchAttribution(conversionData) {
   // 3. Persistir atribuição para cada modelo
   for (const [modelName, attribution] of Object.entries(attributionModels)) {
     for (const touchpoint of attribution) {
-      await DB.prepare(`
+      await env.DB.prepare(`
         INSERT OR REPLACE INTO multi_touch_attribution
         (conversion_id, user_id, email, attribution_model, touchpoint_index,
          utm_source, utm_medium, utm_campaign, event_name, event_timestamp,
@@ -628,7 +628,7 @@ export async function calculateMultiTouchAttribution(conversionData) {
 }
 
 // Atualizar performance de canal
-async function updateChannelPerformance(attributionModels, value, currency) {
+async function updateChannelPerformance(attributionModels, value, currency, env) {
   const today = new Date().toISOString().split('T')[0];
 
   for (const [modelName, attribution] of Object.entries(attributionModels)) {
@@ -660,7 +660,7 @@ async function updateChannelPerformance(attributionModels, value, currency) {
 
     // Atualizar tabela de performance
     for (const perf of Object.values(channelPerformance)) {
-      await DB.prepare(`
+      await env.DB.prepare(`
         INSERT OR REPLACE INTO channel_performance
         (utm_source, utm_medium, utm_campaign, attribution_model,
          total_attribution, total_conversions, total_value, avg_conversion_value, date)
@@ -683,9 +683,9 @@ async function updateChannelPerformance(attributionModels, value, currency) {
 
 ### 2.3 Enviar Atribuição para Plataformas
 
-```javascript
+```typescript
 // Enviar Purchase com atribuição calculada
-export async function sendPurchaseWithAttribution(conversionData, attributionModel = 'U_SHAPE') {
+export async function sendPurchaseWithAttribution(conversionData, env, attributionModel = 'U_SHAPE') {
   const {
     email,
     conversion_id,
@@ -695,7 +695,7 @@ export async function sendPurchaseWithAttribution(conversionData, attributionMod
   } = conversionData;
 
   // 1. Buscar atribuição calculada
-  const attribution = await DB.prepare(`
+  const attribution = await env.DB.prepare(`
     SELECT
       utm_source,
       utm_medium,
@@ -773,7 +773,7 @@ async function sendMetaPurchaseWithAttribution(purchaseData, attribution) {
   const response = await fetch('https://graph.facebook.com/v22.0/events', {
     method: 'POST',
     headers: {
-      'Authorization': `Bearer ${META_ACCESS_TOKEN}`,
+      'Authorization': `Bearer ${env.META_ACCESS_TOKEN}`,
       'Content-Type': 'application/json'
     },
     body: JSON.stringify({ data: [payload] })
@@ -829,7 +829,7 @@ async function sendTikTokPurchaseWithAttribution(purchaseData, attribution) {
   const response = await fetch('https://business-api.tiktok.com/open_api/v1.3/pixel/conversion/', {
     method: 'POST',
     headers: {
-      'Authorization': `Bearer ${TIKTOK_ACCESS_TOKEN}`,
+      'Authorization': `Bearer ${env.TIKTOK_ACCESS_TOKEN}`,
       'Content-Type': 'application/json'
     },
     body: JSON.stringify(payload)
@@ -914,7 +914,7 @@ async function sendGA4PurchaseWithAttribution(purchaseData, channelValues) {
 
 ### 3.1 Configuração via Arquivo
 
-```javascript
+```typescript
 // attribution.config.js
 export const ATTRIBUTION_CONFIG = {
   // Modelo padrão para cálculo de atribuição
@@ -1024,7 +1024,7 @@ export default ATTRIBUTION_CONFIG;
 
 ### 4.1 Endpoint de Atribuição
 
-```javascript
+```typescript
 // Endpoint para consultar atribuição de conversão
 export async function getAttributionForConversion(request, env) {
   const url = new URL(request.url);
@@ -1036,7 +1036,7 @@ export async function getAttributionForConversion(request, env) {
   }
 
   // Buscar atribuição calculada
-  const attribution = await DB.prepare(`
+  const attribution = await env.DB.prepare(`
     SELECT
       utm_source,
       utm_medium,
@@ -1052,7 +1052,7 @@ export async function getAttributionForConversion(request, env) {
   `).bind(conversionId, model).all();
 
   // Buscar dados da conversão
-  const conversion = await DB.prepare(`
+  const conversion = await env.DB.prepare(`
     SELECT
       value,
       currency,
@@ -1096,7 +1096,7 @@ export async function compareAttributionModels(request, env) {
   const comparison = {};
 
   for (const model of ATTRIBUTION_CONFIG.available_models) {
-    const attribution = await DB.prepare(`
+    const attribution = await env.DB.prepare(`
       SELECT
         utm_source,
         credit_percentage
@@ -1136,7 +1136,7 @@ export async function getChannelPerformance(request, env) {
   const days = parseInt(url.searchParams.get('days') || '30');
   const groupBy = url.searchParams.get('group_by') || 'source'; // 'source' ou 'campaign'
 
-  const performance = await DB.prepare(`
+  const performance = await env.DB.prepare(`
     SELECT
       ${groupBy === 'source' ? 'utm_source' : 'utm_campaign'} as group_by,
       SUM(total_attribution) as total_attribution,
@@ -1167,10 +1167,10 @@ export async function getChannelPerformance(request, env) {
 
 ## 🎯 FORMATO DE SAÍDA
 
-### DELIVERABLE 1: `attribution-engine.js`
+### DELIVERABLE 1: `modules/attribution-engine.ts`
 
-```javascript
-// attribution-engine.js - Engine de atribuição multi-touch
+```typescript
+// modules/attribution-engine.ts - Engine de atribuição multi-touch
 export {
   captureTouchpoint,
   calculateMultiTouchAttribution,
@@ -1207,10 +1207,10 @@ CREATE INDEX IF NOT EXISTS idx_channel_source ON channel_performance(utm_source)
 CREATE INDEX IF NOT EXISTS idx_channel_campaign ON channel_performance(utm_campaign);
 ```
 
-### DELIVERABLE 3: `attribution-config.js`
+### DELIVERABLE 3: `modules/attribution-config.ts`
 
-```javascript
-// attribution-config.js - Configuração de modelos de atribuição
+```typescript
+// modules/attribution-config.ts - Configuração de modelos de atribuição
 export const ATTRIBUTION_CONFIG = {
   default_model: 'U_SHAPE',
   available_models: [