112 lines
3.7 KiB
TypeScript
112 lines
3.7 KiB
TypeScript
/**
|
|
* `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<CaptureLeadResult> {
|
|
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<CaptureLeadInput["attribution"]>): Record<string, string> {
|
|
const out: Record<string, string> = {};
|
|
for (const [k, v] of Object.entries(attr)) {
|
|
const t = trim(v ?? null);
|
|
if (t) out[k] = t;
|
|
}
|
|
return out;
|
|
}
|
|
|
|
function serialisePayload(obj: Record<string, unknown>): Record<string, unknown> {
|
|
// Drop top-level keys with empty / undefined values for compact JSON storage.
|
|
const out: Record<string, unknown> = {};
|
|
for (const [k, v] of Object.entries(obj)) {
|
|
if (v === null || v === undefined) continue;
|
|
if (typeof v === "object" && Object.keys(v as Record<string, unknown>).length === 0) continue;
|
|
out[k] = v;
|
|
}
|
|
return out;
|
|
}
|