create-ailk 0.23.0 → 0.25.1

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

@@ -1,573 +0,0 @@
-/**
- * Leads route group.
- *
- * Routes:
- *   POST /v1/leads/submit    — lead submission (contact form / inquiry)
- *   POST /v1/leads/subscribe — newsletter subscription
- *   POST /v1/leads/callback  — callback request (phone-back)
- *   GET  /v1/leads/capture   — whether this deployment accepts a contact
- *                              message / a newsletter signup (#6730 D4)
- *
- * API↔MCP PARITY — `GET /v1/leads/capture` has NO MCP twin, a recorded
- * exception on the same footing as the anonymous form-lifecycle routes. It
- * exists so a web page can choose between the form and the contact email
- * before rendering; an agent never needs that preflight, because the three
- * write tools (`capture_lead`, `subscribe_newsletter`, `request_callback`)
- * already return a typed `api_error` carrying the 503 when capture is not
- * accepted — the same answer, at the moment it matters.
- *
- * TENANT RESOLUTION (#6203, spec §10.4 operator ruling — reverses this
- * file's former byte-unchanged posture). `siteId` used to be taken VERBATIM
- * from the request body (`body["siteId"] as string`) — an anonymous, no-
- * ownership-check value (`packages/validation/src/schemas/leads.ts`'s
- * `safeSiteIdString` permits a `wksp_<uuidv7>`-shaped literal). Every
- * capture kind now resolves its tenant SERVER-SIDE, via
- * `resolveSiteWorkspaceId()` (`lib/site.ts`) — the SAME alias -> workspace
- * resolution `currentSiteId()`/`AILK_SITE_ID` already drive throughout this
- * app, unconditional on the content adapter — and a client-posted `siteId`
- * is IGNORED entirely: it can no longer place a row anywhere. An unresolved
- * result (no DATABASE_URL, or the alias names no workspace this database
- * holds) is a 503 before any write is attempted — never a guess. See
- * `lead-routing.ts`'s own header for the persistence-side half.
- *
- * A REGISTERED SPOKE (#7532 D4) resolves FIRST: a hub serving several spokes
- * reads the spoke's key from `x-ailk-spoke-key` through
- * `resolveCallerSite()` (`services/public-site-resolver.ts`) and writes the
- * lead into that spoke's own workspace. A refused key — malformed, unknown or
- * revoked, or no key at all on a hub (a deployment whose spoke registry holds
- * a row, or one whose `AILK_HUB_REQUIRE_SPOKE_KEY` is `true`; #7633) — is the
- * same 503 `tenant_unresolved` before any write. A header-less request on a
- * deployment with no registered spoke, or under the emergency opt-out
- * (`AILK_HUB_REQUIRE_SPOKE_KEY=false`), takes the alias resolution above,
- * unchanged. So does a keyless request whose hub-status read fails before the
- * process has any answer: lead capture is never lost (#7633, conductor
- * amendment to NFR3). The body's `siteId` stays ignored on every branch.
- *
- * IDEMPOTENCY KEY (#7869, roadmap D5). `POST /v1/leads/submit` accepts an
- * optional `Idempotency-Key` header: 16 to 255 visible ASCII characters, and
- * it must be UNGUESSABLE (a UUID, a Stripe Checkout Session id) — a key is
- * first-write-wins inside its workspace, so a short or predictable one could
- * be claimed by someone else first (SEC-7869-1). It is checked after the
- * tenant gate and before `routeLead`; a malformed key is `400 invalid_input`
- * with no read or write. A repeat of a stored key in the same workspace with
- * the same `email`, `source` and `payload` answers the first lead's 201 and
- * writes nothing; with anything different it is `422
- * idempotency_key_reused`. The key dedupes only where a `Lead` row exists —
- * `inbox` delivery — so a first write that fell back to email or a local
- * 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
- * consent-bearing source (`isConsentLeadSource` in @working-theory/validation:
- * the contact sources `contact-form`, `conversational-intake`, `flow:contact`,
- * and since #9130 the Free apply page's `flow:job-application`) 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
- * regex test, not such a parse, so this route still binds as
- * `api-args-unbound` and the `capture_lead` row is unchanged. The 201 body's
- * field set is unchanged too, and `capture_lead` sends no header. If the
- * guard ever models headers, this becomes an API-side `arg-only-in`.
- */
-
-import { track } from "@working-theory/analytics/server";
-import {
-  CONTACT_FORM_TERMS_STATEMENT,
-  isConsentLeadSource,
-  type LeadSubmitNext,
-} from "@working-theory/validation";
-import type { FastifyPluginAsync } from "fastify";
-
-import { acceptsKind, resolveLeadDelivery } from "../../lib/lead-delivery.js";
-import { currentSiteId, resolveSiteWorkspaceId } from "../../lib/site.js";
-import {
-  CONSENT_VISITOR_HEADER,
-  consentVisitorFromHeader,
-} from "../../services/consent.js";
-import {
-  type LeadKind,
-  type RouteLeadInput,
-  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";
-
-/** #7869 D1 — 16 to 255 visible ASCII characters; no spaces, no list. */
-const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7E]{16,255}$/;
-
-/**
- * Read a named string field from the body, falling back to the same-named
- * field inside `body.payload` when the top-level value is absent — the
- * step-flow envelope (`{ siteId, source, payload: <record> }`) carries its
- * identity fields inside `payload` rather than at the top level. A top-level
- * value always wins.
- */
-function liftString(
-  body: Record<string, unknown>,
-  payload: Record<string, unknown>,
-  key: string,
-): string {
-  const topLevel = body[key];
-  if (typeof topLevel === "string") return topLevel;
-  const fromPayload = payload[key];
-  return (typeof fromPayload === "string" ? fromPayload : topLevel) as string;
-}
-
-/** #8730, #9130 — the refusal a consent-bearing lead without terms acceptance gets. */
-const CONSENT_REQUIRED_BODY = {
-  error: "consent_required",
-  message: "Accept the terms to send this form.",
-} as const;
-
-/**
- * #8730 D3, #9130 — the accepted terms, recorded by the server on a
- * consent-bearing 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
- * `id`) from reaching the service — the service's .strict() Zod schemas provide
- * a second layer, but we also keep the handler clean at the boundary. Lifting
- * `email`/`name`/`phone` out of `payload` (see liftString above) reads by
- * explicit field name only — it does not spread `payload`'s other keys, so
- * the same discipline holds. `payload` itself is passed through unchanged.
- *
- * `siteId` is the RESOLVED `workspaceId` (#6203) — never `body["siteId"]`.
- * A body-supplied `siteId` is read nowhere in this function; a client that
- * posts one has it silently ignored, never honoured.
- */
-function buildInput(
-  kind: LeadKind,
-  body: Record<string, unknown>,
-  workspaceId: string,
-  receivedAt: string,
-): RouteLeadInput {
-  const payload = (body["payload"] ?? {}) as Record<string, unknown>;
-
-  if (kind === "submit") {
-    return {
-      kind,
-      siteId: workspaceId,
-      source: body["source"] as string,
-      email: liftString(body, payload, "email"),
-      payload: isConsentLeadSource(body["source"])
-        ? (withConsentRecord(payload, receivedAt) as Record<string, unknown>)
-        : payload,
-    };
-  }
-  if (kind === "subscribe") {
-    return {
-      kind,
-      siteId: workspaceId,
-      email: liftString(body, payload, "email"),
-      source: body["source"] as string,
-    };
-  }
-  return {
-    kind,
-    siteId: workspaceId,
-    name: liftString(body, payload, "name"),
-    phone: liftString(body, payload, "phone"),
-    ...(body["preferredTime"] !== undefined && {
-      preferredTime: body["preferredTime"] as string,
-    }),
-    payload,
-  };
-}
-
-/** 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, #9130 — a contact lead or a job application carries the
-      // visitor's terms acceptance, or it is refused before the tenant read
-      // and any write.
-      if (
-        kind === "submit" &&
-        isConsentLeadSource(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
-      // (#5112, DEF-004): lead-routing.ts's structured log field and its
-      // opt-in (LEAD_CAPTURE_INCLUDE_IP) persisted metadata.ip both RECORD
-      // the value; neither branches routing, persistence, or dedup on it.
-      // The best-effort/record-only posture is judged sufficient — the same
-      // trade-off server.ts's own trustProxy comment already accepts. The
-      // private @working-theory/lead-routing package (not present in this
-      // repo, not inspectable) is the one consumer this trace could not
-      // complete; see docs/specs/5112-leads-ip-trace-spec.md §8.
-      const sourceMeta: SourceMeta = {
-        ip: request.ip,
-        userAgent: request.headers["user-agent"],
-        receivedAt: new Date().toISOString(),
-      };
-
-      // #7532 D4 — a registered spoke resolves first, to its own workspace; a
-      // refused key never falls through to the alias below. A keyless lead
-      // whose hub-status read fails on a cold start proceeds as on a non-hub,
-      // so routeLead's outage fallback captures it (#7633 amendment).
-      const caller = await resolveCallerSite(request, {
-        keylessOnRegistryFailure: "anonymous",
-      });
-      if (caller.kind === "refused") {
-        return reply.status(503).send({
-          error: "tenant_unresolved",
-          message: "This site is not configured to accept submissions.",
-        });
-      }
-
-      // #6203 — resolve the tenant SERVER-SIDE before any write is
-      // attempted. Two branches, deliberately different:
-      //
-      //  - No DATABASE_URL: the zero-config OSS file-fallback deployment.
-      //    There is no `workspaces` table to resolve against (and
-      //    `assertSiteAliasResolves()` already skips its own boot check for
-      //    exactly this reason), so the "resolved" value here is the site
-      //    ALIAS itself (`currentSiteId()`) — the same value the file
-      //    fallback would have carried before this unit. Never a rejection:
-      //    that would break lead capture for every zero-config scaffold.
-      //  - DATABASE_URL set: resolve via `resolveSiteWorkspaceId()`, the
-      //    SAME alias -> workspace resolution `currentSiteId()` already
-      //    drives everywhere else in this app. `null` here is a genuine
-      //    misconfiguration `build()` already refuses to boot past
-      //    (`assertSiteAliasResolves()`) — reaching it at request time is
-      //    the residual case that startup check cannot catch (a workspace
-      //    deleted after boot, a transient read), and it fails closed the
-      //    same way: reject, never guess (spec AC-4).
-      let workspaceId: string;
-      if (caller.kind === "spoke") {
-        workspaceId = caller.workspaceId;
-        sourceMeta.viaSpoke = true;
-      } else if (!process.env.DATABASE_URL) {
-        workspaceId = currentSiteId();
-      } else {
-        const resolved = await resolveSiteWorkspaceId();
-        if (resolved === null) {
-          request.log.error(
-            { kind },
-            "lead capture: DATABASE_URL is set but the site alias resolves to no workspace",
-          );
-          return reply.status(503).send({
-            error: "tenant_unresolved",
-            message: "This site is not configured to accept submissions.",
-          });
-        }
-        workspaceId = resolved;
-      }
-
-      // #7869 D1 — after the tenant gate, before any read or write. Node
-      // lower-cases header names, and joins a duplicated header with ", ",
-      // which the pattern refuses.
-      let idempotencyKey: string | undefined;
-      if (kind === "submit") {
-        const rawKey = request.headers["idempotency-key"];
-        if (rawKey !== undefined) {
-          if (
-            typeof rawKey !== "string" ||
-            !IDEMPOTENCY_KEY_PATTERN.test(rawKey)
-          ) {
-            return reply.status(400).send({
-              error: "invalid_input",
-              message:
-                "Idempotency-Key must be 16 to 255 visible ASCII characters.",
-            });
-          }
-          idempotencyKey = rawKey;
-        }
-      }
-
-      // #8185 D3 — a spoke's same-origin relay marks every forwarded call.
-      // The mark can only remove the spoke-checkout marker, never grant it.
-      sourceMeta.relayed = request.headers["x-ailk-relayed"] !== undefined;
-
-      // #8438 D11 — the cookie banner's visitor id, forwarded by the site's
-      // own server from its first-party cookie. Only a v4 UUID counts; the
-      // header is never echoed or logged. It links the visitor to the
-      // lead's Person after the write, and changes nothing about the answer.
-      const consentVisitorId = consentVisitorFromHeader(
-        request.headers[CONSENT_VISITOR_HEADER],
-      );
-      if (consentVisitorId !== undefined) {
-        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, sourceMeta.receivedAt),
-        sourceMeta,
-        {
-          ...(idempotencyKey !== undefined && { idempotencyKey }),
-          ...(accountOrigin !== undefined && { accountOrigin }),
-        },
-      );
-
-      if (!result.ok) {
-        if (result.error.kind === "idempotency_conflict") {
-          // #7869 D6 — the operator's signal that a keyed lead was refused.
-          // Never the key, the email or the payload.
-          request.log.warn(
-            { kind, siteId: workspaceId, outcome: "idempotency_conflict" },
-            "lead idempotency_conflict",
-          );
-          return reply.status(422).send({
-            error: "idempotency_key_reused",
-            message: "This Idempotency-Key was used for a different lead.",
-          });
-        }
-        if (result.error.kind === "invalid_input") {
-          return reply
-            .status(400)
-            .send({ error: "invalid_input", message: result.error.message });
-        }
-        if (result.error.kind === "persist_failed") {
-          // Do not surface internal error detail — log it server-side only
-          request.log.error(
-            { kind, siteId: workspaceId, error: result.error.message },
-            "lead persist_failed",
-          );
-          return reply.status(503).send({ error: "persist_failed" });
-        }
-        if (result.error.kind === "delivery_failed") {
-          // Email was the delivery and the provider did not accept it —
-          // never reported as sent (#6730 D5). Detail stays server-side.
-          // `{ kind, siteId }` only (spec D5): provider error text can echo
-          // an address.
-          request.log.error({ kind, siteId: workspaceId }, "lead delivery_failed");
-          return reply.status(503).send({
-            error: "delivery_failed",
-            message: "The message could not be delivered.",
-          });
-        }
-        // config_missing — this deployment has nowhere to put this kind of
-        // lead (#6730 D1: production with neither a database nor the email
-        // vars, or a newsletter signup with no database).
-        return reply.status(503).send({
-          error: "lead_capture_not_configured",
-          message: "Lead capture is not configured.",
-        });
-      }
-
-      // PII-safe structured log: only routing metadata, no email/phone/name/payload
-      const emailKind =
-        "skipped" in result.email
-          ? "skipped"
-          : result.email.ok
-            ? "ok"
-            : "error";
-      request.log.info(
-        {
-          siteId: workspaceId,
-          kind,
-          ip: sourceMeta.ip,
-          persisted: result.persisted,
-          emailKind,
-          replayed: result.replayed === true,
-        },
-        "lead routed",
-      );
-
-      // Request-and-confirm (#5970): mint the tenant's one-time confirm
-      // credential and email them the link. Fire-and-forget and `void`-
-      // returning, so the 201 below stays independent of both Resend and that
-      // write — the request is already persisted by this point, and a send
-      // that fails must never turn a captured lead into an error.
-      //
-      // Callback only: `submit` and `subscribe` have no confirm step. The
-      // service itself no-ops (with a logged reason) when the feature is not
-      // configured, which is the default.
-      // `result.persisted === "db"` for the same reason `lead-routing.ts`
-      // consults it (#5970 security review round 3, M1): the credential is
-      // minted by an update on the `callbacks` row, so a FILE-FALLBACK id
-      // would match nothing and the operator would be left with no email at
-      // all. On that path the generic notification is sent instead, which is
-      // what keeps "exactly one" true in both directions.
-      // A spoke's callback never takes this path (#7532 D4, SEC-7532-2): the
-      // link is minted on the deployment's one Stripe account.
-      if (
-        kind === "callback" &&
-        result.persisted === "db" &&
-        caller.kind !== "spoke"
-      ) {
-        const callbackInput = buildInput(
-          kind,
-          body,
-          workspaceId,
-          sourceMeta.receivedAt,
-        ) as Extract<RouteLeadInput, { kind: "callback" }>;
-        sendRequestConfirmLink(result.id, {
-          name: callbackInput.name,
-          phone: callbackInput.phone,
-          ...(callbackInput.preferredTime !== undefined && {
-            preferredTime: callbackInput.preferredTime,
-          }),
-        });
-      }
-
-      // #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) {
-        void track("lead-captured", {
-          source: body["source"] as string | undefined,
-          locale: (body["payload"] as Record<string, unknown> | undefined)?.[
-            "locale"
-          ] as string | undefined,
-        });
-      }
-
-      return reply.status(201).send({
-        id: result.id,
-        persisted: result.persisted,
-        email: result.email,
-        ...(next === undefined ? {} : { next }),
-      });
-    });
-  };
-}
-
-export const leadSubmitRoute = makeLeadsRoute("submit");
-export const leadSubscribeRoute = makeLeadsRoute("subscribe");
-export const leadCallbackRoute = makeLeadsRoute("callback");
-
-/**
- * `GET /v1/leads/capture` (#6730 D4) — two booleans and nothing else: never
- * an address or which env var is missing. (The pair implies as much of the
- * delivery mode as the rendered page already shows.) Registered at
- * the top level in `server.ts`, outside `leadsScope`'s strict per-IP limit
- * (a web server's single egress IP already spends that on form submissions),
- * so only the server-wide unauthenticated ceiling applies.
- */
-export const leadCaptureStatusRoute: FastifyPluginAsync = async (fastify) => {
-  fastify.get("/v1/leads/capture", async (_request, reply) => {
-    const delivery = resolveLeadDelivery();
-    return reply.header("Cache-Control", "public, max-age=60").send({
-      ok: true,
-      data: {
-        contact: acceptsKind(delivery, "submit"),
-        newsletter: acceptsKind(delivery, "subscribe"),
-      },
-    });
-  });
-};

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

