@softure-ai/billing 0.0.0-stage → 0.1.5

package/src/server/payments.ts

@@ -0,0 +1,434 @@
+// Payments a provider reports through its webhook: a paid checkout grants its plan and a refund
+// takes back what that payment granted (a partial one by the `partialRefunds` policy), each exactly
+// once. `billing.payments` holds one row per paid checkout with the grant it caused (a period or
+// lifetime), written in the transaction of the grant, so a delivery Stripe repeats (or two events
+// for one checkout) finds the row and changes nothing.
+// A payment keeps the total refunded so far (`refunded_amount`, the provider's cumulative figure),
+// so a repeated or stale refund delivery finds nothing new and changes nothing. A refund that fails
+// later gives back what it took (`failRefund`), once per refund id (`billing.refund_failures`); a
+// charge snapshot taken before a failure is corrected by the failed refunds it still counts. A newer
+// snapshot that reports no more than billing counts (a new refund after a failure billing has not
+// heard of yet) is kept on the payment, and each failure applies it once it reports more.
+// Locks: the account first (key share), like `changeEntitlement` and the privacy erase; a refund
+// then takes the entitlement before its payment row (`lockEntitlementRow`), as a manual revoke does,
+// so a refund and a revoke of one account queue on the entitlement instead of deadlocking on the
+// rows each moves back.
+import { users } from "@softure-ai/auth";
+import { err, ok, type Err, type Ok } from "@softure-ai/core";
+import type { Queryable } from "@softure-ai/db";
+import { and, eq, gt, lte, sql } from "drizzle-orm";
+import type { Entitlement, PaymentGrant } from "../contract.js";
+import { findPlan } from "../plans.js";
+import { resolveEntitlement } from "../entitlement.js";
+import { getRestoredDays, moveBackByDays, type RefundShare } from "../refund.js";
+import { payments, refundFailures } from "../schema.js";
+import { readStripeWebhook, type FailedRefund, type PaidCheckout, type StripeWebhookError } from "../stripe-webhook.js";
+import { changeEntitlement, findEntitlementRecord, type BillingContext } from "./entitlements.js";
+import { getBillingOptions, getEntitlementPolicy } from "./options.js";
+import { applyPlan, getBillingPlans } from "./plans.js";
+import { giveBackDays, hasActiveManualLifetime, hasPaidLifetimePayment, lockEntitlementRow, takeBackGrant } from "./take-back.js";
+import { isUserId } from "./user-id.js";
+
+/** The name of `stripe()`, under which its webhook stores payments. */
+export const STRIPE_PROVIDER = "stripe";
+
+export interface RecordPaymentInput extends PaidCheckout {
+  /** The adapter's name, e.g. `stripe`. */
+  readonly provider: string;
+}
+
+/** What a webhook delivery changed. */
+export type PaymentOutcome =
+  /** A new paid checkout: its plan was granted. */
+  | { readonly status: "granted"; readonly entitlement: Entitlement }
+  /** A full refund of a recorded payment (or the partial one that completes it): what it granted was taken back. */
+  | { readonly status: "refunded"; readonly entitlement: Entitlement }
+  /** A partial refund of a recorded payment: access changed by the `partialRefunds` policy. */
+  | { readonly status: "partially_refunded"; readonly entitlement: Entitlement }
+  /** A refund of a recorded payment failed: what it took was given back (nothing when billing never counted it). */
+  | { readonly status: "refund_failed"; readonly entitlement: Entitlement }
+  /** Recorded (or refunded) already: a repeated delivery, nothing changed. */
+  | { readonly status: "duplicate" }
+  /** A refund of a payment billing never recorded: nothing to take back. */
+  | { readonly status: "unknown_payment" }
+  /** An event billing does not act on. */
+  | { readonly status: "ignored"; readonly reason: string };
+
+export type RecordPaymentError = "billing.account_unknown" | "billing.plan_unknown";
+
+/**
+ * Records a paid checkout and grants one payment of its plan, in one transaction: `duplicate` when
+ * the checkout was recorded before. An account or plan that no longer exists stores nothing (the
+ * money is refunded in the provider's dashboard). Database errors propagate.
+ */
+export async function recordPayment(ctx: BillingContext, input: RecordPaymentInput): Promise<Ok<PaymentOutcome> | Err<RecordPaymentError>> {
+  if (findPlan(getBillingPlans(ctx.config), input.planId) === undefined) return err("billing.plan_unknown");
+  if (!isUserId(input.userId)) return err("billing.account_unknown");
+  return ctx.db.transaction(async (tx) => {
+    const now = ctx.clock.now();
+    // A shared lock: the account cannot be deleted before the grant below.
+    const [account] = await tx.select({ id: users.id }).from(users).where(eq(users.id, input.userId)).for("key share");
+    if (account === undefined) return err("billing.account_unknown");
+
+    // A concurrent delivery of the same checkout waits here for this transaction, then conflicts.
+    const inserted = await tx
+      .insert(payments)
+      .values({
+        userId: input.userId,
+        provider: input.provider,
+        checkoutId: input.checkoutId,
+        paymentId: input.paymentId,
+        planId: input.planId,
+        amount: input.amount,
+        currency: input.currency,
+        status: "paid",
+        paidAt: now,
+      })
+      .onConflictDoNothing()
+      .returning();
+    if (inserted.length === 0) return ok({ status: "duplicate" });
+
+    const applied = await applyPlan({ ...ctx, db: tx }, input.userId, input.planId);
+    // The plan and the locked account were checked above, and a plan grant always ends later.
+    if (!applied.ok) throw new Error(`@softure-ai/billing: granting the paid plan "${input.planId}" failed with ${applied.error}`);
+    const [payment] = inserted;
+    const { grant } = applied.value;
+    // A plan grant always adds a period of at least a day, or lifetime access.
+    if (payment === undefined || grant === null) throw new Error(`@softure-ai/billing: the paid plan "${input.planId}" was granted but its payment row or grant is missing`);
+    await tx.update(payments).set(getGrantColumns(grant)).where(eq(payments.id, payment.id));
+    return ok({ status: "granted", entitlement: applied.value.entitlement });
+  });
+}
+
+export interface RefundPaymentInput {
+  readonly provider: string;
+  /** The provider's payment id the refund names (a Stripe PaymentIntent). */
+  readonly paymentId: string;
+  /**
+   * For a partial refund, the total refunded so far in the currency's minor unit (Stripe's
+   * `amount_refunded`); omitted when the payment is refunded in full. A total that reaches the
+   * payment's amount is a full refund.
+   */
+  readonly amountRefunded?: number;
+  /**
+   * When the provider took the charge's state the delivery reports (Stripe's event `created`); now
+   * when omitted. Refunds that failed after it and were created before it are not counted in it.
+   */
+  readonly observedAt?: Date;
+}
+
+export interface GrantColumns {
+  readonly grantKind: "period" | "lifetime" | null;
+  readonly grantedFrom: Date | null;
+  readonly grantedUntil: Date | null;
+}
+
+/** The payment row's columns for what its grant added. */
+export function getGrantColumns(grant: PaymentGrant): GrantColumns {
+  if (grant.kind === "lifetime") return { grantKind: "lifetime", grantedFrom: null, grantedUntil: null };
+  return { grantKind: "period", grantedFrom: grant.from, grantedUntil: grant.until };
+}
+
+/** The grant a payment row records, or null for a row stored before grants were. */
+export function readGrant(row: GrantColumns): PaymentGrant | null {
+  if (row.grantKind === "lifetime") return { kind: "lifetime" };
+  if (row.grantKind === "period" && row.grantedFrom !== null && row.grantedUntil !== null) return { kind: "period", from: row.grantedFrom, until: row.grantedUntil };
+  return null;
+}
+
+/**
+ * Records a refund of a payment and takes back what it granted, in one transaction. A full refund
+ * marks it refunded: a period loses its unused days, a lifetime ends unless another paid lifetime
+ * payment or an active manual lifetime grant still gives it, and a payment stored before grants were
+ * recorded revokes paid access. A partial refund keeps it paid and follows
+ * `billing({ partialRefunds })`: `pro_rata` takes back the share of the unused days that the newly
+ * refunded money is of the money not refunded before (rounded down) and shortens the payment's
+ * stored period by them; `keep_access` takes nothing back. Partial refunds never end a lifetime
+ * nor revoke a payment without a recorded grant; the refund that completes the amount does what a
+ * full refund does. The reported total first loses the failed refunds it still counts (created by
+ * `observedAt`, failed after it). `duplicate` when the refund adds nothing to what was recorded (a
+ * repeated or stale delivery); a state newer than every one recorded is then kept for the failure
+ * that explains it (`failRefund`). `unknown_payment` when billing never recorded the payment. The
+ * days a refund takes are added to the payment's `taken_back_days`, for a failure to give back.
+ * Database errors propagate.
+ */
+export async function refundPayment(ctx: BillingContext, input: RefundPaymentInput): Promise<Ok<PaymentOutcome>> {
+  return ctx.db.transaction(async (tx) => {
+    const now = ctx.clock.now();
+    const match = and(eq(payments.provider, input.provider), eq(payments.paymentId, input.paymentId));
+    const [found] = await tx.select({ userId: payments.userId }).from(payments).where(match);
+    if (found === undefined) return ok({ status: "unknown_payment" });
+    const { userId } = found;
+    // The account first (the lock order of every change), the entitlement, then the payment row.
+    await tx.select({ id: users.id }).from(users).where(eq(users.id, userId)).for("key share");
+    await lockEntitlementRow(tx, userId);
+    const [payment] = await tx.select().from(payments).where(match).for("update");
+    // Erased with the account in the meantime.
+    if (payment === undefined) return ok({ status: "duplicate" });
+
+    const state = { reported: input.amountRefunded ?? payment.amount, observedAt: input.observedAt ?? now };
+    const applied = await applyChargeState({ ...ctx, db: tx }, { payment, state, now });
+    if (applied !== null) return ok(applied);
+    await keepNewerChargeState(tx, payment, state);
+    return ok({ status: "duplicate" });
+  });
+}
+
+type PaymentRow = typeof payments.$inferSelect;
+
+/** What applying a charge state changed. */
+type AppliedRefund = Extract<PaymentOutcome, { readonly status: "refunded" | "partially_refunded" }>;
+
+/** A charge's refunded total as the provider reported it, before any correction, and when it was taken. */
+interface ChargeState {
+  readonly reported: number;
+  readonly observedAt: Date;
+}
+
+interface ApplyChargeStateInput {
+  /** The payment's row, read under the caller's locks. */
+  readonly payment: PaymentRow;
+  readonly state: ChargeState;
+  readonly now: Date;
+}
+
+/**
+ * Applies a charge state to a payment the caller locked (the account, the entitlement, the row):
+ * the refunded total it reports, less the failed refunds it still counts, takes back what it adds
+ * to the recorded total (see `refundPayment`). Null when it adds nothing (the payment is refunded
+ * in full, or the total is not above the recorded one). A kept state at or before it is cleared.
+ */
+async function applyChargeState(ctx: BillingContext, { payment, state, now }: ApplyChargeStateInput): Promise<AppliedRefund | null> {
+  const total = Math.min(Math.max(state.reported - (await getFailedAmountCounted(ctx.db, payment.id, state.observedAt)), 0), payment.amount);
+  const isFull = total >= payment.amount;
+  if (payment.status !== "paid" || (!isFull && total <= payment.refundedAmount)) return null;
+
+  const { userId } = payment;
+  const refundsSeenAt = payment.refundsSeenAt !== null && payment.refundsSeenAt > state.observedAt ? payment.refundsSeenAt : state.observedAt;
+  const isPendingIncluded = payment.pendingRefundsSeenAt !== null && payment.pendingRefundsSeenAt <= state.observedAt;
+  await ctx.db
+    .update(payments)
+    .set({
+      ...(isFull ? { status: "refunded", refundedAt: now, refundedAmount: payment.amount } : { refundedAmount: total }),
+      refundsSeenAt,
+      ...(isPendingIncluded ? { pendingRefundedAmount: null, pendingRefundsSeenAt: null } : {}),
+    })
+    .where(eq(payments.id, payment.id));
+
+  const share = isFull ? undefined : getPartialShare(ctx, { refunded: total - payment.refundedAmount, outstanding: payment.amount - payment.refundedAmount });
+  const grant = readGrant(payment);
+  const { entitlement, days } = await takeBackGrant(ctx, {
+    userId,
+    grant,
+    now,
+    share,
+    hasOtherLifetime: async () => (await hasActiveManualLifetime(ctx.db, userId)) || (await hasPaidLifetimePayment(ctx.db, userId, payment.id)),
+  });
+  if (days > 0 && grant?.kind === "period") {
+    // A partially refunded payment stays paid: its stored period ends where the access it still pays for does.
+    const grantedUntil = isFull ? grant.until : moveBackByDays(grant.until, days, ctx.config.timezone);
+    await ctx.db
+      .update(payments)
+      .set({ grantedUntil, takenBackDays: payment.takenBackDays + days })
+      .where(eq(payments.id, payment.id));
+  }
+  return { status: isFull ? "refunded" : "partially_refunded", entitlement };
+}
+
+/**
+ * Keeps a charge state billing did not apply when it is newer than every state recorded (applied or
+ * kept): it may carry a new refund that a failure billing has not heard of yet hides.
+ */
+async function keepNewerChargeState(tx: Queryable, payment: PaymentRow, state: ChargeState): Promise<void> {
+  const isNewer = (seenAt: Date | null) => seenAt === null || state.observedAt > seenAt;
+  if (!isNewer(payment.refundsSeenAt) || !isNewer(payment.pendingRefundsSeenAt)) return;
+  await tx
+    .update(payments)
+    .set({ pendingRefundedAmount: state.reported, pendingRefundsSeenAt: state.observedAt })
+    .where(eq(payments.id, payment.id));
+}
+
+/** The failed refunds of a payment a charge snapshot taken at `observedAt` still counts: created by then, failed after. */
+async function getFailedAmountCounted(tx: Queryable, paymentId: string, observedAt: Date): Promise<number> {
+  const [row] = await tx
+    .select({ amount: sql<string>`coalesce(sum(${refundFailures.amount}), 0)` })
+    .from(refundFailures)
+    .where(and(eq(refundFailures.paymentId, paymentId), lte(refundFailures.refundCreatedAt, observedAt), gt(refundFailures.failedAt, observedAt)));
+  return Number(row?.amount ?? 0);
+}
+
+export interface FailRefundInput extends FailedRefund {
+  /** The adapter's name, e.g. `stripe`. */
+  readonly provider: string;
+}
+
+/**
+ * Records a refund of a payment that failed and gives back what it took, in one transaction, under
+ * the locks of `refundPayment`. Billing counted the refund when the newest charge snapshot it
+ * recorded was taken after the refund was created and before it failed; then the payment's
+ * refunded total drops by the refund's amount, a payment refunded in full is paid again (a lifetime
+ * comes back), and its period gets back the failed money's share of the days refunds took
+ * (`getRestoredDays`, by `partialRefunds`), with `giveBackDays`. A failure billing never counted is
+ * only recorded, so a later snapshot that still counts the refund is corrected by it. A payment
+ * stored before grants were recorded gets its total and status back but no access. Then the charge
+ * state `refundPayment` kept is applied when, corrected, it reports more than billing now counts: a
+ * new refund reported before this failure is taken back once. `duplicate` for a refund already
+ * recorded as failed, `unknown_payment` when billing never recorded the payment. Database errors
+ * propagate.
+ */
+export async function failRefund(ctx: BillingContext, input: FailRefundInput): Promise<Ok<PaymentOutcome>> {
+  return ctx.db.transaction(async (tx) => {
+    const now = ctx.clock.now();
+    const txCtx = { ...ctx, db: tx };
+    const match = and(eq(payments.provider, input.provider), eq(payments.paymentId, input.paymentId));
+    const [found] = await tx.select({ userId: payments.userId }).from(payments).where(match);
+    if (found === undefined) return ok({ status: "unknown_payment" });
+    const { userId } = found;
+    // The lock order of `refundPayment`: the account, the entitlement, then the payment row.
+    await tx.select({ id: users.id }).from(users).where(eq(users.id, userId)).for("key share");
+    await lockEntitlementRow(tx, userId);
+    const [payment] = await tx.select().from(payments).where(match).for("update");
+    // Erased with the account in the meantime.
+    if (payment === undefined) return ok({ status: "unknown_payment" });
+
+    const recorded = await tx
+      .insert(refundFailures)
+      .values({
+        paymentId: payment.id,
+        refundId: input.refundId,
+        amount: input.amount,
+        refundCreatedAt: input.refundCreatedAt,
+        failedAt: input.failedAt,
+        recordedAt: now,
+      })
+      .onConflictDoNothing()
+      .returning();
+    if (recorded.length === 0) return ok({ status: "duplicate" });
+
+    const seenAt = payment.refundsSeenAt;
+    const isCounted = seenAt !== null && input.refundCreatedAt <= seenAt && seenAt < input.failedAt;
+    const restoredAmount = isCounted ? Math.min(input.amount, payment.refundedAmount) : 0;
+    const restored = restoredAmount === 0 ? null : await restoreRefund(txCtx, { payment, restoredAmount, now });
+    const kept = await applyKeptChargeState(txCtx, payment.id, now);
+    return ok({ status: "refund_failed", entitlement: kept?.entitlement ?? restored ?? (await readEntitlement(txCtx, userId, now)) });
+  });
+}
+
+interface RestoreRefundInput {
+  /** The payment's row, read under the caller's locks. */
+  readonly payment: PaymentRow;
+  /** What billing counted of the failed refund, above 0. */
+  readonly restoredAmount: number;
+  readonly now: Date;
+}
+
+/** Gives back what a failed refund billing counted took (see `failRefund`); the entitlement when access changed. */
+async function restoreRefund(ctx: BillingContext, { payment, restoredAmount, now }: RestoreRefundInput): Promise<Entitlement | null> {
+  const { userId } = payment;
+  const days = getRestoredDays({
+    takenBackDays: payment.takenBackDays,
+    refundedAmount: payment.refundedAmount,
+    restoredAmount,
+    policy: getBillingOptions(ctx.config).partialRefunds,
+  });
+  const isPaid = payment.status === "paid";
+  const grant = readGrant(payment);
+  let entitlement: Entitlement | null = null;
+  let period: GrantColumns | null = null;
+  if (grant?.kind === "period" && days > 0) {
+    const given = await giveBackDays(ctx, { userId, grant, isPaid, days, now });
+    entitlement = given.entitlement;
+    period = getGrantColumns(given.period);
+  } else if (grant?.kind === "lifetime" && !isPaid) {
+    const changed = await changeEntitlement(ctx, userId, { type: "grant_lifetime" });
+    // The account is locked and a lifetime grant is never refused.
+    if (!changed.ok) throw new Error(`@softure-ai/billing: giving back a refunded lifetime failed with ${changed.error}`);
+    entitlement = changed.value;
+  }
+  // Below the amount again, so a payment refunded in full is paid again.
+  await ctx.db
+    .update(payments)
+    .set({
+      status: "paid",
+      refundedAt: null,
+      refundedAmount: payment.refundedAmount - restoredAmount,
+      takenBackDays: payment.takenBackDays - days,
+      ...(period === null ? {} : { grantedFrom: period.grantedFrom, grantedUntil: period.grantedUntil }),
+    })
+    .where(eq(payments.id, payment.id));
+  return entitlement;
+}
+
+/** Applies the charge state a payment kept (see `refundPayment`) when it now reports more than billing counts. */
+async function applyKeptChargeState(ctx: BillingContext, paymentId: string, now: Date): Promise<AppliedRefund | null> {
+  // Read again: the restore may have changed the row. The caller holds its lock.
+  const [payment] = await ctx.db.select().from(payments).where(eq(payments.id, paymentId));
+  if (payment === undefined || payment.pendingRefundedAmount === null || payment.pendingRefundsSeenAt === null) return null;
+  return applyChargeState(ctx, { payment, state: { reported: payment.pendingRefundedAmount, observedAt: payment.pendingRefundsSeenAt }, now });
+}
+
+/** Where the account stands at `now`, read inside the caller's transaction. */
+async function readEntitlement(ctx: BillingContext, userId: string, now: Date): Promise<Entitlement> {
+  const record = await findEntitlementRecord(ctx, userId);
+  // The caller's payment row references the account, which its key share lock keeps.
+  if (record === null) throw new Error("@softure-ai/billing: a refunded payment has no account");
+  return resolveEntitlement(record, now, getEntitlementPolicy(ctx.config));
+}
+
+/** The share a partial refund takes back under the app's policy: none under `keep_access`. */
+function getPartialShare(ctx: BillingContext, share: RefundShare): RefundShare {
+  return getBillingOptions(ctx.config).partialRefunds === "keep_access" ? { ...share, refunded: 0 } : share;
+}
+
+export interface ReceiveStripeWebhookInput {
+  /** The raw request body, exactly as Stripe sent it. */
+  readonly payload: string;
+  /** The `Stripe-Signature` header, or null. */
+  readonly signature: string | null;
+  /** The endpoint's signing secret (`whsec_...`). */
+  readonly secret: string;
+}
+
+export interface StripeWebhookReceipt {
+  readonly eventId: string;
+  readonly outcome:
+    | PaymentOutcome
+    /** A paid checkout whose account or plan is gone: nothing stored, refund it in Stripe. */
+    | { readonly status: "refused"; readonly error: RecordPaymentError; readonly checkoutId: string };
+}
+
+/**
+ * One Stripe webhook delivery: the signature is checked before anything is parsed or read, then a
+ * paid checkout is recorded and granted, a refund takes back what its payment granted (a partial
+ * one by the `partialRefunds` policy), and a failed refund gives it back.
+ * `billing.webhook_invalid` for a delivery that is not Stripe's (or a replay past the tolerance).
+ * Database errors propagate (answer 500, Stripe retries).
+ */
+export async function receiveStripeWebhook(ctx: BillingContext, input: ReceiveStripeWebhookInput): Promise<Ok<StripeWebhookReceipt> | Err<StripeWebhookError>> {
+  const event = readStripeWebhook({ payload: input.payload, header: input.signature, secret: input.secret, now: ctx.clock.now() });
+  if (!event.ok) return event;
+  const { eventId } = event.value;
+  switch (event.value.type) {
+    case "ignored":
+      return ok({ eventId, outcome: { status: "ignored", reason: event.value.reason } });
+    case "checkout_paid": {
+      const { checkout } = event.value;
+      const recorded = await recordPayment(ctx, { provider: STRIPE_PROVIDER, ...checkout });
+      return ok({ eventId, outcome: recorded.ok ? recorded.value : { status: "refused", error: recorded.error, checkoutId: checkout.checkoutId } });
+    }
+    case "payment_refunded": {
+      const { paymentId, snapshotAt } = event.value;
+      const refunded = await refundPayment(ctx, { provider: STRIPE_PROVIDER, paymentId, observedAt: snapshotAt });
+      return ok({ eventId, outcome: refunded.value });
+    }
+    case "payment_partially_refunded": {
+      const { paymentId, amountRefunded, snapshotAt } = event.value;
+      const refunded = await refundPayment(ctx, { provider: STRIPE_PROVIDER, paymentId, amountRefunded, observedAt: snapshotAt });
+      return ok({ eventId, outcome: refunded.value });
+    }
+    case "refund_failed": {
+      const failed = await failRefund(ctx, { provider: STRIPE_PROVIDER, ...event.value.failure });
+      return ok({ eventId, outcome: failed.value });
+    }
+  }
+}

