cdp-edge 1.2.2 → 1.3.0

package/server-edge-tracker/modules/dispatch/crm.ts

@@ -0,0 +1,382 @@
+/**
+ * CDP Edge — EVO CRM Premium Integration
+ * Fluxo: Meta CAPI → Worker → Contato + Conversa + Nota interna no EVO CRM
+ *
+ * Secrets necessários (wrangler secret put):
+ *   EVO_CRM_BASE_URL        → URL base do EVO CRM (ex: https://api-evocrm.suaempresa.com)
+ *   EVO_CRM_CLIENT_ID       → OAuth client_id (Doorkeeper app no CRM)
+ *   EVO_CRM_CLIENT_SECRET   → OAuth client_secret
+ *   EVO_CRM_INBOX_ID        → ID do inbox onde as conversas serão criadas
+ *
+ * Secrets opcionais (defaults BR):
+ *   EVO_CRM_DEFAULT_COUNTRY → Dial code para números locais sem +cc (default "55")
+ *   EVO_CRM_LOCALE          → "pt-BR" | "en-US" | "es-ES" (default "pt-BR")
+ *
+ * Uso (qualquer origem de lead):
+ *   await pushLeadToCrm(env, {
+ *     phone: '5511999990000',
+ *     name: 'João Silva',
+ *     email: 'joao@exemplo.com',
+ *     utmSource: 'facebook',
+ *     utmCampaign: 'campanha-x',
+ *     fbclid: 'AbC123...',
+ *     intentScore: 85,
+ *     ltvClass: 'high',
+ *     pageUrl: 'https://exemplo.com/lp',
+ *   });
+ */
+
+import { Env } from '../../types.js';
+
+// ── Tipos públicos ────────────────────────────────────────────────────────────
+
+export interface CrmLeadData {
+  // Identificação
+  phone: string;
+  name?: string | null;
+  email?: string | null;
+
+  // Meta CAPI
+  fbclid?: string | null;
+  fbc?: string | null;
+  fbp?: string | null;
+  ctwaClid?: string | null;
+  adId?: string | null;
+  messageBody?: string | null;
+  headline?: string | null;
+
+  // UTMs
+  utmSource?: string | null;
+  utmMedium?: string | null;
+  utmCampaign?: string | null;
+  utmContent?: string | null;
+  utmTerm?: string | null;
+
+  // Contexto
+  eventName?: string | null;
+  pageUrl?: string | null;
+  formName?: string | null;
+
+  // Scoring (Quantum Tracking)
+  intentScore?: number | null;
+  ltvClass?: string | null;
+  funnelStage?: string | null;
+  botScore?: number | null;
+
+  // Monetário
+  value?: number | null;
+  currency?: string | null;
+
+  // Atributos livres adicionais
+  attributes?: Record<string, string>;
+}
+
+/** @deprecated Use CrmLeadData + pushLeadToCrm */
+export interface CTWALeadData {
+  phone: string;
+  name?: string | null;
+  messageBody?: string | null;
+  ctwaClid?: string | null;
+  adId?: string | null;
+  sourceUrl?: string | null;
+  headline?: string | null;
+  wamid?: string | null;
+}
+
+/** @deprecated Use CrmLeadData + pushLeadToCrm */
+export interface FormLeadData {
+  phone: string;
+  name?: string | null;
+  email?: string | null;
+  formName?: string | null;
+  utmSource?: string | null;
+  utmCampaign?: string | null;
+  pageUrl?: string | null;
+}
+
+// ── Helpers internos ──────────────────────────────────────────────────────────
+
+function isCrmConfigured(env: Env): boolean {
+  return !!(env.EVO_CRM_BASE_URL && env.EVO_CRM_CLIENT_ID && env.EVO_CRM_CLIENT_SECRET);
+}
+
+function normalizePhone(phone: string, defaultCountryCode = '55'): string {
+  const trimmed = phone.trim();
+  const cc = (defaultCountryCode || '55').replace(/\D/g, '') || '55';
+
+  // Already in E.164 (starts with +): só limpa e re-prefixa
+  if (trimmed.startsWith('+')) return '+' + trimmed.replace(/\D/g, '');
+
+  const digits = trimmed.replace(/\D/g, '');
+
+  // Comportamento BR canônico (preservado): 55 + 10 ou 11 dígitos = válido
+  if (cc === '55' && digits.startsWith('55') && (digits.length === 12 || digits.length === 13)) {
+    return `+${digits}`;
+  }
+  if (cc === '55' && (digits.length === 10 || digits.length === 11)) {
+    return `+55${digits}`;
+  }
+
+  // Genérico: já tem o country code
+  if (digits.startsWith(cc) && digits.length > cc.length + 6) return `+${digits}`;
+
+  // Genérico: número local → prepend country code
+  if (digits.length >= 7 && digits.length <= 11) return `+${cc}${digits}`;
+
+  // Fallback: assume que já tem algum cc
+  return `+${digits}`;
+}
+
+// ── Localização da nota interna ───────────────────────────────────────────────
+
+type Locale = 'pt-BR' | 'en-US' | 'es-ES';
+
+const NOTE_LABELS: Record<Locale, Record<string, string>> = {
+  'pt-BR': {
+    title: '📊 *Novo Lead*',
+    name: 'Nome',
+    source: 'Origem',
+    campaign: 'Campanha',
+    form: 'Formulário',
+    ad: 'Anúncio',
+    message: 'Mensagem',
+    score: 'Score',
+    ltv: 'LTV',
+  },
+  'en-US': {
+    title: '📊 *New Lead*',
+    name: 'Name',
+    source: 'Source',
+    campaign: 'Campaign',
+    form: 'Form',
+    ad: 'Ad',
+    message: 'Message',
+    score: 'Score',
+    ltv: 'LTV',
+  },
+  'es-ES': {
+    title: '📊 *Nuevo Lead*',
+    name: 'Nombre',
+    source: 'Origen',
+    campaign: 'Campaña',
+    form: 'Formulario',
+    ad: 'Anuncio',
+    message: 'Mensaje',
+    score: 'Score',
+    ltv: 'LTV',
+  },
+};
+
+function resolveLocale(input?: string | null): Locale {
+  if (input && input in NOTE_LABELS) return input as Locale;
+  return 'pt-BR';
+}
+
+async function getAccessToken(env: Env): Promise<string | null> {
+  try {
+    const res = await fetch(`${env.EVO_CRM_BASE_URL}/oauth/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({
+        grant_type: 'client_credentials',
+        client_id: env.EVO_CRM_CLIENT_ID!,
+        client_secret: env.EVO_CRM_CLIENT_SECRET!,
+      }),
+    });
+    if (!res.ok) return null;
+    const data: any = await res.json();
+    return data.access_token ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/** Nota interna para o agente: apenas o essencial para atender o lead. */
+function buildAgentNote(data: CrmLeadData, locale: Locale = 'pt-BR'): string {
+  const L = NOTE_LABELS[locale];
+  const lines: string[] = [L.title];
+
+  const name = data.name || data.phone;
+  lines.push(`• ${L.name}: ${name}`);
+
+  const source = [data.utmSource, data.utmMedium].filter(Boolean).join(' / ');
+  if (source) lines.push(`• ${L.source}: ${source}`);
+
+  if (data.utmCampaign) lines.push(`• ${L.campaign}: ${data.utmCampaign}`);
+  if (data.formName && data.formName !== data.eventName) lines.push(`• ${L.form}: ${data.formName}`);
+  if (data.headline)    lines.push(`• ${L.ad}: ${data.headline}`);
+  if (data.messageBody) lines.push(`• ${L.message}: "${data.messageBody}"`);
+
+  if (data.intentScore != null) {
+    const score = data.intentScore > 1 ? data.intentScore : Math.round(data.intentScore * 100);
+    const stage = data.funnelStage ? ` · ${data.funnelStage}` : '';
+    lines.push(`• ${L.score}: ${score}${stage}`);
+  }
+  if (data.ltvClass) lines.push(`• ${L.ltv}: ${data.ltvClass}`);
+
+  return lines.join('\n');
+}
+
+/** Monta additional_attributes para o contato no CRM. */
+function buildContactAttributes(data: CrmLeadData): Record<string, string> {
+  const attrs: Record<string, string> = {};
+
+  if (data.utmSource)   attrs['utm_source']   = data.utmSource;
+  if (data.utmMedium)   attrs['utm_medium']   = data.utmMedium;
+  if (data.utmCampaign) attrs['utm_campaign'] = data.utmCampaign;
+  if (data.utmContent)  attrs['utm_content']  = data.utmContent;
+  if (data.utmTerm)     attrs['utm_term']     = data.utmTerm;
+  if (data.pageUrl)     attrs['pagina']       = data.pageUrl;
+  if (data.formName)    attrs['formulario']   = data.formName;
+  if (data.fbclid)      attrs['fbclid']       = data.fbclid;
+  if (data.fbc)         attrs['fbc']          = data.fbc;
+  if (data.fbp)         attrs['fbp']          = data.fbp;
+  if (data.ctwaClid)    attrs['ctwa_clid']    = data.ctwaClid;
+  if (data.adId)        attrs['ad_id']        = data.adId;
+  if (data.messageBody) attrs['mensagem']     = data.messageBody;
+  if (data.headline)    attrs['anuncio']      = data.headline;
+  if (data.ltvClass)    attrs['ltv_class']    = data.ltvClass;
+  if (data.funnelStage) attrs['funil']        = data.funnelStage;
+  if (data.intentScore != null) attrs['intencao'] = String(data.intentScore);
+  if (data.eventName)   attrs['evento']       = data.eventName;
+
+  // Atributos livres
+  if (data.attributes) Object.assign(attrs, data.attributes);
+
+  return attrs;
+}
+
+// ── API principal (recomendada) ───────────────────────────────────────────────
+
+/**
+ * Cria contato + conversa aberta + nota interna no EVO CRM.
+ * Silencioso se os secrets não estiverem configurados.
+ * Retorna o ID do contato criado ou null em caso de erro/duplicata.
+ */
+export async function pushLeadToCrm(env: Env, data: CrmLeadData): Promise<string | null> {
+  if (!isCrmConfigured(env)) return null;
+
+  const token = await getAccessToken(env);
+  if (!token) {
+    console.warn('[EVO CRM] Failed to get access token');
+    return null;
+  }
+
+  const locale = resolveLocale(env.EVO_CRM_LOCALE);
+  const defaultCountry = env.EVO_CRM_DEFAULT_COUNTRY || '55';
+
+  const attrs = buildContactAttributes(data);
+  const contactPayload: Record<string, any> = {
+    name: data.name || data.phone,
+    phone_number: normalizePhone(data.phone, defaultCountry),
+  };
+  if (data.email) contactPayload.email = data.email;
+  if (Object.keys(attrs).length) contactPayload.additional_attributes = attrs;
+
+  // 1. Criar contato
+  let contactId: string | null = null;
+  try {
+    const res = await fetch(`${env.EVO_CRM_BASE_URL}/api/v1/contacts`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+      body: JSON.stringify(contactPayload),
+    });
+    if (!res.ok) {
+      const body = await res.text();
+      console.warn('[EVO CRM] createContact non-ok:', res.status, body.slice(0, 200));
+      // 422 = contato já existe — tentar extrair o ID do payload de erro
+      if (res.status === 422) {
+        try {
+          const errJson: any = JSON.parse(body);
+          const rawId = errJson?.id ?? errJson?.data?.id ?? errJson?.contact?.id ?? errJson?.data?.contact?.id;
+          if (rawId != null) contactId = String(rawId);
+        } catch { /* body não é JSON */ }
+      }
+      if (!contactId) return null;
+    } else {
+      const result: any = await res.json();
+      // EVO CRM pode retornar { id } direto ou { data: { id } } ou { data: { contact: { id } } }
+      const rawId = result?.id ?? result?.data?.id ?? result?.data?.contact?.id;
+      contactId = rawId != null ? String(rawId) : null;
+    }
+  } catch (err: any) {
+    console.warn('[EVO CRM] createContact failed:', err?.message || String(err));
+    return null;
+  }
+
+  if (!contactId || !env.EVO_CRM_INBOX_ID) return contactId;
+
+  // 2. Criar conversa
+  let conversationId: string | null = null;
+  try {
+    const res = await fetch(`${env.EVO_CRM_BASE_URL}/api/v1/conversations`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+      body: JSON.stringify({
+        inbox_id: env.EVO_CRM_INBOX_ID,
+        contact_id: contactId,
+        additional_attributes: {},
+      }),
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      console.warn('[EVO CRM] createConversation non-ok:', res.status, err.slice(0, 200));
+    } else {
+      const result: any = await res.json();
+      const rawConvId = result?.id ?? result?.data?.id;
+      conversationId = rawConvId != null ? String(rawConvId) : null;
+    }
+  } catch (err: any) {
+    console.warn('[EVO CRM] createConversation failed:', err?.message || String(err));
+  }
+
+  // 3. Criar nota interna com contexto do lead
+  if (conversationId) {
+    try {
+      await fetch(`${env.EVO_CRM_BASE_URL}/api/v1/conversations/${conversationId}/messages`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` },
+        body: JSON.stringify({
+          content: buildAgentNote(data, locale),
+          message_type: 'activity',
+          private: true,
+        }),
+      });
+    } catch {
+      // nota interna é best-effort
+    }
+  }
+
+  return contactId;
+}
+
+// ── Compat: CTWA (WhatsApp click-to-chat) ────────────────────────────────────
+
+export async function notifyEvolutionCTWA(env: Env, data: CTWALeadData): Promise<void> {
+  await pushLeadToCrm(env, {
+    phone: data.phone,
+    name: data.name,
+    messageBody: data.messageBody,
+    ctwaClid: data.ctwaClid,
+    adId: data.adId,
+    pageUrl: data.sourceUrl,
+    headline: data.headline,
+    utmSource: 'whatsapp',
+    eventName: 'CTWA',
+  });
+}
+
+// ── Compat: Formulário ────────────────────────────────────────────────────────
+
+export async function notifyEvolutionForm(env: Env, data: FormLeadData): Promise<void> {
+  await pushLeadToCrm(env, {
+    phone: data.phone,
+    name: data.name,
+    email: data.email,
+    formName: data.formName,
+    utmSource: data.utmSource,
+    utmCampaign: data.utmCampaign,
+    pageUrl: data.pageUrl,
+    eventName: 'Lead',
+  });
+}

