cdp-edge 1.0.0

package/contracts/api-versions.json

@@ -0,0 +1,372 @@
+{
+  "metadata": {
+    "version": "1.1.0",
+    "created_at": "2026-03-28T14:00:00.000Z",
+    "updated_at": "2026-04-14T00:00:00.000Z",
+    "maintained_by": "Intelligence Agent (CDP Edge Quantum Tier)",
+    "purpose": "Fonte única da verdade para versões de API em todo o ecossistema CDP Edge"
+  },
+
+  "meta": {
+    "platform": "meta",
+    "name": "Meta (Facebook)",
+    "documentation": "https://developers.facebook.com/docs/marketing-api/conversions-api/",
+    "changelog": "https://developers.facebook.com/docs/graph-changelog/",
+
+    "versions": {
+      "pixel": {
+        "current": "v22.0",
+        "minimum_supported": "v21.0",
+        "recommended": "v22.0",
+        "deprecated": ["v20.0", "v21.0"],
+        "deprecated_cutoff": {
+          "v20.0": "2024-01-01T00:00:00.000Z",
+          "v21.0": "2024-06-01T00:00:00.000Z"
+        }
+      },
+
+      "capi": {
+        "current": "v22.0",
+        "minimum_supported": "v21.0",
+        "recommended": "v22.0",
+        "endpoint_pattern": "https://graph.facebook.com/{VERSION}/{PIXEL_ID}/events",
+        "authentication": "Bearer token (META_ACCESS_TOKEN)",
+        "rate_limits": {
+          "requests_per_hour": 200,
+          "events_per_batch": 10,
+          "batches_per_hour": 20
+        }
+      },
+
+      "messenger": {
+        "current": "v22.0",
+        "minimum_supported": "v21.0",
+        "recommended": "v22.0",
+        "whatsapp_cloud_api": "v22.0"
+      }
+    }
+  },
+
+  "google": {
+    "platform": "google",
+    "name": "Google (GA4 + Google Ads)",
+    "versions": {
+      "ga4": {
+        "current": "latest",
+        "minimum_supported": "v2",
+        "recommended": "latest",
+        "endpoint_pattern": "https://www.google-analytics.com/mp/collect?measurement_id={MEASUREMENT_ID}&api_secret={SECRET}",
+        "authentication": "API Secret (GA4_API_SECRET)"
+      },
+      "google_ads": {
+        "current": "latest",
+        "minimum_supported": "v2",
+        "recommended": "latest",
+        "uet_tag": "latest"
+      },
+      "consent_mode": {
+        "current": "v2",
+        "minimum_supported": "v2",
+        "required_parameters": [
+          "ad_storage",
+          "analytics_storage",
+          "ad_user_data",
+          "ad_personalization"
+        ],
+        "default_values": {
+          "ad_storage": "denied",
+          "analytics_storage": "denied",
+          "ad_user_data": "denied",
+          "ad_personalization": "denied"
+        },
+        "flags": {
+          "url_passthrough": true,
+          "wait_for_update": 500
+        }
+      }
+    }
+  },
+
+  "tiktok": {
+    "platform": "tiktok",
+    "name": "TikTok (Pixel + Events API)",
+    "documentation": "https://ads.tiktok.com/marketing_api/docs?id=1740465605569281",
+    "versions": {
+      "pixel": {
+        "current": "v1.3",
+        "minimum_supported": "v1.2",
+        "recommended": "v1.3",
+        "deprecated": [
+          "v1.2"
+        ],
+        "deprecated_cutoff": {
+          "v1.2": "2024-03-01T00:00:00.000Z"
+        },
+        "endpoint_pattern": "https://analytics.tiktok.com/v1/pixel"
+      },
+      "events_api": {
+        "current": "v1.3",
+        "minimum_supported": "v1.2",
+        "recommended": "v1.3",
+        "endpoint_pattern": "https://business-api.tiktok.com/open_api/{VERSION}/event/track/",
+        "authentication": "Bearer token (TIKTOK_ACCESS_TOKEN)",
+        "rate_limits": {
+          "requests_per_minute": 10,
+          "events_per_batch": 5,
+          "batches_per_minute": 2
+        }
+      }
+    }
+  },
+
+  "pinterest": {
+    "platform": "pinterest",
+    "name": "Pinterest (Tag + Conversions API)",
+    "documentation": "https://developers.pinterest.com/docs/conversions/",
+    "versions": {
+      "tag": {
+        "current": "3.0",
+        "minimum_supported": "2.0",
+        "recommended": "3.0",
+        "endpoint_pattern": "https://s.pinimg.com/ct/core.js",
+        "enhanced_match": {
+          "supports_email_hashing": true,
+          "supports_phone_hashing": true,
+          "auto_hash_by_pixel": true
+        }
+      },
+      "conversions_api": {
+        "current": "v5",
+        "minimum_supported": "v4.0",
+        "recommended": "v5",
+        "deprecated": [
+          "v4"
+        ],
+        "deprecated_cutoff": {
+          "v4": "2024-01-01T00:00:00.000Z"
+        },
+        "endpoint_pattern": "https://api.pinterest.com/v5/ad_accounts/{AD_ACCOUNT_ID}/events",
+        "authentication": "Bearer token (PINTEREST_ACCESS_TOKEN)",
+        "rate_limits": {
+          "requests_per_hour": 100,
+          "events_per_batch": 10,
+          "batches_per_hour": 10
+        }
+      }
+    }
+  },
+
+  "reddit": {
+    "platform": "reddit",
+    "name": "Reddit (Pixel + Conversions API)",
+    "documentation": "https://ads.reddit.com/help/article/reddit-pixel",
+    "versions": {
+      "pixel": {
+        "current": "v2",
+        "minimum_supported": "v1.0",
+        "recommended": "v2",
+        "endpoint_pattern": "https://www.redditstatic.com/ads/v2.js",
+        "advanced_matching": {
+          "supports_email_hashing": true,
+          "auto_hash_by_pixel": true,
+          "supports_external_id": true
+        }
+      },
+      "conversions_api": {
+        "current": "v2.0",
+        "minimum_supported": "v1.0",
+        "recommended": "v2.0",
+        "deprecated": [
+          "v1.0"
+        ],
+        "deprecated_cutoff": {
+          "v1.0": "2024-06-01T00:00:00.000Z"
+        },
+        "endpoint_pattern": "https://ads-api.reddit.com/api/{VERSION}/conversions/events/{AD_ACCOUNT_ID}",
+        "authentication": "Bearer token (REDDIT_ACCESS_TOKEN)",
+        "rate_limits": {
+          "requests_per_minute": 5,
+          "events_per_batch": 10,
+          "batches_per_minute": 1
+        }
+      }
+    }
+  },
+
+  "linkedin": {
+    "platform": "linkedin",
+    "name": "LinkedIn (Insight Tag + Conversions API)",
+    "documentation": "https://learn.microsoft.com/en-us/linkedin/marketing/conversions-api/",
+    "versions": {
+      "insight_tag": {
+        "current": "v2",
+        "minimum_supported": "v1",
+        "recommended": "v2",
+        "endpoint_pattern": "https://snap.licdn.com/li.lms-analytics/insight.beta.min.js",
+        "consent_mode_required": true,
+        "data_attributes": [
+          "conversion_id",
+          "text",
+          "currency",
+          "value"
+        ]
+      },
+      "conversions_api": {
+        "current": "202401",
+        "minimum_supported": "202401",
+        "recommended": "202401",
+        "endpoint_pattern": "https://api.linkedin.com/rest/conversionEvents",
+        "required_headers": {
+          "LinkedIn-Version": "202401",
+          "X-Restli-Protocol-Version": "2.0.0"
+        },
+        "authentication": "Bearer token (LINKEDIN_ACCESS_TOKEN)",
+        "rate_limits": {
+          "requests_per_second": 10,
+          "events_per_batch": 100
+        }
+      }
+    }
+  },
+
+  "bing": {
+    "platform": "bing",
+    "name": "Microsoft Advertising (UET Tag + Clarity)",
+    "documentation": "https://learn.microsoft.com/en-us/advertising/guides/event-tracking",
+    "versions": {
+      "uet_tag": {
+        "current": "latest",
+        "minimum_supported": "v1",
+        "recommended": "latest",
+        "endpoint_pattern": "https://bat.bing.com/bat.js",
+        "enhanced_conversions": {
+          "supports_email_hashing": true,
+          "supports_phone_hashing": true,
+          "requires_sha256": true
+        }
+      },
+      "clarity": {
+        "current": "latest",
+        "minimum_supported": "v1",
+        "recommended": "latest",
+        "endpoint_pattern": "https://clarity.ms/tag/s/{CLARITY_PROJECT_ID}/clarity.js"
+      }
+    }
+  },
+
+  "youtube": {
+    "platform": "youtube",
+    "name": "YouTube Ads (Video Campaigns)",
+    "documentation": "https://developers.google.com/youtube/v3/guides/auth/server-side-web-apps",
+    "versions": {
+      "video_campaigns": {
+        "current": "latest",
+        "minimum_supported": "v1",
+        "recommended": "latest",
+        "campaign_types": ["TrueView In-Stream", "Bumper Ads", "Non-skip In-Stream", "Video Discovery"],
+        "click_ids": ["gclid", "wbraid", "gbraid"],
+        "conversion_window_vtc_days": 7
+      },
+      "iframe_api": {
+        "current": "latest",
+        "endpoint_pattern": "https://www.youtube.com/embed/{VIDEO_ID}?enablejsapi=1",
+        "events": ["video_start", "video_progress", "video_complete"],
+        "milestones_percent": [25, 50, 75, 100]
+      },
+      "customer_match": {
+        "current": "latest",
+        "hash_required": true,
+        "hash_algorithm": "SHA-256",
+        "accepted_fields": ["email", "phone", "first_name", "last_name"]
+      }
+    }
+  },
+
+  "spotify": {
+    "platform": "spotify",
+    "name": "Spotify Ads (Pixel + Conversions API)",
+    "documentation": "https://advertising-api.spotify.com/docs/",
+    "versions": {
+      "pixel": {
+        "current": "v1",
+        "minimum_supported": "v1",
+        "recommended": "v1",
+        "endpoint_pattern": "Spotify Pixel SDK (custom)"
+      },
+      "conversions_api": {
+        "current": "v1",
+        "minimum_supported": "v1",
+        "recommended": "v1",
+        "endpoint_pattern": "https://advertising-api.spotify.com/conversion/v1/accounts/{ACCOUNT_ID}/events",
+        "authentication": "Bearer token (SPOTIFY_ACCESS_TOKEN)",
+        "rate_limits": {
+          "requests_per_minute": 30,
+          "events_per_batch": 10
+        }
+      }
+    }
+  },
+
+  "validation_rules": {
+    "deprecation_policy": "APIs marcadas como deprecated devem ser atualizadas IMEDIATAMENTE",
+    "minimum_version_policy": "Versões abaixo do minimum_supported NÃO são suportadas",
+    "recommended_version_policy": "Usar sempre a recommended version para máxima compatibilidade",
+    "endpoint_validation": "Endpoints devem seguir exatamente o padrão especificado",
+    "authentication_validation": "Tokens devem ser obtidos via wrangler secret (NUNCA hardcoded)",
+    "rate_limit_policy": "Respeitar rate_limits para evitar bloqueios"
+  },
+
+  "migration_guidelines": {
+    "meta_v20_to_v22": {
+      "breaking_changes": [],
+      "new_parameters": [],
+      "deprecated_parameters": [],
+      "migration_steps": [
+        "Atualizar endpoint de /v20.0/ para /v22.0/",
+        "Verificar novos parâmetros obrigatórios",
+        "Testar em ambiente de sandbox"
+      ]
+    },
+
+    "tiktok_v1.2_to_v1.3": {
+      "breaking_changes": [],
+      "new_parameters": [],
+      "deprecated_parameters": [],
+      "migration_steps": [
+        "Atualizar endpoint de /v1.2/ para /v1.3/",
+        "Verificar compatibilidade de event names",
+        "Atualizar rate limits"
+      ]
+    },
+
+    "pinterest_v4_to_v5": {
+      "breaking_changes": ["ad_account_id agora obrigatório na URL"],
+      "new_parameters": ["external_data", "action_source"],
+      "deprecated_parameters": [],
+      "migration_steps": [
+        "Adicionar ad_account_id ao endpoint",
+        "Atualizar estrutura de payload",
+        "Verificar novos campos obrigatórios"
+      ]
+    },
+
+    "reddit_v1.0_to_v2.0": {
+      "breaking_changes": ["URL mudou de /api/v1.0/ para /api/v2.0/"],
+      "new_parameters": ["conversion_type", "ip_address", "user_agent"],
+      "deprecated_parameters": [],
+      "migration_steps": [
+        "Atualizar todos os endpoints para v2.0",
+        "Adicionar novos campos de user data",
+        "Verificar compatibilidade de event names"
+      ]
+    }
+  },
+
+  "last_updated_by": {
+    "agent": "Intelligence Agent — CDP Edge v2.3.8",
+    "session_id": "CDP_2026-04-14_release",
+    "timestamp": "2026-04-14T00:00:00.000Z"
+  },
+
+  "next_review_date": "2026-05-14T00:00:00.000Z"
+}

