create-ailk 0.24.0 → 0.26.0

package/templates/apps/api/src/services/request-confirm.ts

@@ -1,698 +0,0 @@
-/**
- * @file request-confirm.ts
- * @description The request-and-confirm lifecycle (#5970, D-67 / SUB-100) —
- * the service half of "a request form → the tenant confirms → a Payment Link
- * from the tenant's own Stripe".
- *
- * It owns four things and deliberately no more: the confirm CREDENTIAL (mint,
- * digest, resolve, spend), the tenant-facing SEND that carries it, the
- * CONFIGURATION that decides whether any of this runs at all, and the two
- * writes that record what the confirmation produced. The Stripe calls and the
- * HTTP shapes belong to `routes/requests/confirm.ts`; this module never
- * imports `packages/stripe-client` and never renders a byte of HTML.
- *
- * ── NO LICENCE CLAIM IS READ HERE (spec D9, issue AC-4) ─────────────────────
- *
- * Nothing in this file calls the licence checker, resolves the commerce claim,
- * or imports the licence package. (Those three names are deliberately written
- * as prose rather than as code: § 6.1 step 7 of the spec verifies this
- * property with a `grep`, and a doc comment quoting the identifiers would trip
- * its own check.) The commerce claim the confirm ROUTE serves behind is
- * applied by COMPOSITION at registration in `server.ts` — the checkout
- * launcher's own shape — so the gate is real without any new file reading it. The CAPTURE half this module's send hangs off is never-gate
- * anyway: lead capture end-to-end is free at every level (`CLAUDE.md`
- * § License & tier hygiene), and putting a licence read on it would be the
- * defect, not the feature.
- *
- * ── PII BOUNDARY ────────────────────────────────────────────────────────────
- *
- * The standard is `services/project-listing-resume-email.ts`'s, adopted
- * wholesale: a log line here may carry a `siteId`, a callback id, a reason, an
- * error KIND and a link's HOST. It may never carry the confirm token, the
- * assembled link's QUERY (which is the token), the requester's name or phone,
- * the buyer's address, or the tenant's address. Resend's own `error.message`
- * is untrusted — it can quote an address — so only `error.kind` is logged.
- *
- * ── WHY NO PER-RECIPIENT SEND BUDGET, unlike the resume email ───────────────
- *
- * `sendListingResumeLink` bounds itself per recipient and per site because the
- * address it sends to is one the ANONYMOUS CALLER TYPED — looped, that is a
- * mail bomb aimed at a named victim (#5411/#5414). Here the recipient is the
- * OPERATOR'S OWN CONFIGURED ADDRESS, read from the environment and never from
- * a request body, so the shape those bounds defend against does not arise: a
- * flood costs the operator their own inbox, which is the same exposure the
- * generic lead notification this message SUPERSEDES already had. The leads
- * scope's rate limiter is the bound that applies, and the per-row ceiling
- * below is the one that actually holds.
- */
-
-import { createHash, randomBytes } from "node:crypto";
-
-import {
-  sendRequestConfirmEmail,
-  sendRequestPaidLinkEmail,
-} from "@working-theory/email";
-import { logger } from "@working-theory/observability";
-
-import { isModuleEnabled } from "../config/modules.js";
-import { prisma } from "../lib/prisma.js";
-
-import { findOrCreatePerson, normalizeTelephone } from "./person.js";
-
-// ─── The credential (spec D5) ──────────────────────────────────────────────
-
-/**
- * The token's entropy, in bytes. 256 bits — the same floor
- * `services/project-listings.ts` carries for its resume token, and far beyond
- * guessing at any request rate the routes' limiter permits.
- */
-const CONFIRM_TOKEN_BYTES = 32;
-
-/**
- * How long a confirm link stays live.
- *
- * Seven days, and the resume link's minutes-scale reasoning deliberately does
- * NOT transfer: a founder mid-form is a browser session, whereas a tenant is a
- * person with a mailbox who may be on a job all week. Seven days is long
- * enough for a weekend and short enough that a leaked mailbox archive is not a
- * standing charge primitive.
- */
-export const CONFIRM_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
-
-/**
- * Mint an opaque confirm token. Handed to the email builder exactly once;
- * only its digest is stored, so the server cannot hand it back a second time
- * and an attacker who reads the table still cannot present one.
- */
-function mintConfirmToken(): string {
-  return randomBytes(CONFIRM_TOKEN_BYTES).toString("base64url");
-}
-
-/**
- * What `confirmTokenHash` holds. A plain sha-256 with no salt and no
- * stretching is correct here and a KDF would not be: the input is 256 bits of
- * CSPRNG output, not a human-chosen secret, so there is no dictionary to
- * precompute and nothing for a work factor to slow down. The same sentence
- * `project-listings.ts` writes beside its own digest, for the same reason.
- *
- * Exported because the ROUTE hashes the token a caller presented before
- * handing it to the resolvers below — the token never becomes a `where` value
- * anywhere, only its digest does.
- */
-export function hashConfirmToken(token: string): string {
-  return createHash("sha256").update(token).digest("hex");
-}
-
-/**
- * The link the tenant clicks.
- *
- * Assembled through `URL` so a base that already carries a query string gains
- * a parameter rather than a second `?`, and so the token is percent-encoded.
- */
-export function confirmLinkFor(
-  baseUrl: string,
-  callbackId: string,
-  token: string,
-): string {
-  const url = new URL(
-    `/v1/requests/${encodeURIComponent(callbackId)}/confirm`,
-    baseUrl,
-  );
-  url.searchParams.set("token", token);
-  return url.toString();
-}
-
-// ─── Configuration (spec D6) ───────────────────────────────────────────────
-
-/**
- * What the deployment has configured, or `null` when request-and-confirm is
- * not switched on.
- *
- * Every member has to resolve for the feature to run: a flag with no
- * recipient would write a credential nobody is ever sent, and a flag with no
- * base URL would assemble a link with no origin. `null` means the callback
- * path behaves byte-for-byte as it did before this feature existed — which is
- * why every existing leads suite stays green without being edited (NFR-1).
- *
- * The recipient and sender FALL BACK to the lead-notification pair, following
- * the `AILK_ABANDON_EMAIL_FROM` / `AILK_DELIVERABLE_EMAIL_FROM` idiom: a
- * deployment that already notifies an operator does not have to name the same
- * address twice.
- */
-export type RequestConfirmConfig = {
-  to: string;
-  from: string;
-  baseUrl: string;
-  /** The confirm form's default currency. Lowercase ISO-4217. */
-  currency: string;
-  /** The money gate's ceiling, in minor units (spec D10). */
-  maxAmountMinor: number;
-};
-
-/** Default currency when the deployment names none. */
-const DEFAULT_CURRENCY = "usd";
-
-/**
- * Default money-gate ceiling, in MINOR units: 1 000 000 — ten thousand
- * dollars at two decimal places. High enough not to obstruct a real job,
- * low enough that a typo with three extra zeroes is refused rather than
- * charged. A deployment whose jobs are genuinely larger raises it.
- */
-const DEFAULT_MAX_AMOUNT_MINOR = 1_000_000;
-
-/**
- * `amount_minor` is a Postgres `INTEGER`, so this is the largest value that
- * can be stored at all. A ceiling above it would admit an amount that passes
- * every check in the route and then throws out of Prisma at write time — a 500
- * on a money path, for a configuration mistake (#5970 security review, § 8).
- */
-const MAX_AMOUNT_MINOR_CEILING = 2_147_483_647;
-
-function readPositiveInt(raw: string | undefined, fallback: number): number {
-  if (raw === undefined) return fallback;
-  const parsed = Number(raw);
-  // A misconfigured ceiling must not become `NaN` (which every comparison
-  // fails, refusing every amount) or an unbounded one. Falling back to the
-  // platform default is the safe reading of a value that does not parse.
-  if (!Number.isInteger(parsed) || parsed <= 0) return fallback;
-  return Math.min(parsed, MAX_AMOUNT_MINOR_CEILING);
-}
-
-/**
- * Resolve the configuration, or `null` when the feature is off.
- *
- * Read on every call rather than memoized at import: the test suites and the
- * env-driven deployments both set these per process, and a module-level
- * snapshot would freeze whichever value happened to exist at first import.
- */
-export function requestConfirmConfig(): RequestConfirmConfig | null {
-  if (process.env["AILK_REQUEST_CONFIRM_ENABLED"] !== "true") return null;
-
-  // SINGLE-TENANT ONLY, and it fails closed (#5970 security review, finding 3).
-  //
-  // Every value this function resolves — the recipient, the sender, the
-  // currency, the ceiling — is process-wide, and so is `STRIPE_SECRET_KEY`.
-  // Nothing here is keyed on `Callback.siteId`. On a single-tenant deployment
-  // that is exactly right: one site, one owner, one Stripe account.
-  //
-  // On a MULTI-TENANT build it would be wrong in a way that costs money rather
-  // than tidiness: a callback captured for tenant B would be mailed to the
-  // DEPLOYMENT's configured address, and the Payment Link would be minted on
-  // the DEPLOYMENT's Stripe account — so B's customer pays, and the money
-  // lands in someone else's balance. (The PII half of that is not new: the
-  // generic lead notification this message supersedes already had one
-  // process-global recipient. The money half is new, and is what makes this a
-  // refusal rather than a caveat.)
-  //
-  // So on a multi-tenant build this returns `null` and the callback path
-  // behaves byte-for-byte as it did before the feature existed — the generic
-  // notification still goes out, because `requestConfirmSupersedesNotification`
-  // reads this same function. Lighting it up there means resolving all five
-  // values per `siteId` from a site-settings row, which is its own unit of
-  // work. `.env.example` says so beside the flag.
-  // `workspace` is guarded beside `multi-tenant` because `server.ts`'s own
-  // tenancy predicate is the pair, not either alone (#5970 security review
-  // round 2, informational). On a money path the conservative reading is the
-  // right one: if a build might carry more than one owner, it must not mint
-  // links on one process-wide Stripe account.
-  if (isModuleEnabled("multi-tenant") || isModuleEnabled("workspace")) {
-    return null;
-  }
-
-  const to =
-    process.env["AILK_REQUEST_CONFIRM_TO"] ??
-    process.env["AILK_LEAD_NOTIFICATION_TO"];
-  const from =
-    process.env["AILK_REQUEST_CONFIRM_FROM"] ??
-    process.env["AILK_LEAD_NOTIFICATION_FROM"];
-  const baseUrl = process.env["AILK_PUBLIC_API_URL"];
-
-  if (!to || !from || !baseUrl) return null;
-
-  return {
-    to,
-    from,
-    baseUrl,
-    currency:
-      process.env["AILK_REQUEST_CONFIRM_CURRENCY"]?.toLowerCase() ??
-      DEFAULT_CURRENCY,
-    maxAmountMinor: readPositiveInt(
-      process.env["AILK_REQUEST_CONFIRM_MAX_MINOR"],
-      DEFAULT_MAX_AMOUNT_MINOR,
-    ),
-  };
-}
-
-/**
- * Whether the confirm email SUPERSEDES the generic operator notification for
- * a callback (spec D6).
- *
- * AC-1 says the tenant receives EXACTLY ONE email. The callback path already
- * sends one — `sendLeadNotification` from `lead-routing.ts` — so a second
- * would be two. The confirm message carries strictly more than the one it
- * replaces (the same request details, plus the link), so replacing is the
- * behaviour-preserving direction.
- *
- * `lead-routing.ts` consults this and returns early; this module's send is
- * what runs instead.
- *
- * WHAT THE COUPLING ACTUALLY GUARANTEES, stated precisely because the loose
- * version of this sentence was wrong and shipped (#5970 acceptance review,
- * advisory 3). It used to read "one predicate, read by both sides, so the two
- * can never disagree and send zero emails or two". TWO is what it rules out,
- * and it does: the suppression and the send read the same configuration, so
- * they cannot both fire. ZERO was never ruled out, and the security review
- * found it in production shape — on the FILE-FALLBACK path the notification
- * was suppressed while the send matched no row, so a DB outage produced no
- * tenant email at all.
- *
- * The pair now shares THREE terms — `kind === "callback"`, `persisted ===
- * "db"`, and this configuration read — which closes that case. Zero remains
- * reachable AFTER the decision point, by a failure inside the confirm send
- * itself: the credential write matching no row, or Resend rejecting the
- * message. Both are logged and neither is silent, and they are the same
- * best-effort posture the notification they replaced already had — but they
- * are not impossible, and a reader deciding whether this coupling is safe
- * deserves the true statement rather than the comfortable one.
- */
-export function requestConfirmSupersedesNotification(): boolean {
-  return requestConfirmConfig() !== null;
-}
-
-// ─── The capture-side send ─────────────────────────────────────────────────
-
-/** What the tenant is shown about the request, in the email. */
-export type CapturedRequest = {
-  name: string;
-  phone: string;
-  preferredTime?: string | undefined;
-};
-
-async function send(
-  callbackId: string,
-  request: CapturedRequest,
-): Promise<void> {
-  const config = requestConfirmConfig();
-  if (config === null) {
-    logger.info(
-      { callbackId, reason: "not_configured" },
-      "request-confirm-email-skipped",
-    );
-    return;
-  }
-
-  const token = mintConfirmToken();
-
-  // The digest lands on the row BEFORE the message goes out. The other order
-  // would send a live link the database cannot yet resolve, and a send that
-  // succeeds against a write that then fails is a link that 404s forever.
-  // fence: global-key — `Callback.id`, the row's own primary key, minted
-  // moments earlier in THIS request's already-scoped frame: `routeLead`'s
-  // callback branch created the row with the route's resolved workspace id
-  // stamped on it and handed the new id straight to `sendRequestConfirmLink`
-  // (`routes/leads/index.ts`). The id is never read from a request body and
-  // never enumerated; this service holds no workspace id of its own, and the
-  // route files that do are audit-only for #6257.
-  const stored = await prisma.callback.updateMany({
-    // `confirmedAt: null` sits beside the digest guard deliberately (#5970
-    // security review, § 8). After a successful claim the digest IS null, so
-    // the digest test alone would let a second call mint a fresh credential on
-    // an already-confirmed row — and a second Payment Link with it. No caller
-    // does that today (lead capture always creates a new row), which is
-    // exactly why the guard has to say so rather than rely on it.
-    where: { id: callbackId, confirmTokenHash: null, confirmedAt: null },
-    data: {
-      confirmTokenHash: hashConfirmToken(token),
-      confirmTokenExpiresAt: new Date(Date.now() + CONFIRM_TOKEN_TTL_MS),
-    },
-  });
-
-  // `confirmTokenHash: null` in the guard means a row that already carries a
-  // credential is never re-minted — one live link per request, which is the
-  // per-row ceiling spec D11 leans on rather than a rate limiter.
-  if (stored.count !== 1) {
-    logger.warn(
-      { callbackId, reason: "no_row_to_credential" },
-      "request-confirm-email-skipped",
-    );
-    return;
-  }
-
-  // The HOST only, never the query — the query IS the credential. An operator
-  // who repointed `AILK_PUBLIC_API_URL` at a third party would otherwise
-  // exfiltrate every confirm token with nothing anywhere recording it.
-  const link = confirmLinkFor(config.baseUrl, callbackId, token);
-  logger.info(
-    { callbackId, linkHost: new URL(link).host },
-    "request-confirm-email-sending",
-  );
-
-  const result = await sendRequestConfirmEmail({
-    to: config.to,
-    fromAddress: config.from,
-    confirmLink: link,
-    request: {
-      name: request.name,
-      phone: request.phone,
-      ...(request.preferredTime !== undefined && {
-        preferredTime: request.preferredTime,
-      }),
-    },
-  });
-
-  if (!result.ok) {
-    // `error.kind`, never `error.message` — the latter is Resend's own text
-    // and can quote an address.
-    logger.warn(
-      { callbackId, errorKind: result.error.kind },
-      "request-confirm email send failed",
-    );
-  }
-}
-
-/**
- * Fire-and-forget entry point — what the callback route calls, and what keeps
- * its 201 independent of both Resend and this write.
- *
- * Returns `void` rather than a promise so a caller cannot accidentally
- * `await` it, and `.catch`-guards everything: `send` can reject (the Prisma
- * update, a malformed base URL reaching `new URL`) where
- * `sendRequestConfirmEmail` itself never does, and nothing from either may
- * reach a route whose row is already committed.
- *
- * `sendListingResumeLink`'s shape exactly — the same promise on the same kind
- * of feature: a best-effort side effect of a write that has already landed.
- */
-export function sendRequestConfirmLink(
-  callbackId: string,
-  request: CapturedRequest,
-): void {
-  send(callbackId, request).catch((err: unknown) => {
-    logger.warn(
-      { callbackId, errName: err instanceof Error ? err.name : "UnknownError" },
-      "request-confirm email rejected unexpectedly",
-    );
-  });
-}
-
-// ─── Resolution and stamping ───────────────────────────────────────────────
-
-/** What the confirm form needs to render, and nothing else. */
-export type ConfirmableRequest = {
-  id: string;
-  name: string;
-  phone: string;
-  preferredTime: string | null;
-  payload: unknown;
-};
-
-/**
- * Resolve the ONE request a token grants access to — the read the GET renders
- * from (spec D5).
- *
- * The id, the digest, the expiry and the not-yet-confirmed predicate are all
- * in one `where`, so a tampered token, an expired token, a token replayed
- * after use, and a valid token aimed at another row all resolve to `null`
- * IDENTICALLY. That identity is the point: the caller cannot tell which of the
- * four happened, and the route answers one 404 for all of them.
- *
- * The comparison is an equality test on a 256-bit digest inside Postgres.
- * There is no application-level secret compare to make constant-time, and no
- * practical timing signal in matching digests of that width.
- */
-export async function resolveConfirmableRequest(
-  id: string,
-  token: string,
-): Promise<ConfirmableRequest | null> {
-  // fence: global-key — the CONFIRM TOKEN digest
-  // (`Callback.confirmTokenHash`), a 256-bit single-use credential this
-  // service mints and hashes itself. It names one row across every workspace,
-  // and it — not the `id` beside it — is what authorizes the read: a valid
-  // token aimed at another row resolves to `null` identically to a tampered
-  // one. The caller is anonymous and carries no tenant, by design.
-  return prisma.callback.findFirst({
-    where: {
-      id,
-      confirmTokenHash: hashConfirmToken(token),
-      confirmTokenExpiresAt: { gt: new Date() },
-      confirmedAt: null,
-    },
-    select: {
-      id: true,
-      name: true,
-      phone: true,
-      preferredTime: true,
-      payload: true,
-    },
-  }) as Promise<ConfirmableRequest | null>;
-}
-
-/** What the POST stamps onto the row when it claims the credential. */
-export type ConfirmationClaim = {
-  id: string;
-  token: string;
-  confirmedTime: string;
-  buyerEmail: string;
-  amountMinor?: number | undefined;
-  currency?: string | undefined;
-};
-
-/**
- * Claim the credential and stamp the confirmation — verification and write in
- * ONE guarded update, deliberately.
- *
- * Reading first and writing second would leave a window in which two
- * simultaneous POSTs both pass the read and both go on to mint a Payment
- * Link. Here the `where` carries the same four predicates the resolver does,
- * so exactly one of those two updates reports `count === 1` and the other
- * reports `0` and is answered a 404. `confirmTokenHash: null` in the `data`
- * is what SPENDS the credential — that, not a flag, is the single-use
- * mechanism.
- *
- * It runs BEFORE any Stripe call, so a request that loses this race never
- * reaches the SDK: "one Payment Link total" (AC-2) is a property of this
- * update rather than of the handler's control flow.
- */
-export async function claimConfirmation(
-  claim: ConfirmationClaim,
-): Promise<boolean> {
-  // fence: global-key — the same CONFIRM TOKEN digest the resolver above is
-  // keyed on, spent in this statement. Verification and write are ONE guarded
-  // update precisely so the credential, not a prior read, is what admits the
-  // row; a tenant term would add nothing a 256-bit digest does not already
-  // decide.
-  const result = await prisma.callback.updateMany({
-    where: {
-      id: claim.id,
-      confirmTokenHash: hashConfirmToken(claim.token),
-      confirmTokenExpiresAt: { gt: new Date() },
-      confirmedAt: null,
-    },
-    data: {
-      confirmedAt: new Date(),
-      confirmedTime: claim.confirmedTime,
-      buyerEmail: claim.buyerEmail,
-      // The credential is spent in the same statement that stamps the
-      // confirmation — never in a follow-up write that could not run.
-      confirmTokenHash: null,
-      ...(claim.amountMinor !== undefined && {
-        amountMinor: claim.amountMinor,
-      }),
-      ...(claim.currency !== undefined && { currency: claim.currency }),
-    },
-  });
-  return result.count === 1;
-}
-
-/**
- * Give the credential back after a confirmation that produced nothing (#5970
- * security review, finding 4).
- *
- * `claimConfirmation` spends the token before the Stripe call, which is what
- * makes "one Payment Link total" true under a race. The cost is that a Stripe
- * refusal AFTER the claim leaves the row stamped and the link dead — and for
- * one refusal that cost is plainly wrong: an unknown `lookup_key` is a TYPO,
- * caught by a read (`stripe.prices.list`) that changes nothing on Stripe's
- * side. Telling the operator to "check the key and try again" while silently
- * having destroyed the only link they could try it from is not an error
- * message, it is a dead end.
- *
- * So that one case is rolled back: the stamp is cleared and the digest
- * rewritten, leaving the ORIGINAL expiry in place so a release cannot extend a
- * credential's life. The caller passes the same token it was given, which is
- * the only way to re-derive the digest — this function cannot resurrect a row
- * for anyone who did not already hold the credential.
- *
- * Deliberately NOT called for a generic Stripe failure: that one may have
- * created a Payment Link whose id never came back, and handing out a fresh
- * credential would then be how a second one gets minted.
- */
-export async function releaseConfirmation(
-  id: string,
-  token: string,
-): Promise<void> {
-  // fence: global-key — `Callback.id`, inside the frame the CONFIRM TOKEN
-  // digest already authorized: `claimConfirmation` spent that credential
-  // moments earlier in this same request, and the caller re-supplies the
-  // token (it is what re-derives the digest written below). The `where` is
-  // additionally narrowed to a row that produced no artifact, so a row a
-  // different attempt stamped can never be released here.
-  await prisma.callback.updateMany({
-    // Narrow enough to mean what the paragraph above says (#5970 security
-    // review round 2, informational). `stripePaymentLinkId: null` is what
-    // makes "a row this very call stamped, which produced nothing" a
-    // PREDICATE rather than a claim about the one caller: a row that already
-    // carries an artifact can never be released, however this is called.
-    where: {
-      id,
-      confirmTokenHash: null,
-      stripePaymentLinkId: null,
-      paidAt: null,
-    },
-    data: {
-      confirmTokenHash: hashConfirmToken(token),
-      confirmedAt: null,
-      confirmedTime: null,
-    },
-  });
-}
-
-/**
- * Record the Stripe artifact the confirmation produced.
- *
- * Separate from `claimConfirmation` because it happens AFTER the Stripe call,
- * which is the only ordering that can be honest: the id does not exist until
- * Stripe returns it. A confirmation whose Stripe call then fails leaves a
- * stamped row with no artifact id — visible, recoverable, and far better than
- * a Payment Link nothing recorded.
- *
- * This is also the column the webhook stamp matches on, so the write is what
- * makes `paidAt` reachable at all.
- */
-export async function recordPaymentLink(
-  id: string,
-  paymentLinkId: string,
-): Promise<void> {
-  // fence: global-key — `Callback.id`, inside the frame the CONFIRM TOKEN
-  // digest already authorized: this write records the artifact of a
-  // confirmation `claimConfirmation` admitted in this same request, and the
-  // id is the one that update matched. Nothing here is enumerable and nothing
-  // is read from a body.
-  await prisma.callback.update({
-    where: { id },
-    data: { stripePaymentLinkId: paymentLinkId },
-  });
-  // #8435 D5 — only now, with the Payment Link recorded: the Person step can
-  // never strand a spent token without its link (SEC-8435-G).
-  await linkConfirmedCallbackPerson(id);
-}
-
-/**
- * Link a confirmed callback to its Person (#8435 D5): when the capture did not
- * (`personId` null — no `payload.email`) and the tenant typed a buyer email on
- * the confirm form, find or create that email's Person in the callback's own
- * workspace and stamp it, guarded on `personId: null` so a link a capture
- * already made is never replaced. Best-effort like every Person step: it never
- * throws and never changes `recordPaymentLink`'s outcome. Logs the outcome
- * kind only.
- */
-async function linkConfirmedCallbackPerson(id: string): Promise<void> {
-  let outcome: "linked" | "skipped" | "failed";
-  try {
-    // fence: global-key — `Callback.id`, the row `recordPaymentLink` just
-    // wrote. The Person it names is found or created in THIS row's own
-    // `workspaceId`, so the link can only ever name a Person of that workspace.
-    const callback = await prisma.callback.findFirst({
-      where: { id },
-      select: { workspaceId: true, buyerEmail: true, name: true, phone: true, personId: true },
-    });
-    if (!callback || callback.personId !== null || callback.buyerEmail === null) {
-      outcome = "skipped";
-    } else {
-      const telephone = normalizeTelephone(callback.phone);
-      const person = await findOrCreatePerson(callback.workspaceId, {
-        email: callback.buyerEmail,
-        name: callback.name,
-        contact: telephone === null ? {} : { telephone },
-      });
-      if (!person.ok) {
-        outcome = person.error.kind === "invalid_email" ? "skipped" : "failed";
-      } else {
-        // fence: global-key — same `Callback.id`; `workspaceId` is the row's
-        // own, and `personId: null` keeps a capture's link.
-        await prisma.callback.updateMany({
-          where: { id, workspaceId: callback.workspaceId, personId: null },
-          data: { personId: person.value.personId },
-        });
-        outcome = "linked";
-      }
-    }
-  } catch {
-    outcome = "failed";
-  }
-  if (outcome === "failed") logger.error({ event: "callback-person", outcome }, "callback person failed");
-  else logger.info({ event: "callback-person", outcome }, "callback person");
-}
-
-/** What the buyer is told, once the tenant has confirmed. */
-export type PaidLinkNotice = {
-  id: string;
-  to: string;
-  from: string;
-  paymentUrl: string;
-  confirmedTime: string;
-  amountMinor?: number | undefined;
-  currency?: string | undefined;
-};
-
-/**
- * Email the buyer the hosted Stripe URL (AC-2's second half).
- *
- * AWAITED by its caller rather than fired and forgotten, unlike the
- * tenant-facing send above, and the difference is deliberate: the tenant is
- * looking at the confirm page when this runs, and whether their customer was
- * actually told is the one thing they cannot find out anywhere else. So the
- * result changes the page's WORDING.
- *
- * It still never throws and never fails the request. The Payment Link exists
- * either way; a send failure means the tenant forwards the URL themselves,
- * which the page then tells them to do.
- *
- * Returns whether the buyer was reached — not the message id, which nothing
- * here has any use for.
- */
-export async function sendPaidLinkToBuyer(
-  notice: PaidLinkNotice,
-): Promise<boolean> {
-  try {
-    const result = await sendRequestPaidLinkEmail({
-      to: notice.to,
-      fromAddress: notice.from,
-      paymentUrl: notice.paymentUrl,
-      confirmedTime: notice.confirmedTime,
-      ...(notice.amountMinor !== undefined && {
-        amountMinor: notice.amountMinor,
-      }),
-      ...(notice.currency !== undefined && { currency: notice.currency }),
-    });
-    if (!result.ok) {
-      // `error.kind`, never `error.message` — Resend's text can quote an
-      // address, and the buyer's address is exactly what must not be logged.
-      logger.warn(
-        { callbackId: notice.id, errorKind: result.error.kind },
-        "request-paid-link email send failed",
-      );
-      return false;
-    }
-    return true;
-  } catch (err) {
-    logger.warn(
-      {
-        callbackId: notice.id,
-        errName: err instanceof Error ? err.name : "UnknownError",
-      },
-      "request-paid-link email rejected unexpectedly",
-    );
-    return false;
-  }
-}