package/server-edge-tracker/modules/dispatch/ga4.ts

@@ -0,0 +1,72 @@
+/**
+ * CDP Edge — GA4 Measurement Protocol
+ * Envia eventos server-side para o GA4 via Measurement Protocol.
+ */
+
+import { normalizePhone } from '../utils.js';
+import { logApiFailure } from '../db.js';
+import { Env, TrackPayload } from '../../types.js';
+import { ExecutionContext } from '@cloudflare/workers-types';
+
+export async function sendGA4Mp(env: Env, ga4EventName: string, payload: TrackPayload, ctx: ExecutionContext | null): Promise<{ ok?: boolean; status?: number; skipped?: string; error?: string }> {
+  if (!env.GA4_API_SECRET) return { skipped: 'GA4_API_SECRET not set' };
+
+  const {
+    gaClientId: clientId, sessionId,
+    value, currency, contentName,
+    email, phone, firstName,
+    orderId,
+  } = payload;
+
+  if (!clientId) return { skipped: 'no clientId' };
+
+  const eventParams: Record<string, string | number> = {
+    ...(value       !== undefined && { value: parseFloat(String(value)) }),
+    ...(currency    && { currency: String(currency).toUpperCase() }),
+    ...(contentName && { content_name: contentName }),
+    ...(orderId     && { transaction_id: orderId }),
+    ...(email       && { user_data_email_address: email.toLowerCase().trim() }),
+    ...(phone       && { user_data_phone_number: normalizePhone(phone) || '' }),
+    ...(firstName   && { user_data_first_name: firstName.toLowerCase().trim() }),
+    ...(sessionId   && { session_id: sessionId }),
+    engagement_time_msec: 100,
+  };
+
+  const body = {
+    client_id: clientId,
+    events: [{ name: ga4EventName, params: eventParams }],
+  };
+
+  const url = `https://www.google-analytics.com/mp/collect`
+            + `?measurement_id=${env.GA4_MEASUREMENT_ID}`
+            + `&api_secret=${env.GA4_API_SECRET}`;
+
+  try {
+    const res = await fetch(url, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body:    JSON.stringify(body),
+    });
+
+    if (res.status !== 204) {
+      if (env.DB && ctx) {
+        ctx.waitUntil(logApiFailure(env.DB, 'ga4', ga4EventName, String(res.status), 'GA4 returned non-204 status', '', JSON.stringify(body)));
+      }
+    }
+
+    return res.status === 204 ? { ok: true } : { status: res.status };
+  } catch (err: any) {
+    console.error('GA4 MP fetch failed:', err?.message || String(err));
+
+    if (env.DB && ctx) {
+      ctx.waitUntil(logApiFailure(env.DB, 'ga4', ga4EventName, 'FETCH_ERROR', err?.message || String(err), '', JSON.stringify(body)));
+    }
+
+    if (env.RETRY_QUEUE) {
+      const send = env.RETRY_QUEUE.send({ eventType: ga4EventName, payload, platform: 'ga4' });
+      if (ctx) ctx.waitUntil(send); else send.catch(() => {});
+    }
+
+    return { error: err?.message || String(err) };
+  }
+}

