create-ailk 0.21.0 → 0.22.0

package/templates/apps/api/src/routes/leads/index.ts

@@ -57,6 +57,47 @@
  * file leaves nothing to find, and its retry writes again. `subscribe` and
  * `callback` never read the header. The key is never logged or echoed.
  *
+ * CONTACT TERMS ACCEPTANCE (#8730). A `submit` whose `source` is a contact
+ * source (`isContactLeadSource` in @working-theory/validation:
+ * `contact-form`, `conversational-intake`, `flow:contact`) must carry a
+ * top-level `consent: true` — the boolean, nothing else — or it is
+ * `400 consent_required` before the tenant read or any write. An accepted one
+ * gets `payload.consent = { statement, acceptedAt }` written HERE, replacing
+ * any `payload.consent` the client sent: `statement` is the platform's
+ * contact terms statement (`CONTACT_FORM_TERMS_STATEMENT`) and `acceptedAt`
+ * this request's receive time. The `consent` flag itself is never stored. A
+ * lead with any other source, `subscribe` and `callback` are unchanged. A
+ * direct caller can still send `consent: true`; the gate makes acceptance an
+ * explicit, recorded assertion, not proof that a person read the terms.
+ *
+ * API↔MCP PARITY for `consent` (#8730): no guard entry, for the reason the
+ * Idempotency-Key paragraph below gives — this route parses no validation
+ * export, so it binds as `api-args-unbound`. `capture_lead` stamps `mcp`, a
+ * source this check never reads, so the tool is unchanged.
+ *
+ * A MAGNET'S COMPLETION (#8757 D6). After a `flow:<slug>` submit is written
+ * to the database, `services/magnet-completion.ts` reads that LIVE magnet's
+ * completion setting. On `invite` the 201 gains `next: { completion:
+ * "invite" }` and — on a first write, never a replay — the submitter is sent
+ * one confirmation email whose link starts sign-in with their address
+ * prefilled (capped per recipient and per magnet, counted in the database);
+ * on `checkout`, re-checked against the `commerce` claim and the published
+ * offerings, it gains `next: { completion: "checkout", checkoutOffering }`.
+ * `lead`, a draft or missing magnet, or a caller with nowhere to sign in
+ * leaves the 201 as it was. A failed read or send never changes the 201,
+ * and the completion read has a time budget (`MAGNET_COMPLETION_BUDGET_MS`).
+ * `next` is reachable only through a `flow:` source: `capture_lead` posts
+ * `source: "mcp"`, so the tool's arguments get the same answer as before and
+ * no parity guard row changes (NFR5).
+ *
+ * A CHECKOUT'S ACCOUNT LINK (#8757 D14). A checkout fulfilment's submit
+ * (`source: "web"`, `payload.page: "checkout"`) carries the caller's account
+ * origin into `routeLead` as `accountOrigin`, resolved exactly as the invite
+ * link's (`accountTargetFor`): the spoke's enabled sign-in client's callback
+ * origin, or `FRONTEND_URL`'s on a keyless build with an account area. With
+ * none, or a failed read, it is left out and the buyer's purchase email goes
+ * without the link. No other submit makes this read, and the 201 is unchanged.
+ *
  * API↔MCP PARITY for the header (#7869 D9, roadmap §12 Q5): NO guard entry.
  * The guard binds a route's arguments to the validation export its handler
  * `.safeParse`s on `request.params|query|body`; the header check below is a
@@ -67,6 +108,11 @@
  */
 
 import { track } from "@working-theory/analytics/server";
+import {
+  CONTACT_FORM_TERMS_STATEMENT,
+  isContactLeadSource,
+  type LeadSubmitNext,
+} from "@working-theory/validation";
 import type { FastifyPluginAsync } from "fastify";
 
 import { acceptsKind, resolveLeadDelivery } from "../../lib/lead-delivery.js";
@@ -81,6 +127,11 @@ import {
   routeLead,
   type SourceMeta,
 } from "../../services/lead-routing.js";
+import {
+  accountTargetFor,
+  magnetCompletionWithinBudget,
+  sendInviteConfirmation,
+} from "../../services/magnet-completion.js";
 import { resolveCallerSite } from "../../services/public-site-resolver.js";
 import { sendRequestConfirmLink } from "../../services/request-confirm.js";
 
@@ -105,6 +156,28 @@ function liftString(
   return (typeof fromPayload === "string" ? fromPayload : topLevel) as string;
 }
 
+/** #8730 — the refusal a contact lead without terms acceptance gets. */
+const CONSENT_REQUIRED_BODY = {
+  error: "consent_required",
+  message: "Accept the terms to send a contact message.",
+} as const;
+
+/**
+ * #8730 D3 — the accepted terms, recorded by the server on a contact lead's
+ * payload, replacing any `consent` the client wrote there. Only a plain
+ * object payload is stamped: anything else is left for `routeLead`'s schema
+ * to refuse, never spread into an object that would then pass it.
+ */
+function withConsentRecord(payload: unknown, acceptedAt: string): unknown {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return payload;
+  }
+  return {
+    ...(payload as Record<string, unknown>),
+    consent: { statement: CONTACT_FORM_TERMS_STATEMENT, acceptedAt },
+  };
+}
+
 /**
  * Build a typed RouteLeadInput from the raw request body for a given kind.
  * Explicit destructure per kind prevents unknown fields (e.g. attacker-supplied
@@ -122,6 +195,7 @@ function buildInput(
   kind: LeadKind,
   body: Record<string, unknown>,
   workspaceId: string,
+  receivedAt: string,
 ): RouteLeadInput {
   const payload = (body["payload"] ?? {}) as Record<string, unknown>;
 
@@ -131,7 +205,9 @@ function buildInput(
       siteId: workspaceId,
       source: body["source"] as string,
       email: liftString(body, payload, "email"),
-      payload,
+      payload: isContactLeadSource(body["source"])
+        ? (withConsentRecord(payload, receivedAt) as Record<string, unknown>)
+        : payload,
     };
   }
   if (kind === "subscribe") {
@@ -154,10 +230,31 @@ function buildInput(
   };
 }
 
+/** A spoke checkout fulfilment's submit (#8757 D14): `source: "web"`, `payload.page: "checkout"`. */
+function isCheckoutSubmit(body: Record<string, unknown>): boolean {
+  const payload = body["payload"];
+  return (
+    body["source"] === "web" &&
+    typeof payload === "object" &&
+    payload !== null &&
+    (payload as Record<string, unknown>)["page"] === "checkout"
+  );
+}
+
 function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
   return async (fastify) => {
     fastify.post(`/v1/leads/${kind}`, async (request, reply) => {
       const body = request.body as Record<string, unknown>;
+
+      // #8730 D1 — a contact lead carries the visitor's terms acceptance, or
+      // it is refused before the tenant read and any write.
+      if (
+        kind === "submit" &&
+        isContactLeadSource(body?.["source"]) &&
+        body?.["consent"] !== true
+      ) {
+        return reply.status(400).send(CONSENT_REQUIRED_BODY);
+      }
       // request.ip became attacker-influenceable when trustProxy: true went
       // instance-wide (server.ts, #4730/#4778) — leads/index.ts was never
       // itself touched by that PR. Traced every consumer of this value
@@ -264,10 +361,20 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         sourceMeta.consentVisitorId = consentVisitorId;
       }
 
+      // #8757 D14 — where a buyer's account lives, for the purchase email.
+      let accountOrigin: string | undefined;
+      if (kind === "submit" && isCheckoutSubmit(body)) {
+        const target = await accountTargetFor(caller).catch(() => null);
+        accountOrigin = target?.origin;
+      }
+
       const result = await routeLead(
-        buildInput(kind, body, workspaceId),
+        buildInput(kind, body, workspaceId, sourceMeta.receivedAt),
         sourceMeta,
-        idempotencyKey === undefined ? {} : { idempotencyKey },
+        {
+          ...(idempotencyKey !== undefined && { idempotencyKey }),
+          ...(accountOrigin !== undefined && { accountOrigin }),
+        },
       );
 
       if (!result.ok) {
@@ -357,10 +464,12 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         result.persisted === "db" &&
         caller.kind !== "spoke"
       ) {
-        const callbackInput = buildInput(kind, body, workspaceId) as Extract<
-          RouteLeadInput,
-          { kind: "callback" }
-        >;
+        const callbackInput = buildInput(
+          kind,
+          body,
+          workspaceId,
+          sourceMeta.receivedAt,
+        ) as Extract<RouteLeadInput, { kind: "callback" }>;
         sendRequestConfirmLink(result.id, {
           name: callbackInput.name,
           phone: callbackInput.phone,
@@ -370,6 +479,50 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         });
       }
 
+      // #8757 D6 — a written `flow:<slug>` submit answers its magnet's
+      // completion. A read that fails, or outlasts its budget, leaves the 201
+      // as it was: the lead is saved.
+      let next: LeadSubmitNext | undefined;
+      const source = body["source"];
+      if (
+        kind === "submit" &&
+        result.persisted === "db" &&
+        typeof source === "string" &&
+        source.startsWith("flow:")
+      ) {
+        const slug = source.slice("flow:".length);
+        try {
+          const completion = await magnetCompletionWithinBudget(workspaceId, slug, () =>
+            accountTargetFor(caller),
+          );
+          if (completion !== null) {
+            next = completion.next;
+            if (completion.next.completion === "invite" && !result.replayed) {
+              const submitInput = buildInput(
+                kind,
+                body,
+                workspaceId,
+                sourceMeta.receivedAt,
+              ) as Extract<RouteLeadInput, { kind: "submit" }>;
+              const locale = submitInput.payload["locale"];
+              void sendInviteConfirmation({
+                workspaceId,
+                slug,
+                email: submitInput.email,
+                locale: typeof locale === "string" ? locale : undefined,
+                completion,
+                now: new Date(),
+              });
+            }
+          }
+        } catch (error) {
+          request.log.error(
+            { event: "magnet-completion", error: error instanceof Error ? error.name : "unknown" },
+            "lead magnet completion read failed",
+          );
+        }
+      }
+
       // Fire-and-forget: track() never throws; no need to hold the response.
       // #7869 D6 — a replay records nothing new: the first write counted it.
       if (!result.replayed) {
@@ -385,6 +538,7 @@ function makeLeadsRoute(kind: LeadKind): FastifyPluginAsync {
         id: result.id,
         persisted: result.persisted,
         email: result.email,
+        ...(next === undefined ? {} : { next }),
       });
     });
   };