create-ailk 0.14.0 → 0.16.0

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

@@ -27,13 +27,55 @@
  * under it already contradicted it.) The one READ in this file — the
  * duplicate-subscriber lookup on the P2002 arm — is scoped by it too
  * (#6257).
+ *
+ * IDEMPOTENCY KEY (#7869, roadmap D5). A `submit` may carry a caller's
+ * `Idempotency-Key` (`routes/leads/index.ts` reads and validates the header;
+ * it travels beside the input as `routeLead`'s third argument, never inside
+ * the `.strict()` input). On `inbox` delivery only, a key already stored on a
+ * `Lead` of THIS workspace short-circuits the write: the same `email`,
+ * `source` and `payload` is a replay (the first lead's id, nothing written,
+ * no capture record, no notification); anything else is an
+ * `idempotency_conflict` (nothing written). The two reads — the lookup
+ * before the write and the re-read after a `P2002` race — are both keyed on
+ * `(workspaceId, idempotencyKey)`, so a key can never reach another tenant's
+ * row. `email`, `local` and `none` deliveries ignore the key: there is no
+ * row to dedupe against. The key itself is never logged.
+ *
+ * PERSON (#852 D6). Before a `submit` writes its `Lead`, `findOrCreatePerson`
+ * (`services/person.ts`, the only Person creator) resolves the client of
+ * this workspace for the lead's email, and its id joins the create as
+ * `personId`. Lead capture is a never-gate surface, so the Person step never
+ * 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`.
+ *
+ * CHECKOUT PLAN (#7877 D10). A spoke's checkout fulfilment posts one
+ * `submit` with the Checkout Session id as its `Idempotency-Key`. When that
+ * lead is written (never on a replay) with a Person, and it is a LIVE,
+ * paid checkout lead from a registered spoke's server — `viaSpoke`, a
+ * `cs_live_` key, `source: "web"`, `payload.page: "checkout"`, a string
+ * `payload.offering` and `payload.site`, and an `amountTotal` that is
+ * absent, `null` or a positive integer — the Person's plan becomes the
+ * offering minus a leading `<site>_` (`setPersonPlanOffering`, the plan's
+ * only writer). No spoke file changes. The step never throws, never changes
+ * `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.
  */
 
 import { randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
 
 import type { Prisma } from "@working-theory/database";
 import { sendLeadNotification } from "@working-theory/email";
-import { leadInputSchema } from "@working-theory/validation";
+import { logger } from "@working-theory/observability";
+import {
+  LEAD_SITE_MARKER_KEY,
+  leadInputSchema,
+  planOfferingSchema,
+} from "@working-theory/validation";
 
 import { writeLeadFallback } from "../lib/file-fallback.js";
 import { appendLeadRecord } from "../lib/lead-capture-store.js";
@@ -41,6 +83,7 @@ import { acceptsKind, resolveLeadDelivery } from "../lib/lead-delivery.js";
 import { prisma } from "../lib/prisma.js";
 
 import { enrichLead } from "./enrichment-shim.js";
+import { findOrCreatePerson, setPersonPlanOffering } from "./person.js";
 import { requestConfirmSupersedesNotification } from "./request-confirm.js";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -79,9 +122,21 @@ export type SourceMeta = {
 /** Where the lead landed: a database row, the local file fallback, or the owner's inbox by email (#6730). */
 export type Persisted = "db" | "file" | "email";
 
+/** Per-call options carried beside the input (#7869 D2). */
+export type RouteLeadOptions = {
+  /** The caller's validated `Idempotency-Key`; honoured for `submit` only. */
+  idempotencyKey?: string;
+};
+
 export type RouteLeadResult =
   | {
       ok: true;
+      /**
+       * The answer to a repeat of an already-stored idempotency key (#7869
+       * D4): nothing was written. Never on the wire — the route builds its
+       * 201 body from `id`, `persisted` and `email` only.
+       */
+      replayed?: true;
       id: string;
       persisted: Persisted;
       email:
@@ -96,7 +151,8 @@ export type RouteLeadResult =
           | "invalid_input"
           | "persist_failed"
           | "config_missing"
-          | "delivery_failed";
+          | "delivery_failed"
+          | "idempotency_conflict";
         message: string;
       };
     };
@@ -116,6 +172,64 @@ function validateInput(
   return { ok: true };
 }
 
+// ─── Idempotency key (#7869) ─────────────────────────────────────────────────
+
+type SubmitInput = Extract<RouteLeadInput, { kind: "submit" }>;
+type KeyedRow = { id: string; email: string; source: string; payload: unknown };
+/** What a stored key means for this request (#7869 D4). */
+type KeyedOutcome = { kind: "replay"; id: string } | { kind: "conflict" };
+
+/**
+ * The one read of `Lead.idempotencyKey` (#7869 D3, reused by D5's re-read).
+ * The compound unique carries `workspaceId`, so the lookup can only ever
+ * reach this workspace's rows.
+ */
+async function findLeadByKey(
+  workspaceId: string,
+  idempotencyKey: string,
+): Promise<KeyedRow | null> {
+  return (await prisma.lead.findUnique({
+    where: { workspaceId_idempotencyKey: { workspaceId, idempotencyKey } },
+    select: { id: true, email: true, source: true, payload: true },
+  })) as KeyedRow | null;
+}
+
+/**
+ * A stored row is a replay only when it carries this request's exact `email`
+ * and `source` and a deep-equal `payload` (key order ignored, SEC-7869-3);
+ * any other row is a conflict (#7869 D4).
+ */
+function classifyKeyedRow(row: KeyedRow, input: SubmitInput): KeyedOutcome {
+  return row.email === input.email &&
+    row.source === input.source &&
+    isDeepStrictEqual(row.payload, input.payload)
+    ? { kind: "replay", id: row.id }
+    : { kind: "conflict" };
+}
+
+function keyedResult(outcome: KeyedOutcome): RouteLeadResult {
+  if (outcome.kind === "conflict") {
+    return {
+      ok: false,
+      error: { kind: "idempotency_conflict", message: "idempotency key reused" },
+    };
+  }
+  return {
+    ok: true,
+    replayed: true,
+    id: outcome.id,
+    persisted: "db",
+    email: { skipped: true, reason: "idempotent_replay" },
+  };
+}
+
+/** The structural `P2002` test `recommender-capture.ts` already uses. */
+function isUniqueViolation(err: unknown): boolean {
+  return (
+    typeof err === "object" && err !== null && (err as { code?: unknown }).code === "P2002"
+  );
+}
+
 // ─── DB persist ───────────────────────────────────────────────────────────────
 
 type DbRow = { id: string };
@@ -127,36 +241,155 @@ type PersistResult =
       skipEmail: boolean;
       skipReason?: string;
     }
+  // #7869 D5 — a keyed create lost a race to a row it now answers with.
+  | { ok: "keyed"; outcome: KeyedOutcome }
   | { ok: false; error: string };
 
-async function persistToDb(input: RouteLeadInput): Promise<PersistResult> {
+/**
+ * The Person of a submitted lead (#852 D6) — its id, or `null` when the email
+ * is not a storable address or the step failed. Never throws: a Person step
+ * must never refuse, lose or delay a lead. Logs the outcome kind and the
+ * site only.
+ */
+async function resolveLeadPersonId(input: SubmitInput): 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 });
+    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 },
+        "lead person skipped",
+      );
+    } else {
+      logger.error({ event: "person-failed", siteId: input.siteId }, "lead person failed");
+    }
+  } catch {
+    logger.error({ event: "person-failed", siteId: input.siteId }, "lead person failed");
+  }
+  return null;
+}
+
+/** 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}$/;
+
+/**
+ * The raw offering of a lead that qualifies for the checkout plan rule, or
+ * `null` when it does not (#7877 D10). Reads the lead's own fields only.
+ */
+function checkoutPlanCandidate(
+  input: SubmitInput,
+  idempotencyKey: string | undefined,
+  viaSpoke: boolean,
+): { offering: string; site: string } | null {
+  if (viaSpoke !== true) return null;
+  if (idempotencyKey === undefined || !LIVE_CHECKOUT_SESSION_KEY.test(idempotencyKey)) {
+    return null;
+  }
+  const { payload } = input;
+  const amountTotal = payload["amountTotal"];
+  if (
+    amountTotal !== undefined &&
+    amountTotal !== null &&
+    !(typeof amountTotal === "number" && Number.isInteger(amountTotal) && amountTotal > 0)
+  ) {
+    return null;
+  }
+  if (input.source !== "web" || payload["page"] !== "checkout") return null;
+  const offering = payload["offering"];
+  const site = payload[LEAD_SITE_MARKER_KEY];
+  if (typeof offering !== "string" || typeof site !== "string" || !SITE_SLUG.test(site)) {
+    return null;
+  }
+  return { offering, site };
+}
+
+/**
+ * Set the Person's plan from a qualifying checkout lead (#7877 D10). Never
+ * throws and never changes the lead's result; logs the outcome kind and the
+ * site only.
+ */
+async function applyCheckoutPlan(
+  input: SubmitInput,
+  personId: string,
+  candidate: { offering: string; site: string },
+): Promise<void> {
+  const prefix = `${candidate.site}_`;
+  const offering = candidate.offering.startsWith(prefix)
+    ? candidate.offering.slice(prefix.length)
+    : candidate.offering;
+  let outcome: "set" | "skipped" | "failed";
+  // The operator's PUT accepts the same keys (`planOfferingSchema`).
+  if (!planOfferingSchema.safeParse(offering).success) {
+    outcome = "skipped";
+  } else {
+    try {
+      const result = await setPersonPlanOffering(input.siteId, personId, offering);
+      outcome = result === "set" ? "set" : "failed";
+    } catch {
+      outcome = "failed";
+    }
+  }
+  const line = { event: "checkout-plan", outcome, siteId: input.siteId };
+  if (outcome === "failed") logger.error(line, "checkout plan failed");
+  else logger.info(line, "checkout plan");
+}
+
+async function persistToDb(
+  input: RouteLeadInput,
+  idempotencyKey?: string,
+  viaSpoke = false,
+): Promise<PersistResult> {
   if (input.kind === "submit") {
-    const row = (await prisma.lead.create({
-      data: {
-        siteId: input.siteId,
-        // #6203/#6254 — the isolation key, equal to `siteId` by
-        // construction. `input.siteId` is the RESOLVED workspace id at
-        // EVERY `routeLead(kind: "submit")` caller now — the primary route
-        // (`routes/leads/index.ts`, never reads it from the body — see that
-        // file's header) and the three service-layer callers
-        // (`flow-engine.ts`'s `completeSubmission`,
-        // `recommender-capture.ts`'s `captureRecommenderChoice`,
-        // `project-listings.ts`'s `submitProjectListingDraft`) all resolve
-        // the site alias before calling in (#6254 AC-6/AC-10). `workspaceId`
-        // is NOT NULL as of
-        // database/migrations/20260922120000_tenancy_fence, so this can no
-        // longer stamp `null` for an unresolved alias the way it once did
-        // (spec D2's old rule) — a caller that somehow still passed one
-        // would instead hit the pre-existing `<table>_workspace_id_format`
-        // CHECK loudly, via the AC-11 re-raise below, rather than landing a
-        // silently-unfenced row.
-        workspaceId: input.siteId,
-        source: input.source,
-        email: input.email,
-        payload: input.payload as Prisma.InputJsonValue,
-      },
-      select: { id: true },
-    })) as DbRow;
+    const personId = await resolveLeadPersonId(input);
+    let row: DbRow;
+    try {
+      row = (await prisma.lead.create({
+        data: {
+          siteId: input.siteId,
+          // #6203/#6254 — the isolation key, equal to `siteId` by
+          // construction. `input.siteId` is the RESOLVED workspace id at
+          // EVERY `routeLead(kind: "submit")` caller now — the primary route
+          // (`routes/leads/index.ts`, never reads it from the body — see that
+          // file's header) and the three service-layer callers
+          // (`flow-engine.ts`'s `completeSubmission`,
+          // `recommender-capture.ts`'s `captureRecommenderChoice`,
+          // `project-listings.ts`'s `submitProjectListingDraft`) all resolve
+          // the site alias before calling in (#6254 AC-6/AC-10). `workspaceId`
+          // is NOT NULL as of
+          // database/migrations/20260922120000_tenancy_fence, so this can no
+          // longer stamp `null` for an unresolved alias the way it once did
+          // (spec D2's old rule) — a caller that somehow still passed one
+          // would instead hit the pre-existing `<table>_workspace_id_format`
+          // CHECK loudly, via the AC-11 re-raise below, rather than landing a
+          // silently-unfenced row.
+          workspaceId: input.siteId,
+          source: input.source,
+          email: input.email,
+          payload: input.payload as Prisma.InputJsonValue,
+          // #852 D6 — the Person `resolveLeadPersonId` found or created.
+          personId,
+          ...(idempotencyKey !== undefined && { idempotencyKey }),
+        },
+        select: { id: true },
+      })) as DbRow;
+    } catch (err) {
+      // #7869 D5 — two keyed requests both missed the lookup and both
+      // created; the unique index refused the second. Answer with the
+      // winner. Anything else — no key, another error, a winner that cannot
+      // be read back — is rethrown untouched, so `routeLead`'s existing
+      // constraint and outage handling decide it exactly as before.
+      if (idempotencyKey === undefined || !isUniqueViolation(err)) throw err;
+      const winner = await findLeadByKey(input.siteId, idempotencyKey).catch(() => null);
+      if (!winner) throw err;
+      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 };
   }
 
@@ -426,6 +659,7 @@ function captureRecordFor(input: RouteLeadInput, id: string, sourceMeta: SourceM
 export async function routeLead(
   input: RouteLeadInput,
   sourceMeta: SourceMeta,
+  options: RouteLeadOptions = {},
 ): Promise<RouteLeadResult> {
   // 1. Validate
   const validation = validateInput(input);
@@ -452,6 +686,17 @@ export async function routeLead(
     };
   }
 
+  // 2a. Idempotency key (#7869 D3/D7) — submit, a key, and a database to
+  // dedupe against. A stored key answers before any enrichment or write. A
+  // failed read is not an answer: the create below meets the same database
+  // and takes the existing outage path.
+  const idempotencyKey =
+    input.kind === "submit" && delivery === "inbox" ? options.idempotencyKey : undefined;
+  if (idempotencyKey !== undefined && input.kind === "submit") {
+    const stored = await findLeadByKey(input.siteId, idempotencyKey).catch(() => null);
+    if (stored) return keyedResult(classifyKeyedRow(stored, input));
+  }
+
   // 3. Enrich (reserved for Phase 3 — today returns lead unchanged).
   // Cast via unknown: enrichLead accepts CreateLead (B3 shim type) but the
   // pass-through contract means RouteLeadInput is safe here until Phase 3 wires
@@ -484,7 +729,10 @@ export async function routeLead(
   let skipReason: string | undefined;
 
   try {
-    const dbResult = await persistToDb(input);
+    const dbResult = await persistToDb(input, idempotencyKey, sourceMeta.viaSpoke === true);
+    // #7869 D5 — a lost race answers like the lookup above: no capture
+    // record, no notification.
+    if (dbResult.ok === "keyed") return keyedResult(dbResult.outcome);
     if (!dbResult.ok) {
       // persistToDb returned ok:false — defensive guard; current impl doesn't reach this
       return {