create-ailk 0.18.0 → 0.19.1

package/templates/apps/api/src/services/lead-routing.ts

@@ -48,8 +48,16 @@
  * throws, never refuses the lead and never changes `routeLead`'s result: an
  * unstorable address or a failed step writes the lead with `personId: null`
  * and logs one bare line (`person-skipped` / `person-failed`, never the
- * email). `subscribe` and `callback` create no Person; the `email`, `local`
- * and `none` deliveries never reach `persistToDb`.
+ * email). The `email`, `local` and `none` deliveries never reach
+ * `persistToDb`.
+ *
+ * CONTACT AND LINKS (#8435 D5). A `submit` may carry `options.contact` (the
+ * magnet's tagged answers): `findOrCreatePerson` fills the Person's BLANK
+ * contact fields from it while the Person is uncurated, and the lead's own
+ * `payload` is unchanged. A `subscribe` and a `callback` with a storable email
+ * (a callback's is `payload.email`) now also resolve a Person and stamp its id
+ * as `personId`; a callback with no email makes no Person call and writes no
+ * `personId`. Every one of these steps is best-effort exactly like the lead's.
  *
  * CHECKOUT PLAN (#7877 D10). A spoke's checkout fulfilment posts one
  * `submit` with the Checkout Session id as its `Idempotency-Key`. When that
@@ -63,6 +71,24 @@
  * `routeLead`'s result, and logs one bare `checkout-plan` line — never the
  * offering, the email or the key. A lead that does not qualify makes no
  * Person call at all.
+ *
+ * SPOKE CHECKOUT MARKER (#8185 D2). The same predicate, plus "not relayed
+ * for a visitor" (`SourceMeta.relayed`), is evaluated once BEFORE the lead's
+ * create and stored as `Lead.spokeCheckout` — the hub's conclusion at write
+ * time, which `GET /v1/member/purchases` serves as a purchase
+ * (`lib/member-store.ts`). Written only in the submit create below, never by
+ * an update; an unmarked create carries no `spokeCheckout` key at all and
+ * relies on the column default. The plan rule above is unchanged: it still
+ * runs after the write, from the same candidate.
+ *
+ * VISITOR LINK (#8438 D11). When the request carried a valid consent visitor
+ * id (`SourceMeta.consentVisitorId`, set by the leads and flows routes from
+ * `x-ailk-consent-visitor` only when it is a v4 UUID) and the submit resolved
+ * a Person, `linkConsentVisitor` joins the two — source `magnet` for a
+ * `flow:` source, else `api`. A link never fails a lead and is never
+ * returned: `RouteLeadResult.personId` is internal, for the flow engine's
+ * consent write. A subscribe or callback resolves no Person, so it links
+ * nothing. The header is never echoed and never logged.
  */
 
 import { randomUUID } from "node:crypto";
@@ -82,8 +108,15 @@ import { appendLeadRecord } from "../lib/lead-capture-store.js";
 import { acceptsKind, resolveLeadDelivery } from "../lib/lead-delivery.js";
 import { prisma } from "../lib/prisma.js";
 
+import { linkConsentVisitor } from "./consent.js";
 import { enrichLead } from "./enrichment-shim.js";
-import { findOrCreatePerson, setPersonPlanOffering } from "./person.js";
+import {
+  findOrCreatePerson,
+  normalizeCapturedContact,
+  normalizeTelephone,
+  setPersonPlanOffering,
+} from "./person.js";
+import type { LeadContact, PersonContact } from "./person.js";
 import { requestConfirmSupersedesNotification } from "./request-confirm.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -117,6 +150,19 @@ export type SourceMeta = {
    * `false`. Never persisted — `captureRecordFor` copies fields by name.
    */
   viaSpoke?: boolean;
+  /**
+   * The request carried `x-ailk-relayed`, i.e. it was forwarded for a
+   * visitor by a spoke's same-origin relay (#8185 D3). Absent reads as
+   * `false`. Never persisted. It can only REMOVE the spoke-checkout marker,
+   * never grant it.
+   */
+  relayed?: boolean;
+  /**
+   * The cookie banner's visitor id from the request's `x-ailk-consent-visitor`
+   * header, set only when it is a v4 UUID (#8438 D11). Used to link the
+   * visitor to the lead's Person; never persisted, echoed or logged.
+   */
+  consentVisitorId?: string;
 };
 
 /** Where the lead landed: a database row, the local file fallback, or the owner's inbox by email (#6730). */
@@ -126,6 +172,12 @@ export type Persisted = "db" | "file" | "email";
 export type RouteLeadOptions = {
   /** The caller's validated `Idempotency-Key`; honoured for `submit` only. */
   idempotencyKey?: string;
+  /**
+   * The contact the capture offers (#8435 D5) — the magnet's tagged answers —
+   * honoured for `submit` only and never persisted as such: the lead's
+   * `payload` stays the raw answers.
+   */
+  contact?: LeadContact;
 };
 
 export type RouteLeadResult =
@@ -138,6 +190,12 @@ export type RouteLeadResult =
        */
       replayed?: true;
       id: string;
+      /**
+       * The Person a `submit` resolved (#8438 D11), `null`/absent when none.
+       * Internal only — the route builds its 201 body from `id`, `persisted`
+       * and `email`, so this never reaches a wire.
+       */
+      personId?: string | null;
       persisted: Persisted;
       email:
         | { ok: true; messageId: string }
@@ -240,6 +298,8 @@ type PersistResult =
       source: "db";
       skipEmail: boolean;
       skipReason?: string;
+      /** The Person a `submit` resolved (#8438 D11). */
+      personId?: string | null;
     }
   // #7869 D5 — a keyed create lost a race to a row it now answers with.
   | { ok: "keyed"; outcome: KeyedOutcome }
@@ -251,25 +311,41 @@ type PersistResult =
  * must never refuse, lose or delay a lead. Logs the outcome kind and the
  * site only.
  */
-async function resolveLeadPersonId(input: SubmitInput): Promise<string | null> {
+async function resolveCapturePersonId(
+  siteId: string,
+  capture: { email: string; name?: string | null; contact?: Partial<PersonContact> },
+): Promise<string | null> {
   try {
-    const name = typeof input.payload["name"] === "string" ? input.payload["name"] : null;
-    const person = await findOrCreatePerson(input.siteId, { email: input.email, name });
+    const person = await findOrCreatePerson(siteId, capture);
     if (person.ok) return person.value.personId;
     if (person.error.kind === "invalid_email") {
       logger.warn(
-        { event: "person-skipped", kind: person.error.kind, siteId: input.siteId },
+        { event: "person-skipped", kind: person.error.kind, siteId },
         "lead person skipped",
       );
     } else {
-      logger.error({ event: "person-failed", siteId: input.siteId }, "lead person failed");
+      logger.error({ event: "person-failed", siteId }, "lead person failed");
     }
   } catch {
-    logger.error({ event: "person-failed", siteId: input.siteId }, "lead person failed");
+    logger.error({ event: "person-failed", siteId }, "lead person failed");
   }
   return null;
 }
 
+async function resolveLeadPersonId(input: SubmitInput, contact?: LeadContact): Promise<string | null> {
+  const payloadName = typeof input.payload["name"] === "string" ? input.payload["name"] : null;
+  if (contact === undefined) {
+    return resolveCapturePersonId(input.siteId, { email: input.email, name: payloadName });
+  }
+  // #8435 D5 — an explicit contact name wins over the payload's.
+  const name = typeof contact.name === "string" ? contact.name : payloadName;
+  return resolveCapturePersonId(input.siteId, {
+    email: input.email,
+    name,
+    contact: normalizeCapturedContact(contact),
+  });
+}
+
 /** A LIVE-mode Checkout Session id (#7877 D10, SEC-7877-C). */
 const LIVE_CHECKOUT_SESSION_KEY = /^cs_live_[A-Za-z0-9]{1,250}$/;
 const SITE_SLUG = /^[a-z0-9][a-z0-9-]{0,39}$/;
@@ -340,9 +416,16 @@ async function persistToDb(
   input: RouteLeadInput,
   idempotencyKey?: string,
   viaSpoke = false,
+  relayed = false,
+  contact?: LeadContact,
 ): Promise<PersistResult> {
   if (input.kind === "submit") {
-    const personId = await resolveLeadPersonId(input);
+    const personId = await resolveLeadPersonId(input, contact);
+    // #8185 D2 — the plan rule's own predicate (pure: input, key, flag),
+    // evaluated before the create so its result can be stored. A relayed
+    // request is never a spoke's server call (D3).
+    const candidate = checkoutPlanCandidate(input, idempotencyKey, viaSpoke);
+    const spokeCheckout = candidate !== null && relayed !== true;
     let row: DbRow;
     try {
       row = (await prisma.lead.create({
@@ -371,6 +454,8 @@ async function persistToDb(
           // #852 D6 — the Person `resolveLeadPersonId` found or created.
           personId,
           ...(idempotencyKey !== undefined && { idempotencyKey }),
+          // #8185 D4 — only a marked create names the column.
+          ...(spokeCheckout && { spokeCheckout: true }),
         },
         select: { id: true },
       })) as DbRow;
@@ -386,14 +471,15 @@ async function persistToDb(
       return { ok: "keyed", outcome: classifyKeyedRow(winner, input) };
     }
     // #7877 D10 — only after THIS request's own write, so a replay sets nothing.
-    const candidate = checkoutPlanCandidate(input, idempotencyKey, viaSpoke);
     if (candidate !== null && personId !== null) {
       await applyCheckoutPlan(input, personId, candidate);
     }
-    return { ok: true, id: row.id, source: "db", skipEmail: false };
+    return { ok: true, id: row.id, source: "db", skipEmail: false, personId };
   }
 
   if (input.kind === "subscribe") {
+    // #8435 D5 — the subscriber's Person; `null` when the step skips or fails.
+    const personId = await resolveCapturePersonId(input.siteId, { email: input.email });
     try {
       const row = (await prisma.subscriber.create({
         data: {
@@ -407,6 +493,7 @@ async function persistToDb(
           workspaceId: input.siteId,
           email: input.email,
           source: input.source,
+          personId,
         },
         select: { id: true },
       })) as DbRow;
@@ -444,6 +531,18 @@ async function persistToDb(
   }
 
   // kind === "callback"
+  // #8435 D5 — a callback with a string `payload.email` resolves a Person; one
+  // without makes no call and writes no `personId`.
+  const callbackEmail = input.payload["email"];
+  const telephone = normalizeTelephone(input.phone);
+  const callbackPersonId =
+    typeof callbackEmail === "string"
+      ? await resolveCapturePersonId(input.siteId, {
+          email: callbackEmail,
+          name: input.name,
+          contact: telephone === null ? {} : { telephone },
+        })
+      : undefined;
   const row = (await prisma.callback.create({
     data: {
       siteId: input.siteId,
@@ -457,6 +556,7 @@ async function persistToDb(
         preferredTime: input.preferredTime,
       }),
       payload: input.payload as Prisma.InputJsonValue,
+      ...(callbackPersonId !== undefined && { personId: callbackPersonId }),
     },
     select: { id: true },
   })) as DbRow;
@@ -727,9 +827,16 @@ export async function routeLead(
   let persisted: Persisted;
   let skipEmail = false;
   let skipReason: string | undefined;
+  let personId: string | null = null;
 
   try {
-    const dbResult = await persistToDb(input, idempotencyKey, sourceMeta.viaSpoke === true);
+    const dbResult = await persistToDb(
+      input,
+      idempotencyKey,
+      sourceMeta.viaSpoke === true,
+      sourceMeta.relayed === true,
+      input.kind === "submit" ? options.contact : undefined,
+    );
     // #7869 D5 — a lost race answers like the lookup above: no capture
     // record, no notification.
     if (dbResult.ok === "keyed") return keyedResult(dbResult.outcome);
@@ -744,6 +851,20 @@ export async function routeLead(
     persisted = "db";
     skipEmail = dbResult.skipEmail;
     skipReason = dbResult.skipReason;
+    personId = dbResult.personId ?? null;
+    // #8438 D11 — only after THIS request's own write (a keyed replay
+    // returned above), and only when a Person was resolved.
+    if (sourceMeta.consentVisitorId !== undefined && personId !== null) {
+      await linkConsentVisitor({
+        workspaceId: input.siteId,
+        visitorId: sourceMeta.consentVisitorId,
+        personId,
+        source:
+          input.kind === "submit" && input.source.startsWith("flow:")
+            ? "magnet"
+            : "api",
+      });
+    }
   } catch (dbErr) {
     // #6254 AC-11 (spec D6, SEC-02) — a constraint violation is OUR OWN
     // derivation producing a row Postgres itself refuses (an unresolved
@@ -863,5 +984,5 @@ export async function routeLead(
     emailResult = await sendEmail(input, id!, persisted!, sourceMeta.viaSpoke);
   }
 
-  return { ok: true, id: id!, persisted, email: emailResult };
+  return { ok: true, id: id!, personId, persisted, email: emailResult };
 }