Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/web/app/utils/leads/captureLead.server.ts
T

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;
}