package/contracts/types.ts

@@ -0,0 +1,81 @@
+// CDP Edge Premium - API Contracts & Typings
+
+export interface QuantumEventPayload {
+  eventName: string;
+  eventId: string;
+  userId: string;
+  email?: string | null;
+  phone?: string | null;
+  firstName?: string | null;
+  lastName?: string | null;
+  city?: string | null;
+  state?: string | null;
+  zip?: string | null;
+  country?: string | null;
+  
+  // Identifiers
+  fbp?: string | null;
+  fbc?: string | null;
+  ttp?: string | null;
+  gaClientId?: string | null;
+  
+  // Parameters
+  value?: number | null;
+  currency?: string;
+  contentIds?: string[];
+  contentName?: string;
+  contentType?: string;
+  pageUrl?: string;
+  orderId?: string;
+
+  // Quantum Tracking Details
+  intentScoreNum?: number | null;
+  metaSignal?: number;
+  distanceBucket?: string;
+  funnelLevel?: string;
+  botScore?: number;
+  
+  // Any extra params
+  [key: string]: any;
+}
+
+export interface AgencyContext {
+  // Required Env mappings for specialists
+  META_ACCESS_TOKEN?: string;
+  META_PIXEL_ID?: string;
+  GA4_API_SECRET?: string;
+  GA4_MEASUREMENT_ID?: string;
+  TIKTOK_ACCESS_TOKEN?: string;
+  TIKTOK_PIXEL_ID?: string;
+  PINTEREST_ACCESS_TOKEN?: string;
+  PINTEREST_AD_ACCOUNT_ID?: string;
+  REDDIT_ACCESS_TOKEN?: string;
+  REDDIT_AD_ACCOUNT_ID?: string;
+  LINKEDIN_ACCESS_TOKEN?: string;
+  LINKEDIN_AD_ACCOUNT_ID?: string;
+  SPOTIFY_ACCESS_TOKEN?: string;
+  SPOTIFY_AD_ACCOUNT_ID?: string;
+  
+  // Databases and Stores
+  DB?: any; // D1 Database
+  GEO_CACHE?: any; // KV Namespace
+  RATE_LIMITER?: any;
+  SITE_DOMAIN?: string;
+  
+  [key: string]: any;
+}
+
+export interface ApiVersionsConfig {
+  metadata: {
+    version: string;
+  };
+  meta: any;
+  google: any;
+  tiktok: any;
+  pinterest: any;
+  reddit: any;
+  linkedin: any;
+  bing: any;
+  youtube: any;
+  spotify: any;
+}