@@ -1,104 +0,0 @@
-/**
- * The leads INBOX read (#5678).
- *
- * Routes:
- *   GET /v1/leads?cursor=&limit=  — the caller's own sites' leads, newest first
- *
- * Registered INSIDE `server.ts`'s `authScope` (auth only — NOT the inner
- * `tenantScope`, which the multi-tenant module owns), beside
- * `/v1/waitlist-signups/me` and `/v1/project-listings/me`. Lead capture is a
- * never-gate surface at every level, so reading a lead back must be too: this
- * route is registered unconditionally, not behind an `isModuleEnabled()` gate.
- * Registering everywhere is not the same as RETURNING a row everywhere —
- * `services/leads-inbox.ts` § "What it takes for this to return anything"
- * names the two deployment preconditions, both of which fail empty, never
- * wide.
- *
- * Identity is `request.userId` ONLY. There is no site, org or workspace
- * parameter — the query schema declares `cursor` and `limit` and nothing else
- * — so the scope cannot be widened from the wire. `services/leads-inbox.ts`
- * resolves it from the caller's own memberships through
- * `services/owner-workspaces.ts`'s `resolveOwnerWorkspaces` and filters every
- * read on `siteId ∈ workspaceIds`.
- *
- * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
- * `{ ok: false, error: { code, message } }`, real HTTP status codes:
- *   400 validation_failed · 401 unauthorized · 500 internal_error.
- *
- * No response-contract re-parse (the `waitlist-experiments/respond.ts`
- * `sendValidated` net): the five fields of a row are assembled one by one in
- * `leads-inbox.ts` from five explicitly selected columns, with no
- * pass-through of a stored value that could carry an unexpected shape — so
- * there is no drift for that net to catch.
- *
- * API↔MCP parity: identity-bound (the session IS the scope; the OSS MCP
- * surface is identity-blind) — no MCP twin (#3591 exception, the same shape as
- * `/v1/workspaces/*`, `/v1/billing/*` and `/v1/waitlist-experiments/*`).
- */
-import { zLeadId } from "@working-theory/ids";
-import type { FastifyPluginAsync, FastifyReply } from "fastify";
-import { z } from "zod";
-
-import { listOwnedLeads } from "../../services/leads-inbox.js";
-
-const DEFAULT_LIMIT = 50;
-const MAX_LIMIT = 200;
-
-const emptyToUndefined = (val: unknown) => (val === "" ? undefined : val);
-
-/** Boundary validation, mirroring `waitlist-experiments/signups.ts`'s query schema. */
-const listQuerySchema = z.object({
-  cursor: z.preprocess(emptyToUndefined, zLeadId.optional()),
-  limit: z.preprocess(
-    emptyToUndefined,
-    z.coerce.number().int().min(1).max(MAX_LIMIT).optional(),
-  ),
-});
-
-function unauthorized(reply: FastifyReply) {
-  return reply.status(401).send({
-    ok: false,
-    error: { code: "unauthorized", message: "Authentication required" },
-  });
-}
-
-function invalidQuery(reply: FastifyReply, message: string) {
-  return reply.status(400).send({
-    ok: false,
-    error: { code: "validation_failed", message },
-  });
-}
-
-export const leadListRoute: FastifyPluginAsync = async (fastify) => {
-  fastify.get("/v1/leads", async (request, reply) => {
-    const userId = request.userId;
-    if (!userId) return unauthorized(reply);
-
-    const query = listQuerySchema.safeParse(request.query);
-    if (!query.success) return invalidQuery(reply, "Invalid query parameters");
-
-    const result = await listOwnedLeads({
-      userId,
-      cursor: query.data.cursor,
-      limit: query.data.limit ?? DEFAULT_LIMIT,
-    });
-
-    if (!result.ok) {
-      if (result.error.kind === "invalid_cursor") {
-        return invalidQuery(reply, result.error.message);
-      }
-      // Do not surface internal error detail — log it server-side only, and
-      // with no lead field in the log line (the leads PII boundary).
-      request.log.error(
-        { route: "leads/list", error: result.error.message },
-        "leads list failed",
-      );
-      return reply.status(500).send({
-        ok: false,
-        error: { code: "internal_error", message: "Failed to read leads" },
-      });
-    }
-
-    return reply.status(200).send({ ok: true, data: result.value });
-  });
-};