package/server-edge-tracker/modules/dispatch/meta.ts

@@ -0,0 +1,143 @@
+/**
+ * CDP Edge — Meta Conversions API v22.0
+ * Envia eventos server-side para a Meta CAPI.
+ */
+
+import { sha256, normalizePhone, normalizeCity } from '../utils.js';
+import { logApiFailure } from '../db.js';
+import { logMatchQuality, autoEnrichPayload } from '../ml/matchquality.js';
+import { Env, TrackPayload } from '../../types.js';
+import { ExecutionContext } from '@cloudflare/workers-types';
+
+interface EnrichedPayload {
+  payload: TrackPayload;
+  recovered: { email: boolean; utm: boolean };
+}
+
+export async function sendMetaCapi(env: Env, eventName: string, payload: TrackPayload, request: Request | null, ctx: ExecutionContext | null): Promise<any> {
+  // Auto-enriquecer payload com dados do Identity Graph antes do envio
+  let recovered = { email: false, utm: false };
+  if (env.DB && payload) {
+    const enriched  = await autoEnrichPayload(env, payload) as EnrichedPayload;
+    payload         = enriched.payload;
+    recovered       = enriched.recovered;
+  }
+
+  const {
+    email, phone, firstName, lastName,
+    city, state, country,
+    zip, dob,
+    fbp, fbc, userId,
+    eventId, pageUrl,
+    value, currency,
+    contentIds, contentName, contentType, numItems,
+    // Dual-layer context — funil avançado + imóveis
+    funnel_stage, distanceBucket: distance_bucket, intentScoreNum: intent_score, intent_bucket,
+    ltvScore, ltvClass, metaSignal, metaSignalBucket: metaSignalBucketVal,
+  } = payload;
+
+  const phoneNorm   = normalizePhone(phone);
+  const countryCode = (country || (request as any)?.cf?.country || 'br').toLowerCase();
+  const stateCode   = state ? String(state).toLowerCase() : undefined;
+  const cityNorm    = normalizeCity(city);
+
+  const userData: Record<string, string> = {
+    ...(email      && { em:       await sha256(email) || '' }),
+    ...(phoneNorm  && { ph:       await sha256(phoneNorm) || '' }),
+    ...(firstName  && { fn:       await sha256(firstName) || '' }),
+    ...(lastName   && { ln:       await sha256(lastName) || '' }),
+    ...(cityNorm   && { ct:       await sha256(cityNorm) || '' }),
+    ...(stateCode  && { st:       await sha256(stateCode) || '' }),
+    ...(countryCode && { country: await sha256(countryCode) || '' }),
+    ...(userId     && { external_id: await sha256(String(userId)) || '' }),
+    ...(zip        && { zp:         await sha256(zip) || '' }),
+    ...(dob        && { db:         await sha256(dob) || '' }),
+    ...(fbp        && { fbp }),
+    ...(fbc        && { fbc }),
+    client_ip_address: request?.headers.get('CF-Connecting-IP')
+                    || request?.headers.get('X-Forwarded-For')
+                    || '',
+    client_user_agent: request?.headers.get('User-Agent') || '',
+  };
+
+  const customData: Record<string, string | number | string[]> = {
+    ...(value       !== undefined && { value: parseFloat(String(value)) }),
+    ...(currency    && { currency: String(currency).toUpperCase() }),
+    ...(contentIds  && contentIds.length > 0 && { content_ids: contentIds }),
+    ...(contentName && { content_name: contentName }),
+    ...(contentType && { content_type: contentType }),
+    ...(numItems    && { num_items: parseInt(String(numItems)) }),
+    // Contexto de funil e proximidade — enriquece matching e otimização Meta
+    ...(funnel_stage    && { funnel_stage }),
+    ...(distance_bucket && { distance_bucket }),
+    ...(intent_score    && { intent_score }),
+    ...(ltvScore    !== undefined && ltvScore    !== null && { ltv_score: ltvScore }),
+    ...(ltvClass    && { ltv_class: ltvClass }),
+    ...(metaSignal       !== undefined && metaSignal       !== null && { meta_signal: metaSignal }),
+    ...(metaSignalBucketVal && { meta_signal_bucket: metaSignalBucketVal }),
+    ...(intent_bucket    && { intent_bucket }),
+  };
+
+  const eventPayload = {
+    event_name:       eventName,
+    event_time:       Math.floor(Date.now() / 1000),
+    event_id:         eventId || `cdp_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+    event_source_url: pageUrl || `https://${env.SITE_DOMAIN}`,
+    action_source:    'website',
+    user_data:        userData,
+    ...(Object.keys(customData).length > 0 && { custom_data: customData }),
+  };
+
+  const requestBody: Record<string, any> = {
+    data:         [eventPayload],
+    access_token: env.META_ACCESS_TOKEN,
+  };
+
+  if (env.META_TEST_CODE) {
+    requestBody.test_event_code = env.META_TEST_CODE;
+  }
+
+  // Logar match quality em background (não bloqueia dispatch)
+  if (env.DB && ctx) {
+    ctx.waitUntil(logMatchQuality(env.DB, eventName, payload, recovered));
+  } else if (env.DB) {
+    logMatchQuality(env.DB, eventName, payload, recovered).catch(() => {});
+  }
+
+  const endpoint = `https://graph.facebook.com/v22.0/${env.META_PIXEL_ID}/events`;
+
+  try {
+    const res = await fetch(endpoint, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body:    JSON.stringify(requestBody),
+    });
+
+    const data = await res.json();
+
+    if (!res.ok) {
+      const errorCode    = (data as any).error?.code || String(res.status);
+      const errorMessage = (data as any).error?.message || (data as any).error?.error_user_msg || 'Unknown error';
+      console.error('Meta CAPI error:', res.status, errorMessage);
+
+      if (env.DB && ctx) {
+        ctx.waitUntil(logApiFailure(env.DB, 'meta', eventName, errorCode, errorMessage, eventPayload.event_id, JSON.stringify(requestBody)));
+      }
+    }
+
+    return data;
+  } catch (err: any) {
+    console.error('Meta CAPI fetch failed:', err?.message || String(err));
+
+    if (env.DB && ctx) {
+      ctx.waitUntil(logApiFailure(env.DB, 'meta', eventName, 'FETCH_ERROR', err?.message || String(err), eventPayload.event_id, JSON.stringify(requestBody)));
+    }
+
+    if (env.RETRY_QUEUE) {
+      const send = env.RETRY_QUEUE.send({ eventType: eventName, payload, platform: 'meta' });
+      if (ctx) ctx.waitUntil(send); else send.catch(() => {});
+    }
+
+    return { error: err?.message || String(err) };
+  }
+}