package/src/server/plans.ts

@@ -0,0 +1,143 @@
+// Plans on the server: the configured list, granting a plan to an account (the one path the
+// manual admin page and a provider's webhook take) and starting a payment through the provider.
+import { users } from "@softure-ai/auth";
+import { err, ok, type Err, type Ok, type SoftureConfig } from "@softure-ai/core";
+import { consumeRateLimit, subjectKey } from "@softure-ai/security/server";
+import { eq } from "drizzle-orm";
+import type { BillingErrorCode, Entitlement, EntitlementEvent, PaymentErrorCode, PaymentGrant, Plan } from "../contract.js";
+import { parseInvoiceDetails, type InvoiceDetailsError, type InvoiceInput } from "../invoice.js";
+import type { InvoiceDetails, PaymentAccount, PaymentProvider, PaymentStart } from "../payment.js";
+import { findPlan, getPlanGrant } from "../plans.js";
+import { getPaymentGrant } from "../refund.js";
+import { changeEntitlement, findEntitlementRecord, type BillingContext } from "./entitlements.js";
+import { getBillingOptions, getBillingRoutes } from "./options.js";
+import { claimHandOver, confirmHandOver, recordPaymentRequest, releaseHandOver } from "./requests.js";
+import { isUserId } from "./user-id.js";
+import { assertPaymentSetup, PAYMENT_BUCKET } from "./setup.js";
+
+/** The plans of `billing({ plans })`, in their order. */
+export function getBillingPlans(config: SoftureConfig): readonly Plan[] {
+  return getBillingOptions(config).plans;
+}
+
+/** The provider of `billing({ payment })`. Throws when the app set none: a payment page without one is a bug. */
+export function getPaymentProvider(config: SoftureConfig): PaymentProvider {
+  const provider = getBillingOptions(config).payment;
+  if (provider === undefined) throw new Error("@softure-ai/billing: billing({ payment }) is not set; the payment page needs a provider such as manual()");
+  return provider;
+}
+
+/** The account with this email (compared trimmed and lower-cased, as auth stores it), or null. */
+export async function findAccountByEmail(ctx: Pick<BillingContext, "db">, email: string): Promise<PaymentAccount | null> {
+  const [row] = await ctx.db
+    .select({ id: users.id, email: users.email })
+    .from(users)
+    .where(eq(users.email, email.trim().toLowerCase()))
+    .limit(1);
+  return row ?? null;
+}
+
+/** The account with this id, or null (also for an id that is not a uuid). */
+export async function findAccountById(ctx: Pick<BillingContext, "db">, id: string): Promise<PaymentAccount | null> {
+  if (!isUserId(id)) return null;
+  const [row] = await ctx.db.select({ id: users.id, email: users.email }).from(users).where(eq(users.id, id));
+  return row ?? null;
+}
+
+/** Where the account stands after a plan grant, and what the grant added (null when it added nothing). */
+export interface AppliedPlan {
+  readonly entitlement: Entitlement;
+  readonly grant: PaymentGrant | null;
+}
+
+/**
+ * `grantPlan` that also says what the grant added, for the payment row that pays for it. The event
+ * is computed under the entitlement's lock and may be computed twice (a concurrent first change), so
+ * the grant is taken from the last computation, the one applied.
+ */
+export async function applyPlan(ctx: BillingContext, userId: string, planId: string): Promise<Ok<AppliedPlan> | Err<BillingErrorCode | "billing.plan_unknown">> {
+  const plan = findPlan(getBillingPlans(ctx.config), planId);
+  if (plan === undefined) return err("billing.plan_unknown");
+  let grant = null as PaymentGrant | null;
+  const changed = await changeEntitlement(ctx, userId, (record, now): EntitlementEvent => {
+    const event = getPlanGrant(record, plan, now, ctx.config.timezone);
+    grant = getPaymentGrant(record, event, now);
+    return event;
+  });
+  return changed.ok ? ok({ entitlement: changed.value, grant }) : changed;
+}
+
+/**
+ * Grants one payment of the plan: a paid period that starts when the account's current access ends,
+ * or lifetime access. Computed under the entitlement's lock, so two grants at once give two periods.
+ * It records nothing: a grant made here is not in the account's history and cannot be revoked; an
+ * admin's grant goes through `grantPlanManually`.
+ */
+export async function grantPlan(ctx: BillingContext, userId: string, planId: string): Promise<Ok<Entitlement> | Err<BillingErrorCode | "billing.plan_unknown">> {
+  const applied = await applyPlan(ctx, userId, planId);
+  return applied.ok ? ok(applied.value.entitlement) : applied;
+}
+
+export interface StartPaymentInput {
+  readonly account: PaymentAccount;
+  readonly planId: string;
+  /** What the form sent; ignored when the provider collects its own details. */
+  readonly invoice: InvoiceInput;
+}
+
+export type StartPaymentResult = Ok<PaymentStart> | Err<Exclude<PaymentErrorCode, "billing.invoice_details_invalid"> | "security.rate_limited"> | InvoiceDetailsError;
+
+/**
+ * Starts paying for a plan: counts `billing-payment` per account first, checks the plan, that the
+ * account has no lifetime access yet and, for a provider that needs them, the invoice details, then
+ * starts the provider. A provider that hands requests over (`handsOverRequests`, the manual adapter)
+ * gets the request stored first and is called once per open request: asking again refreshes the
+ * stored request and answers `requested` without a second hand-over, and a hand-over that failed
+ * (an `Err` or a throw) is released, so the next ask tries again; a claim left without an answer (the
+ * process stopped) is taken over by an ask a minute later. Database errors and provider
+ * throws propagate; a provider whose answer contradicts `handsOverRequests` throws.
+ */
+export async function startPayment(ctx: BillingContext, input: StartPaymentInput): Promise<StartPaymentResult> {
+  assertPaymentSetup(ctx.config);
+  const provider = getPaymentProvider(ctx.config);
+  const limited = await consumeRateLimit(ctx, { bucket: PAYMENT_BUCKET, key: subjectKey(`account:${input.account.id}`) });
+  if (!limited.ok) return err("security.rate_limited");
+
+  const plan = findPlan(getBillingPlans(ctx.config), input.planId);
+  if (plan === undefined) return err("billing.plan_unknown");
+  const record = await findEntitlementRecord(ctx, input.account.id);
+  if (record?.isLifetime === true) return err("billing.lifetime_active");
+  let invoice: InvoiceDetails | null = null;
+  if (provider.collectsInvoiceDetails) {
+    const parsed = parseInvoiceDetails(input.invoice);
+    if (!parsed.ok) return parsed;
+    invoice = parsed.value;
+  }
+  const returnUrl = new URL(getBillingRoutes(ctx.config).payment, ctx.config.appOrigin).toString();
+  const request = { plan, account: input.account, invoice, returnUrl };
+  if (!provider.handsOverRequests) {
+    const started = await provider.startPayment(ctx, request);
+    if (started.ok && started.value.type === "requested") throw new Error(`@softure-ai/billing: provider "${provider.name}" answered requested but does not set handsOverRequests`);
+    return started;
+  }
+
+  const requestId = await recordPaymentRequest(ctx, { userId: input.account.id, planId: plan.id, invoice, price: plan.price });
+  const claimedAt = await claimHandOver(ctx, requestId);
+  // Handed over before (asking again refreshed its details), or being handed over by a concurrent ask
+  // whose claim is younger than a minute.
+  if (claimedAt === null) return ok({ type: "requested" });
+  let started: Awaited<ReturnType<PaymentProvider["startPayment"]>>;
+  try {
+    started = await provider.startPayment(ctx, request);
+  } catch (error) {
+    await releaseHandOver(ctx, requestId, claimedAt);
+    throw error;
+  }
+  if (!started.ok) {
+    await releaseHandOver(ctx, requestId, claimedAt);
+    return started;
+  }
+  if (started.value.type !== "requested") throw new Error(`@softure-ai/billing: provider "${provider.name}" sets handsOverRequests but answered ${started.value.type}`);
+  await confirmHandOver(ctx, requestId);
+  return started;
+}