cdp-edge 2.2.5 → 2.3.1

package/README.md

@@ -2,7 +2,9 @@
 
 **Padrão Quantum Tracking: 100% Cloudflare Edge.** Sem GTM. Sem Stape. Sem cookies de terceiros.
 
-> **v2.2.5** — Versão Dinâmica · Correção de banner e CLI · Cloudflare Workers · Meta CAPI v22.0 · GA4 MP · TikTok Events API v1.3
+> **v2.3.1** — Hardening Enterprise · PII removido dos logs · Script de deploy seguro (`deploy-client.js`) · WhatsApp secrets alinhados à Meta Cloud API v22.0 · `api-versions.json` v1.1.0
+
+> ⚠️ **REGRA DE OURO (SQUAD):** Todas as atualizações, correções ou novas features devem OBRIGATORIAMENTE ser documentadas de forma sincronizada neste `README.md`, no arquivo de instruções `CLAUDE.md` e no dossiê de diretoria `CDP-EDGE-BUSINESS-BOOK.md`. Nenhuma alteração passa sem esse tripé.
 
 ---
 
@@ -25,6 +27,59 @@ Meu ecossistema opera como um Cérebro de Conversão Privado na borda. Quando um
 
 ---
 
+## 📋 CHANGELOG v2.3.1 — Hardening Enterprise (12 de Abril de 2026)
+
+### 🔒 Segurança & Conformidade
+
+- **PII removido dos logs:** `DeviceGraph` parou de logar `user_id` nos Workers logs — dados sensíveis nunca aparecem no Cloudflare dashboard
+- **Deploy seguro:** novo `deploy-client.js` — lê credenciais de `.client.env` (gitignored), gera `wrangler.deploy.toml` temporário, faz deploy e autodestrói o arquivo. Credenciais de cliente nunca entram no repo
+- **`.gitignore` reforçado:** `.client.env` e `wrangler.deploy.toml` explicitamente ignorados
+- **WhatsApp secrets alinhados à Meta Cloud API v22.0:** `resolvePhoneNumberId()` e `resolveAccessToken()` com fallback canônico → legado — backwards compat garantido
+- **`api-versions.json` v1.1.0:** metadata `updated_at` corrigido para `2026-04-12`
+- **`/health` WhatsApp:** reflete corretamente secrets com nomes canônicos ou legados
+
+### 🔧 Deploy de Cliente — Novo Fluxo
+
+```bash
+cd server-edge-tracker
+cp .client.env.example .client.env
+# preencher DATABASE_ID, SITE_DOMAIN, pixels
+node deploy-client.js --dry-run   # valida sem subir
+node deploy-client.js             # deploy real
+```
+
+---
+
+## 📋 CHANGELOG v2.3.0 — TypeScript Nativo (12 de Abril de 2026)
+
+### 🔷 Worker 100% TypeScript — Migração Completa
+
+Todo o código server-side (`server-edge-tracker/`) foi migrado de JavaScript para **TypeScript nativo**. O Wrangler compila diretamente o `.ts` via esbuild — sem etapa de build separada, sem configuração extra.
+
+**Por que TypeScript muda o jogo no CDP Edge:**
+- **Env tipado** — typos em nomes de secrets (`META_ACCESS_TOKEN`, `GEO_CACHE`, `DB`) viram erros em build time, nunca em produção
+- **TrackPayload contratado** — o shape do payload entre browser e Worker é garantido pelo compilador
+- **Cloudflare types nativos** — D1, KV, R2, Workers AI com autocomplete e validação de métodos
+- **Fraud Gate e ML seguros** — `checkFraudGate(env: Env, request: Request, payload: TrackPayload)` — nenhum `undefined` passa despercebido
+- **Refatoração segura** — renomear qualquer campo do `TrackPayload` lista automaticamente todos os pontos de quebra
+
+**Arquivos migrados (JS → TS) — 16 módulos:**
+- `index.ts` — entry point do Worker
+- `types.ts` — **novo** — contratos centralizados: `Env`, `TrackPayload`, `BehavioralData`, `HotmartWebhook`, `KiwifyWebhook`, `TictoWebhook`, `QueueMessage`, `PromiseResult<T>`
+- `modules/utils.ts`, `modules/db.ts`, `modules/intelligence.ts`
+- `modules/dispatch/` — `meta.ts`, `ga4.ts`, `tiktok.ts`, `platforms.ts`, `whatsapp.ts`
+- `modules/ml/` — `ltv.ts`, `fraud.ts`, `bidding.ts`, `segmentation.ts`, `logistic.ts`, `matchquality.ts`
+
+**Infraestrutura:**
+- `tsconfig.json` — `target: ESNext`, `moduleResolution: "bundler"`, `strict: true`, `@cloudflare/workers-types`
+- `wrangler.toml` — `main = "index.ts"` (TypeScript nativo via wrangler/esbuild)
+- `contracts/types.ts` — tipos públicos exportados no pacote NPM: `QuantumEventPayload`, `AgencyContext`, `ApiVersionsConfig`
+- `npm run typecheck` — `tsc --noEmit` (225 testes passando, zero erros de compilação)
+
+**Breaking change:** nenhuma — API HTTP e comportamento em runtime são idênticos. TypeScript é invisível para o Cloudflare.
+
+---
+
 ## 📋 CHANGELOG v2.2.5 (11 de Abril de 2026)
 
 ### 🔧 Correção de Versão Dinâmica