package/dist/commands/analyze.js

@@ -0,0 +1,52 @@
+/**
+ * Analyze Command - Análise de páginas
+ */
+
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import ora from 'ora';
+import { promises as fs } from 'fs';
+
+export async function runAnalyze(dir) {
+  console.log(chalk.cyan.bold('\n CDP Edge - Page Analyzer\n'));
+
+  const spinner = ora('Analisando arquivos...').start();
+
+  try {
+    // Busca arquivos HTML/JS no diretório
+    const files = await findProjectFiles(dir);
+
+    spinner.succeed(`Encontrados ${files.length} arquivos`);
+
+    // Análise dos eventos detectados
+    const events = await analyzeEvents(files);
+
+    console.log('\n' + chalk.yellow('Eventos detectados:'));
+    console.log(formatEventAnalysis(events));
+
+  } catch (error) {
+    spinner.fail('Erro na análise');
+    console.error(error);
+  }
+}
+
+async function findProjectFiles(dir) {
+  // Em produção, faria glob real dos arquivos
+  return ['index.html', 'checkout.html', 'thankyou.html'];
+}
+
+async function analyzeEvents(files) {
+  // Em produção, analisaria cada arquivo com o Page Analyzer Agent
+  return {
+    leads: 2,
+    purchases: 1,
+    views: 3,
+    custom: 0
+  };
+}
+
+function formatEventAnalysis(events) {
+  return Object.entries(events)
+    .map(([type, count]) => `  ${chalk.cyan(type)}: ${count}`)
+    .join('\n');
+}

