cdp-edge 1.24.2 → 1.25.1

package/server-edge-tracker/modules/utm/utm-enricher.ts

@@ -0,0 +1,231 @@
+/**
+ * UTM Enricher Module
+ * Obfusca/desobfusca UTMs sensíveis (valores de produto)
+ * Integração com Agente UTM
+ */
+
+// ============================================================================
+// Constants & Config
+// ============================================================================
+
+const UTM_SALT = 'CDP_EDGE_UTM_SALT';
+const HASH_TRUNCATE_LENGTH = 8;
+
+// Obfuscação: SHA256(original + salt) → truncate(8)
+// Isso garante: mesmo valor → mesmo hash, mas irreversível sem o mapeamento
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface UTMMapping {
+  obfuscated: string;        // Hash truncado (ex: "8a3f1d2b")
+  original: string;          // Valor real (ex: "700k-1M")
+  category: string;          // "imovel", "automotivo", etc
+  pixel_audience?: string;   // ID da custom audience Meta
+  platform_specific?: {
+    meta?: { custom_audience_id?: string };
+    tiktok?: { pixel_id?: string };
+    ga4?: { event_parameter?: string };
+  };
+}
+
+export interface UTMMappingConfig {
+  method: 'sha256';
+  salt: string;
+  truncated_length: number;
+  mappings: UTMMapping[];
+}
+
+export interface EnrichedUTM {
+  source?: string;
+  medium?: string;
+  campaign?: string;
+  content?: string;
+  faixa_obfuscada?: string;    // Hash da faixa de valor
+  faixa_real?: string;         // Valor real (de-obfuscado)
+  faixa_category?: string;    // Categoria do produto
+  product_id_obfuscated?: string;
+  product_id_real?: string;
+}
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * Obfusca um valor sensível usando SHA256 + truncate
+ * @param value - Valor a ser obfuscado (ex: "700k-1M")
+ * @returns Hash truncado de 8 caracteres
+ */
+export function obfuscateValue(value: string): string {
+  // sha256(value + salt) → truncate(8)
+  const hash = sha256(`${value}${UTM_SALT}`);
+  return hash.substring(0, HASH_TRUNCATE_LENGTH);
+}
+
+/**
+ * Verifica se um hash é válido (8 chars hex)
+ */
+export function isValidObfuscatedHash(hash: string): boolean {
+  return /^[a-f0-9]{8}$/.test(hash);
+}
+
+/**
+ * Desobfusca um valor usando o mapeamento
+ * @param obfuscated - Hash obfuscado
+ * @param mappings - Mapeamento de UTM (do config/utm-mapping.json)
+ * @returns UTM com valor real ou undefined se não encontrado
+ */
+export function deobfuscateValue(
+  obfuscated: string,
+  mappings: UTMMapping[]
+): UTMMapping | undefined {
+  return mappings.find(m => m.obfuscated === obfuscated);
+}
+
+/**
+ * Enrich payload com UTMs, desobfuscando valores sensíveis
+ */
+export function enrichPayloadWithUTM(
+  payload: any,
+  utms: Record<string, string>,
+  mappings: UTMMapping[]
+): { enriched: any; faixa?: UTMMapping } {
+  const enriched = { ...payload };
+  let faixa: UTMMapping | undefined;
+
+  // Desobfuscar faixa de valor
+  if (utms.faixa_obfuscada || utms.utm_faixa) {
+    const faixaHash = utms.faixa_obfuscada || utms.utm_faixa;
+    if (isValidObfuscatedHash(faixaHash)) {
+      faixa = deobfuscateValue(faixaHash, mappings);
+      if (faixa) {
+        enriched.faixa_real = faixa.original;
+        enriched.faixa_category = faixa.category;
+        enriched.pixel_audience = faixa.pixel_audience;
+      }
+    }
+  }
+
+  // Extrair UTMs padrão
+  enriched.utm_source = utms.utm_source || utms.source;
+  enriched.utm_medium = utms.utm_medium || utms.medium;
+  enriched.utm_campaign = utms.utm_campaign || utms.campaign;
+  enriched.utm_content = utms.utm_content || utms.content;
+
+  return { enriched, faixa };
+}
+
+/**
+ * Gera UTM obfuscada para uma faixa de valor
+ * @param range - Faixa real (ex: "700k-1M")
+ * @param category - Categoria (ex: "imovel")
+ * @returns Object com hash obfuscado
+ */
+export function generateObfuscatedUTM(range: string, category: string) {
+  const obfuscated = obfuscateValue(range);
+  return {
+    utm_faixa: obfuscated,
+    utm_campaign: `${category}_${obfuscated}`,
+    original_range: range,
+    hash: obfuscated
+  };
+}
+
+/**
+ * Cria um novo mapeamento de UTM
+ */
+export function createUTMMapping(
+  original: string,
+  category: string,
+  platform_specific?: any
+): UTMMapping {
+  return {
+    obfuscated: obfuscateValue(original),
+    original,
+    category,
+    platform_specific
+  };
+}
+
+// ============================================================================
+// Integration Functions (para uso no Worker)
+// ============================================================================
+
+/**
+ * Verifica se payload tem UTMs de segmentação
+ */
+export function hasSegmentationUTM(utms: Record<string, string>): boolean {
+  return !!(
+    utms.faixa_obfuscada ||
+    utms.utm_faixa ||
+    (utms.utm_campaign && isValidObfuscatedHash(
+      utms.utm_campaign.split('_').pop() || ''
+    ))
+  );
+}
+
+/**
+ * Extrai faixa de valor do utm_campaign (pattern: category_hash)
+ */
+export function extractFaixaFromCampaign(
+  campaign: string
+): string | null {
+  const parts = campaign.split('_');
+  const hash = parts.pop();
+  if (hash && isValidObfuscatedHash(hash)) {
+    return hash;
+  }
+  return null;
+}
+
+/**
+ * Para Meta CAPI: adiciona segmentação ao external_id
+ */
+export function addSegmentationToExternalId(
+  cdp_uid: string,
+  faixa: UTMMapping
+): string {
+  return `${cdp_uid}_${faixa.obfuscated}`;
+}
+
+/**
+ * Para GA4: cria custom parameter segmentado
+ */
+export function createSegmentationCustomParameter(faixa: UTMMapping) {
+  return {
+    'custom_faixa_categoria': faixa.category,
+    'custom_faixa_obfuscada': faixa.obfuscated,
+    'custom_faixa_audience': faixa.pixel_audience || 'UNKNOWN'
+  };
+}
+
+// ============================================================================
+// Import de sha256 (reutilizar de utils.ts)
+// ============================================================================
+
+function sha256(message: string): string {
+  // Importado de utils.ts - implementação real do SHA256
+  // Aqui simulamos para o exemplo:
+  const crypto = require('crypto');
+  return crypto.createHash('sha256').update(message).digest('hex');
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export const UTM_ENRICHER_VERSION = '1.0.0';
+
+export default {
+  obfuscateValue,
+  deobfuscateValue,
+  enrichPayloadWithUTM,
+  generateObfuscatedUTM,
+  createUTMMapping,
+  hasSegmentationUTM,
+  extractFaixaFromCampaign,
+  addSegmentationToExternalId,
+  createSegmentationCustomParameter
+};

package/server-edge-tracker/schema-utm.sql

@@ -0,0 +1,80 @@
+-- ============================================================================
+-- SCHEMA UTM OBFUSCATION — Fase de Segmentação de Valor
+-- ============================================================================
+-- Este schema estende o schema.sql existente com colunas para UTMs obfuscadas
+-- e uma tabela de mapeamento para de-obfuscação no runtime.
+--
+-- Como funciona:
+-- 1. utm_mappings: mapeia hash obfuscado → valor real (configuração)
+-- 2. leads: adiciona colunas faixa_real, faixa_category (segmentação)
+-- 3. dispatch: payload enriquecido com faixa de-obfuscada para Meta CAPI
+--
+-- ============================================================================
+-- TABELA: utm_mappings (configuração de segmentação)
+-- ============================================================================
+CREATE TABLE IF NOT EXISTS utm_mappings (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  obfuscated_hash TEXT NOT NULL UNIQUE,           -- ex: "8a3f1d2b" (hash truncado de 8 chars)
+  original_value TEXT NOT NULL,                    -- ex: "700k-1M" (valor real)
+  category TEXT NOT NULL,                         -- ex: "imovel", "automotivo", "curso"
+  pixel_audience TEXT,                            -- ex: "AUDIENCE_MID" (Meta custom audience)
+  platform_specific TEXT,                          -- JSON com IDs específicos por plataforma
+  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+-- ============================================================================
+-- ÍNDICES: utm_mappings
+-- ============================================================================
+CREATE INDEX IF NOT EXISTS idx_utm_obfuscated ON utm_mappings(obfuscated_hash);
+CREATE INDEX IF NOT EXISTS idx_utm_category ON utm_mappings(category);
+
+-- ============================================================================
+-- ALTER: leads (adicionar colunas de segmentação)
+-- ============================================================================
+ALTER TABLE leads ADD COLUMN IF NOT EXISTS faixa_obfuscada TEXT;       -- Hash da faixa de valor (vem da URL)
+ALTER TABLE leads ADD COLUMN IF NOT EXISTS faixa_real TEXT;            -- Valor real de-obfuscado (ex: "700k-1M")
+ALTER TABLE leads ADD COLUMN IF NOT EXISTS faixa_category TEXT;         -- Categoria do produto (ex: "imovel")
+
+-- ============================================================================
+-- ÍNDICES: leads (novas colunas para segmentação)
+-- ============================================================================
+CREATE INDEX IF NOT EXISTS idx_leads_faixa_real ON leads(faixa_real);
+CREATE INDEX IF NOT EXISTS idx_leads_faixa_category ON leads(faixa_category);
+CREATE INDEX IF NOT EXISTS idx_leads_faixa_obfuscada ON leads(faixa_obfuscada);
+
+-- ============================================================================
+-- VIEW: leads_segmented (para queries de segmentação)
+-- ============================================================================
+CREATE VIEW IF NOT EXISTS leads_segmented AS
+SELECT
+  l.id,
+  l.user_id,
+  l.event,
+  l.event_id,
+  l.email,
+  l.phone,
+  l.city,
+  l.state,
+  l.faixa_obfuscada,
+  l.faixa_real,
+  l.faixa_category,
+  l.created_at,
+  l.value,
+  l.intent_score,
+  l.ltv_class,
+  -- Meta CAPI: custom audience de-obfuscada
+  u.pixel_audience AS meta_custom_audience
+FROM leads l
+LEFT JOIN utm_mappings u ON l.faixa_obfuscada = u.obfuscated_hash;
+
+-- ============================================================================
+-- EXEMPLO: Query para exportar leads por faixa de valor (para Meta Custom Audience)
+-- ============================================================================
+-- SELECT email, phone, city, state, faixa_real, meta_custom_audience
+-- FROM leads_segmented
+-- WHERE faixa_category = 'imovel' AND faixa_real = '700k-1M'
+--   AND created_at >= datetime('now', '-30 days');
+--
+-- Isso gera um CSV pronto para upload como Custom Audience na Meta.
+-- ============================================================================