/** * `captureLead` — idempotent upsert helper for the marketing capture endpoint * (Phase 05 #78). * * Behaviour: * - When no Lead exists for the email: insert a new row, populate * first-touch UTM/referrer/landingPage attribution, store first * captured `LeadEvent` of type `captured`. * - When a Lead exists: update `lastTouchAt` + `lastIpHash` + `userAgent`, * merge missing optional profile fields (firstName, lastName, phone, * company), but NEVER overwrite already-set attribution columns (first- * touch semantics). Append a `re-captured` LeadEvent. * * The helper never throws on duplicate-email — the unique index guarantees * idempotency. Validation is the caller's responsibility (Zod-parsed input). */ import { createHash } from "node:crypto"; import { captureMarketingLeadCapability } from "@hivegrid/db/pretenant-security.server"; export interface CaptureLeadInput { email: string; firstName?: string | null; lastName?: string | null; phone?: string | null; company?: string | null; source?: string | null; /** Attribution fields. Treated as first-touch — set only on insert. */ attribution?: { utmSource?: string | null; utmMedium?: string | null; utmCampaign?: string | null; utmTerm?: string | null; utmContent?: string | null; gclid?: string | null; fbclid?: string | null; referrer?: string | null; landingPage?: string | null; }; ip?: string | null; userAgent?: string | null; } export interface CaptureLeadResult { /** Persisted (or already-existing) lead id. */ leadId: string; /** `true` when a new row was inserted, `false` when an existing row was touched. */ created: boolean; } export function hashIp(ip: string | null | undefined): string | null { if (!ip) return null; return createHash("sha256").update(ip).digest("hex").slice(0, 32); } export async function captureLead(input: CaptureLeadInput): Promise { const email = input.email.trim().toLowerCase(); const ipHash = hashIp(input.ip); const ua = input.userAgent ? input.userAgent.slice(0, 500) : null; const attr = input.attribution ?? {}; return captureMarketingLeadCapability({ email, firstName: trim(input.firstName), lastName: trim(input.lastName), phone: trim(input.phone), company: trim(input.company), source: trim(input.source), utmSource: trim(attr.utmSource), utmMedium: trim(attr.utmMedium), utmCampaign: trim(attr.utmCampaign), utmTerm: trim(attr.utmTerm), utmContent: trim(attr.utmContent), gclid: trim(attr.gclid), fbclid: trim(attr.fbclid), referrer: trim(attr.referrer), landingPage: trim(attr.landingPage), lastIpHash: ipHash, userAgent: ua, eventPayload: serialisePayload({ source: trim(input.source), attribution: cleanAttribution(attr), }), }); } function trim(v: string | null | undefined): string | null { if (v === null || v === undefined) return null; const t = String(v).trim(); return t === "" ? null : t; } function cleanAttribution(attr: NonNullable): Record { const out: Record = {}; for (const [k, v] of Object.entries(attr)) { const t = trim(v ?? null); if (t) out[k] = t; } return out; } function serialisePayload(obj: Record): Record { // Drop top-level keys with empty / undefined values for compact JSON storage. const out: Record = {}; for (const [k, v] of Object.entries(obj)) { if (v === null || v === undefined) continue; if (typeof v === "object" && Object.keys(v as Record).length === 0) continue; out[k] = v; } return out; }