@@ -65,7 +120,7 @@ Meu ecossistema opera como um Cérebro de Conversão Privado na borda. Quando um
 - **YouTube events**: `video_milestone`/`video_progress_25/50/75` → `video_25`/`video_50`/`video_75` (alinhado ao VALID_EVENT_NAMES do worker)
 - **LinkedIn CAPI**: endpoint `/rest/conversionEvents` + header `LinkedIn-Version: 202401` em `contracts/api-versions.json`
 - **Workers AI model**: `llama-3-8b-instruct` → `@cf/meta/llama-3.1-8b-instruct`
-- **worker.js**: Content-Length guard (413 se > 64KB), payload validation (allowlist 19 events, 512 chars, value range), PII removido dos logs
+- **index.ts**: Content-Length guard (413 se > 64KB), payload validation (allowlist 19 events, 512 chars, value range), PII removido dos logs
 - **Testes**: bugs críticos em `deduplication.test.js` corrigidos (template literals escapados, prefixo errado)
 - **npm**: lodash 4.17.23 → 4.18.1, node-fetch removido
 

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/docs/whatsapp-ctwa.md

@@ -199,11 +199,12 @@ fetch('https://SEU_WORKER.SEU_USUARIO.workers.dev/track', {
 
 | Arquivo | Descrição |
 |---------|-----------|
-| `server-edge-tracker/worker.js` | Função `processWhatsAppWebhook()` (linha ~943) e rotas (linha ~2182) |
+| `server-edge-tracker/modules/dispatch/whatsapp.ts` | Funções `processWhatsAppWebhook()`, `sendWhatsApp()`, `verifyHmac()` |
+| `server-edge-tracker/index.ts` | Rotas `/webhook/whatsapp` (GET verify + POST mensagens) |
 | `server-edge-tracker/migrate-v6.sql` | Migration que criou a tabela `whatsapp_contacts` |
 | `server-edge-tracker/wrangler.toml` | Secret `WA_WEBHOOK_VERIFY_TOKEN` documentado |
 | `server-edge-tracker/schema.sql` | Schema completo do D1 (referência) |
 
 ---
 
-*Implementado em: 30 de março de 2026. CDP Edge v1.2 — WhatsApp CTWA Module.*
+*Implementado em: 30 de março de 2026. CDP Edge v1.2 — WhatsApp CTWA Module. Migrado para TypeScript (`whatsapp.ts`) em 12 de abril de 2026 (v2.2.5+).*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cdp-edge",
-  "version": "2.2.5",
+  "version": "2.3.1",
   "description": "CDP Edge - Quantum Tracking - Sistema multi-agente para tracking digital Cloudflare Native (Workers + D1)",
   "main": "dist/index.js",
   "type": "module",
@@ -34,7 +34,8 @@
     "agents:check": "node scripts/validate-agents.js",
     "agents:sync": "node scripts/sync-agents.js",
     "agents:sync:list": "node scripts/sync-agents.js --list",
-    "agents:sync:all": "node scripts/sync-agents.js --apply-all"
+    "agents:sync:all": "node scripts/sync-agents.js --apply-all",
+    "typecheck": "tsc --noEmit"
   },
   "keywords": [
     "pixel",
@@ -71,12 +72,14 @@
     "ora": "^8.0.0"
   },
   "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260412.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^13.0.1",
     "@semantic-release/github": "^12.0.6",
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.0",
-    "@types/node": "^20.0.0",
-    "semantic-release": "^25.0.3"
+    "@types/node": "^20.19.39",
+    "semantic-release": "^25.0.3",
+    "typescript": "^6.0.2"
   }
 }