package/dist/commands/infra.js

@@ -0,0 +1,54 @@
+/**
+ * Infra Command - Guia de setup Cloudflare
+ */
+
+import chalk from 'chalk';
+
+export async function runInfra() {
+  console.log(chalk.cyan.bold('\n CDP Edge - Guia de Infraestrutura Cloudflare\n'));
+
+  const guide = `
+
+${chalk.yellow.bold('🚀 Setup do Zero ao Deploy')}
+
+${chalk.cyan.bold('PASSO 1: Criar Conta Cloudflare')}
+   1. Acesse https://dash.cloudflare.com/sign-up
+   2. Crie uma conta gratuita
+   3. Adicione seu domínio (opcional para testes)
+
+${chalk.cyan.bold('PASSO 2: Instalar Wrangler CLI')}
+   npm install -g wrangler
+   wrangler login
+
+${chalk.cyan.bold('PASSO 3: Criar D1 Database')}
+   wrangler d1 create cdp-edge-db
+   # Copie o database_id gerado
+
+${chalk.cyan.bold('PASSO 4: Criar Worker')}
+   wrangler init cdp-edge-worker
+   # Responda às perguntas do wizard
+
+${chalk.cyan.bold('PASSO 5: Configurar Secrets')}
+   wrangler secret put META_ACCESS_TOKEN
+   wrangler secret put TIKTOK_ACCESS_TOKEN
+   wrangler secret put GA4_MEASUREMENT_ID
+
+${chalk.cyan.bold('PASSO 6: Aplicar Schema D1')}
+   wrangler d1 execute cdp-edge-db --file=schema.sql
+
+${chalk.cyan.bold('PASSO 7: Deploy')}
+   wrangler deploy
+
+${chalk.cyan.bold('PASSO 8: Configurar Domínio')}
+   # No dashboard Cloudflare:
+   # 1. Workers & Pages → Routes → Add Route
+   # 2. Exemplo: seu-dominio.com/api/tracking/*
+   # 3. Aponte para o worker criado
+
+${chalk.green.bold('✅ Pronto! Seu tracking Quantum Tier está ativo.')}
+
+${chalk.gray('Para mais detalhes, consulte docs/guia-cloudflare-iniciante.md')}
+`;
+
+  console.log(guide);
+}