create-ailk 0.4.0 → 0.6.0

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

@@ -0,0 +1,646 @@
+/**
+ * @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";
+
+// ─── 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 },
+  });
+}
+
+/** 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;
+  }
+}