package/server-edge-tracker/.client.env.example

@@ -0,0 +1,14 @@
+# CDP Edge — Variáveis do cliente para deploy
+# Copie este arquivo para .client.env e preencha com os dados reais.
+# .client.env é gitignored — NUNCA commitado.
+
+# Cloudflare D1 — obter com: wrangler d1 list
+DATABASE_ID=SEU_DATABASE_ID
+
+# Domínio do projeto (sem https://)
+SITE_DOMAIN=seudominio.com.br
+
+# Pixels de rastreamento (opcional — deixar vazio se não usar)
+META_PIXEL_ID=
+GA4_MEASUREMENT_ID=
+TIKTOK_PIXEL_ID=

package/server-edge-tracker/deploy-client.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * CDP Edge — deploy-client.js
+ *
+ * Deploy do Worker com variáveis reais do cliente, sem commitar credenciais no repo.
+ * Lê de .client.env (gitignored) e gera um wrangler.deploy.toml temporário.
+ *
+ * Uso:
+ *   node deploy-client.js           → deploy completo
+ *   node deploy-client.js --dry-run → valida sem subir ao Cloudflare
+ *
+ * Setup:
+ *   cp .client.env.example .client.env
+ *   # edite .client.env com os valores do cliente
+ *   node deploy-client.js
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+const ROOT    = __dirname;
+const TOML    = path.join(ROOT, 'wrangler.toml');
+const DEPLOY  = path.join(ROOT, 'wrangler.deploy.toml');
+const ENV     = path.join(ROOT, '.client.env');
+const DRY_RUN = process.argv.includes('--dry-run');
+
+// ── Carregar .client.env ──────────────────────────────────────────────────────
+if (!fs.existsSync(ENV)) {
+  console.error('\n❌  .client.env não encontrado.');
+  console.error('   cp .client.env.example .client.env  e preencha os valores do cliente.\n');
+  process.exit(1);
+}
+
+const env = {};
+fs.readFileSync(ENV, 'utf8').split('\n').forEach(line => {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith('#')) return;
+  const [key, ...rest] = trimmed.split('=');
+  if (key) env[key.trim()] = rest.join('=').trim();
+});
+
+const required = ['DATABASE_ID', 'SITE_DOMAIN'];
+const missing  = required.filter(k => !env[k]);
+if (missing.length > 0) {
+  console.error(`\n❌  Variáveis obrigatórias faltando no .client.env: ${missing.join(', ')}\n`);
+  process.exit(1);
+}
+
+// ── Substituir placeholders no wrangler.toml → wrangler.deploy.toml ───────────
+let toml = fs.readFileSync(TOML, 'utf8');
+
+toml = toml
+  .replace(/SEU_DATABASE_ID/g,  env.DATABASE_ID)
+  .replace(/SEU_DOMINIO/g,       env.SITE_DOMAIN)
+  .replace(/META_PIXEL_ID\s*=\s*""/,      `META_PIXEL_ID      = "${env.META_PIXEL_ID      || ''}"`)
+  .replace(/GA4_MEASUREMENT_ID\s*=\s*""/,  `GA4_MEASUREMENT_ID = "${env.GA4_MEASUREMENT_ID || ''}"`)
+  .replace(/TIKTOK_PIXEL_ID\s*=\s*""/,     `TIKTOK_PIXEL_ID    = "${env.TIKTOK_PIXEL_ID    || ''}"`);
+
+fs.writeFileSync(DEPLOY, toml);
+
+// ── Executar wrangler deploy ──────────────────────────────────────────────────
+const cmd = `wrangler deploy --config wrangler.deploy.toml${DRY_RUN ? ' --dry-run' : ''}`;
+console.log(`\n🚀  ${DRY_RUN ? '[DRY-RUN] ' : ''}Deploying com config do cliente...\n`);
+
+try {
+  execSync(cmd, { stdio: 'inherit', cwd: ROOT });
+  console.log(`\n✅  Deploy ${DRY_RUN ? '(dry-run) ' : ''}concluído.\n`);
+} catch (err) {
+  console.error('\n❌  Deploy falhou.\n');
+  process.exit(1);
+} finally {
+  // sempre remove o arquivo temporário
+  if (fs.existsSync(DEPLOY)) fs.unlinkSync(DEPLOY);
+  console.log('🧹  wrangler.deploy.toml removido.\n');
+}