/** * `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 type { Prisma } from "@hivegrid/db/prisma-browser"; import { db } from "~/utils/db.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 ?? {}; const existing = await db.lead.findUnique({ where: { email }, select: { id: true } }); if (!existing) { const lead = await db.lead.create({ data: { 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, events: { create: { type: "captured", payload: serialisePayload({ source: trim(input.source), attribution: cleanAttribution(attr), }), }, }, }, select: { id: true }, }); return { leadId: lead.id, created: true }; } // Existing — only fill blanks, never overwrite. First-touch attribution wins. const updateData: Prisma.LeadUpdateInput = { lastTouchAt: new Date(), lastIpHash: ipHash, userAgent: ua, firstName: nonNullSetIfMissing(input.firstName), lastName: nonNullSetIfMissing(input.lastName), phone: nonNullSetIfMissing(input.phone), company: nonNullSetIfMissing(input.company), events: { create: { type: "re-captured", payload: serialisePayload({ source: trim(input.source), attribution: cleanAttribution(attr), }), }, }, }; // Only conditionally fill blanks — Prisma update treats `undefined` as // "leave alone", and `null` as "set to NULL" which we explicitly do NOT want. // We re-fetch the row only for fields that need conditional patching to // avoid extra reads; the merge logic happens in the next query batch. await db.lead.update({ where: { id: existing.id }, data: updateData }); // Best-effort fill-blanks: only touches columns where the existing value is // NULL and the incoming value is set. This is two queries in the dup-case // which keeps the common path simple. await fillBlankProfileFields(existing.id, input); return { leadId: existing.id, created: false }; } 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 nonNullSetIfMissing(_v: string | null | undefined): undefined { // Returning `undefined` so Prisma keeps the existing value untouched. // The fill-blanks step (`fillBlankProfileFields`) handles actual patches. return undefined; } async function fillBlankProfileFields(leadId: string, input: CaptureLeadInput): Promise { const row = await db.lead.findUnique({ where: { id: leadId }, select: { firstName: true, lastName: true, phone: true, company: true }, }); if (!row) return; const patch: Prisma.LeadUpdateInput = {}; if (row.firstName == null && trim(input.firstName)) patch.firstName = trim(input.firstName); if (row.lastName == null && trim(input.lastName)) patch.lastName = trim(input.lastName); if (row.phone == null && trim(input.phone)) patch.phone = trim(input.phone); if (row.company == null && trim(input.company)) patch.company = trim(input.company); if (Object.keys(patch).length === 0) return; await db.lead.update({ where: { id: leadId }, data: patch }); } 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): Prisma.InputJsonValue { // 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 as Prisma.InputJsonValue; }