@pithy-sh/payments 0.1.0

package/src/data/purchase.ts

@@ -0,0 +1,131 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate, sqliteJson } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { PaymentsProductType } from "../config/config";
+import { PaymentsRail } from "./rail";
+import { PurchaseStatus } from "./status";
+import { PaymentsSubject } from "./subject";
+
+/**
+ * Which store environment a purchase happened in. Every purchase carries it, and it never widens: a
+ * sandbox StoreKit transaction reaching production must not grant a real entitlement, and granting one is
+ * the most common in-app-purchase security defect there is.
+ */
+export const PurchaseEnvironment = z
+  .enum(["production", "sandbox"])
+  .describe("The store environment a purchase happened in. A sandbox purchase never grants in production.");
+export type PurchaseEnvironment = z.infer<typeof PurchaseEnvironment>;
+
+/**
+ * What a purchase row *is* — the thing that grants access, or the thing that took the money.
+ *
+ * On three of the four rails these are one object and `charge` is the only value ever written: an Apple
+ * renewal, a Play renewal and a Stripe invoice each carry both the money and the subscription's state, so
+ * one row does both jobs and nothing needs distinguishing.
+ *
+ * Lemon Squeezy splits them, and splits them at the source. Its `subscription_*` webhooks carry a
+ * subscription object with the status and the renewal date and no charge; its `subscription_payment_*`
+ * webhooks carry an invoice with the money and no subscription state. Neither names the other's key —
+ * an LS subscription has no latest-invoice pointer — so collapsing them onto one row would mean inventing
+ * the missing pointer and stamping two different clocks into one monotonic watermark, which is exactly
+ * the ordering defect `providerEventAt` exists to prevent.
+ *
+ * So that rail writes two rows, and this field says which is which. **`state` never credits a ledger.**
+ * A `grants` clause fires once per paid provider transaction, and a subscription's state is not a
+ * transaction — without this discriminator a live subscription's honest `active` status passes
+ * `purchaseIsPaid` and every subscriber is credited once more than they paid for.
+ */
+export const PurchaseRole = z
+  .enum(["charge", "state"])
+  .describe(
+    "Whether this row records money moving (`charge`) or a subscription's standing (`state`). Only `charge` rows fulfill a `grants` clause. Every rail but Lemon Squeezy writes `charge` for everything.",
+  );
+export type PurchaseRole = z.infer<typeof PurchaseRole>;
+
+/** The raw verified provider payload — an object, whatever the rail's own shape. Retained as received. */
+const ProviderPayload = z
+  .record(z.string(), z.unknown())
+  .describe("The rail's verified response, as received. Shapes differ per rail, so only the envelope is fixed.");
+
+/**
+ * One provider transaction, as the projection of provider truth — the row in `pithy_payments_purchases`.
+ *
+ * `UNIQUE (rail, providerTransactionId)` is the idempotency guard all three write paths rely on: a client
+ * submission, a webhook, and a reconciliation pass produce the identical row, so a dropped client call
+ * costs nothing and a replayed webhook changes nothing.
+ *
+ * The owner is a **subject pair**, not a user id: the buyer is whoever the project bills, which under
+ * organization billing is the organization rather than the person who happened to click. Both columns are
+ * written together, and `data/subject.ts` states why either alone is ambiguous.
+ *
+ * `providerEventAt` is what makes the write monotonic. Providers do not guarantee delivery order, so an
+ * `expired` notification can arrive after the `renewed` that superseded it. Last-write-wins would
+ * silently revoke a paying subscriber, so the writer ignores any event staler than the row it is
+ * updating.
+ */
+export const PaymentsPurchase = z
+  .object({
+    id: z
+      .string()
+      .describe(
+        "The purchase's UUID. Text rather than an autoincrement integer because these surface in API responses, and sequential ids would leak order volume.",
+      ),
+    subjectType: PaymentsSubject.shape.subjectType.describe(
+      "Whether `subjectId` names a user or an organization. Half the owner — the id alone is ambiguous, so the two columns travel together.",
+    ),
+    subjectId: PaymentsSubject.shape.subjectId.describe(
+      "The subject that owns the purchase — the authenticated buyer, or the organization they bought for.",
+    ),
+    rail: PaymentsRail.describe("Which store this transaction came from."),
+    providerTransactionId: z
+      .string()
+      .describe("The rail's own transaction id. `UNIQUE (rail, providerTransactionId)` — the idempotency anchor."),
+    productId: z.string().describe("The logical catalog product id, from `products` in pithy.config.ts."),
+    providerProductId: z.string().describe("The rail's own SKU or price id, exactly as the provider presented it."),
+    type: PaymentsProductType.describe(
+      "The product type, copied from the catalog at projection time so a later config edit cannot rewrite history.",
+    ),
+    status: PurchaseStatus.describe("The normalized status. Nothing downstream ever sees a rail-specific state."),
+    role: PurchaseRole.default("charge").describe(
+      "Whether this row is the money or the subscription's standing. Defaults to `charge`, which is what every rail but Lemon Squeezy writes for every row.",
+    ),
+    environment: PurchaseEnvironment.describe(
+      "Which store environment the purchase happened in. Every purchase carries it: a sandbox StoreKit transaction reaching production must never grant a real entitlement.",
+    ),
+    purchasedAt: SQLiteDate.describe("When the store recorded the purchase."),
+    expiresAt: SQLiteDate.nullable().describe(
+      "When access lapses, or null for a purchase that never expires. Evaluated at read time as well as write time.",
+    ),
+    revokedAt: SQLiteDate.nullable().describe("When the purchase was refunded or revoked, or null."),
+    resumesAt: SQLiteDate.nullable().describe(
+      "When a paused subscription comes back, as the provider stated it — never computed. Null on a paused row means the provider said none, which is an indefinite pause; null everywhere else means the purchase is not paused, and the table's check constraint is what keeps those two apart. See `data/pause.ts`.",
+    ),
+    originalTransactionId: z
+      .string()
+      .nullable()
+      .describe("Chains renewals back to the transaction that started the subscription. Null for a one-time purchase."),
+    amountMinor: z
+      .number()
+      .int()
+      .nullable()
+      .describe(
+        "The amount charged, in the currency's minor unit — an integer, never a float. Nullable: not every rail reports it on every event.",
+      ),
+    currency: z
+      .string()
+      .nullable()
+      .describe("The ISO currency the amount is in, or null when the rail did not report one."),
+    providerEventAt: SQLiteDate.describe(
+      "The provider's own timestamp for the event that produced this row. The monotonic write rule compares against it, so out-of-order delivery cannot revoke a live subscription.",
+    ),
+    payload: sqliteJson(ProviderPayload).describe(
+      "The raw verified provider payload, Zod-validated on write and on read. Retained for reconciliation and audit.",
+    ),
+    createdAt: SQLiteDate.describe("When this row was first projected."),
+    updatedAt: SQLiteDate.describe("When this row was last projected."),
+  })
+  .describe("One verified provider transaction — the row in `pithy_payments_purchases`.");
+export type PaymentsPurchase = z.output<typeof PaymentsPurchase>;
+export type PaymentsPurchaseRow = z.input<typeof PaymentsPurchase>;

package/src/data/rail.ts

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The five payment rails, as one normalized name each. Nothing downstream of a rail's own module ever
+ * branches on a store's vocabulary — Apple's `originalTransactionId`, Google's `purchaseToken`, Stripe's
+ * `subscription` and Paddle's `sub_…` all arrive as a `(rail, providerTransactionId)` pair, which is what
+ * lets one projection serve five stores and one entitlement resolve across them.
+ *
+ * Adding a sixth rail (Amazon Appstore) is a member here plus a provider module. Nothing else in the
+ * package knows how many there are.
+ *
+ * `lemonSqueezy` and `paddle` are the two **merchants of record**: each owns the tax registration, the VAT
+ * thresholds, the invoices and the chargebacks, where the other three leave every one of those to the
+ * adopter. That is a commercial difference rather than a technical one, and the only place it shows in
+ * this package is that a refund can arrive with no local write preceding it — both issue them on their own.
+ */
+export const PaymentsRail = z
+  .enum(["apple", "google", "stripe", "lemonSqueezy", "paddle"])
+  .describe("Which store a transaction came from — Apple's App Store, Google Play, Stripe, Lemon Squeezy, or Paddle.");
+export type PaymentsRail = z.infer<typeof PaymentsRail>;
+
+/** Every rail, in a stable order — for iterating the catalog's per-rail blocks and cross-checking them. */
+export const PAYMENTS_RAILS: readonly PaymentsRail[] = PaymentsRail.options;
+
+/**
+ * The rails that sell in a browser — and mint a billing portal, which is the same statement.
+ *
+ * **One name, because it is one question.** {@link CheckoutRail} declares `createCheckoutSession` and
+ * `createPortalSession` together, so a rail cannot start a purchase on the web without also having a
+ * portal to send that buyer back to. "Sells in a browser" and "mints a portal we can link to" are not
+ * two lists that happen to match today; they are one list, held that way by an interface. Two names
+ * would suggest a divergence the type system does not permit, and the next person would have to read
+ * both to learn they are the same.
+ *
+ * The day a rail sells without a portal, `CheckoutRail` splits first — and `providers.test.ts`, which
+ * compares this list against the rails that actually satisfy `isCheckoutRail`, goes red. That is the
+ * moment a second name is earned, and it arrives with a failing test rather than a judgment call.
+ *
+ * **Enumerated rather than computed**, because nothing can compute it. A screen cannot construct a rail
+ * provider to discover what it implements, and `PaymentsRail.options` cannot answer it either — Apple and
+ * Google are rails and are not hosted. So it is a named subset with a gate over it, in both programs: this
+ * one, and its DOM-safe mirror in `src/client/api.ts`, which stays a hand-written union because pulling
+ * Zod into an adopter's browser program is what that file exists to avoid.
+ *
+ * Ordered, and the order is only used to make a refusal deterministic when a product sells on two rails
+ * and the caller named neither. See `checkoutRailFor`.
+ *
+ * **Extracted from {@link PaymentsRail} rather than spelled again.** A member misspelled here is a
+ * compile error rather than a rail that silently never matches, and the extraction is what lets the four
+ * schemas that narrow to this subset share one definition instead of four literals.
+ *
+ * **One subset, not two.** These are also exactly the rails that mint discount codes today, and both
+ * discount schemas narrow to this. A second constant would be a mirror with nothing to mirror. The day a
+ * rail mints and does not sell, or sells and does not mint, `providers.test.ts` disagrees with itself and
+ * the subset splits — with a failing test rather than a judgment call, which is the same bargain
+ * `CheckoutRail` makes for selling and portal-minting.
+ */
+export const PaymentsHostedRail = PaymentsRail.extract(["stripe", "lemonSqueezy", "paddle"]).describe(
+  "Which hosted rail — the three that sell in a browser, mint a portal, and mint a discount code.",
+);
+export type PaymentsHostedRail = z.infer<typeof PaymentsHostedRail>;
+
+/**
+ * The same three as a plain array, for the callers that iterate rather than parse.
+ *
+ * Derived from the schema rather than written beside it. Four request and response schemas wrote this
+ * subset out by hand and Paddle reached none of them (#465), so a rail that sold, minted portals and minted
+ * discount codes was a 400 at every point a caller had to name it. One list, one edit — and
+ * `providers.test.ts` holds it to the rails that satisfy the interfaces at runtime, in both directions.
+ */
+export const PAYMENTS_HOSTED_RAILS: readonly PaymentsRail[] = PaymentsHostedRail.options;

package/src/data/reconcileRun.ts

@@ -0,0 +1,208 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { D1Database } from "@cloudflare/workers-types";
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { withD1Retry } from "@pithy-sh/core/src/data/withD1Retry";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import { PurchaseEnvironment } from "./purchase";
+import { PaymentsRail } from "./rail";
+import { PAYMENTS_RECONCILE_RUNS_TABLE, paymentsDatabase } from "./tables";
+
+/**
+ * One reconciliation pass, kept — the row in `pithy_payments_reconcile_runs`.
+ *
+ * **Reconciliation is the compensating control for a delivery mechanism that is known to fail.** Webhooks are
+ * dropped, delayed and delivered out of order, which is the whole reason the pass exists. So the run that
+ * *repaired* something is the most operationally valuable event this capability produces: it is the proof that
+ * a delivery went missing and that a customer was briefly wrong.
+ *
+ * Before this table, that was unobservable after the fact. The pass wrote its tally to a `Logger` and its
+ * repairs to an `AuditEmit`, and *"has reconciliation been running"* had no answer but reading logs, while
+ * *"what did it fix last month"* had none at all. An adopter could not tell a healthy integration from one
+ * whose cron stopped firing, because a silent nightly job and a job that is not running look identical.
+ *
+ * ## A run is a summary, not a second audit trail
+ *
+ * An audit event is one thing that happened; a run is the statement over many — started, finished, how much
+ * was compared, how much was repaired, what failed. That tally cannot be reconstructed by grouping events,
+ * because nothing in the events says where one pass ended and the next began.
+ *
+ * So the repairs stay in the audit trail, once, and **the run points at them rather than copying them**: the
+ * run's `id` travels on every `payments/purchase_reconciled` event the pass emits, as `runId`. Copying the
+ * repairs here would build a second, weaker copy of the trail inside a table with different access rules —
+ * the mistake `admin/coverage.ts` refuses on the webhook log for the same reason.
+ *
+ * ## A clean run is stored
+ *
+ * *"It ran and found nothing"* is the answer to *"is it healthy"*. Storing only the passes that repaired
+ * something would make silence ambiguous — indistinguishable from a cron that stopped firing, which is
+ * precisely the failure this table exists to make visible.
+ *
+ * ## Retention
+ *
+ * {@link RECONCILE_RUN_RETENTION_DAYS} days, pruned by the writer on every run. Runs are small and frequent —
+ * a daily cron is one row a day — so the table is bounded by the schedule rather than by the catalog, and a
+ * ninety-day window covers "did it run last quarter" while never growing without limit. It is stated here and
+ * enforced in {@link recordReconcileRun}, rather than left to be discovered when a table is large.
+ *
+ * ## No provider payload, and structurally so
+ *
+ * Every field below is a count, a timestamp, an enum or this deployment's own id. There is no column a
+ * store's response could be written into, so a run record cannot carry one — the same control
+ * `admin/read.ts` applies to a purchase by never selecting `payload`, taken one step further by never
+ * having the column.
+ */
+
+/** How long a run record is kept. Days, pruned by the writer — see the module doc. */
+export const RECONCILE_RUN_RETENTION_DAYS = 90;
+
+/** One reconciliation pass, as stored. `z.output` is the app shape; `z.input` is the SQLite row. */
+export const PaymentsReconcileRun = z
+  .object({
+    id: z.string().describe("The run's UUID. Travels on every repair the pass audits, as `runId`."),
+    startedAt: SQLiteDate.describe("When the pass began, from the run's own clock."),
+    finishedAt: SQLiteDate.describe("When the pass finished. Equal to `startedAt` for a run that read nothing."),
+    environment: PurchaseEnvironment.describe(
+      "The store environment the host was deployed to. A sandbox pass and a production pass are different facts about different money, and a table that mixed them would answer the health question wrong.",
+    ),
+    rail: PaymentsRail.nullable().describe(
+      "The single store this pass was narrowed to, or null for every enabled rail. Null is the scheduled behavior; a value means somebody ran it by hand against one store.",
+    ),
+    pages: z.number().int().describe("Durable steps read — one per page of purchases."),
+    scanned: z.number().int().describe("Purchases examined."),
+    unchanged: z.number().int().describe("Purchases whose stored state already matched the store's."),
+    drifted: z
+      .number()
+      .int()
+      .describe(
+        "Purchases whose stored state disagreed and was repaired. The number that matters: a rising one means webhooks are being lost.",
+      ),
+    superseded: z
+      .number()
+      .int()
+      .describe(
+        "Old periods a later transaction has replaced, settled on this pass. Falls back to zero once a catalog's history has been walked once, which is why it is counted apart from `drifted`.",
+      ),
+    skipped: z
+      .number()
+      .int()
+      .describe("Purchases no store could be asked about — a rail switched off, or unaddressable."),
+    failed: z
+      .number()
+      .int()
+      .describe(
+        "Purchases a store refused to answer for. Counted rather than thrown, so one bad row cannot end a pass.",
+      ),
+    truncated: SQLiteBoolean.describe(
+      "Whether the pass stopped at its page cap with catalog left unread. True means the tally is a floor, not a total.",
+    ),
+    dryRun: SQLiteBoolean.describe(
+      "Whether this pass only reported. A dry run repairs nothing, so its `drifted` is a finding rather than a fix.",
+    ),
+    createdAt: SQLiteDate.describe("When this row was written."),
+  })
+  .describe(
+    "One reconciliation pass — when it ran, what it was narrowed to, and its tally. Never a provider payload: there is no column for one.",
+  );
+export type PaymentsReconcileRun = z.output<typeof PaymentsReconcileRun>;
+export type PaymentsReconcileRunRow = z.input<typeof PaymentsReconcileRun>;
+
+/** What the pass hands the writer. The row, minus the two fields the writer owns. */
+export interface ReconcileRunInput {
+  /** The run's id — minted before the pass so the repairs it audits can name it. */
+  id: string;
+  /** When the pass began. */
+  startedAt: Date;
+  /** When it finished. */
+  finishedAt: Date;
+  /** The deployment's store environment. */
+  environment: PurchaseEnvironment;
+  /** The rail the pass was narrowed to, or null for every enabled one. */
+  rail: PaymentsRail | null;
+  /** The tally, as `reconcilePayments` reports it. */
+  report: {
+    pages: number;
+    scanned: number;
+    unchanged: number;
+    drifted: number;
+    superseded: number;
+    skipped: number;
+    failed: number;
+    truncated: boolean;
+    dryRun: boolean;
+  };
+}
+
+/**
+ * Write one run record, and prune the ones past retention.
+ *
+ * Idempotent on the run's id: a Workflow step that wrote the row and then failed to journal its result
+ * replays the whole body, and a second insert for one pass would make the health read count a pass twice.
+ * `ON CONFLICT (id) DO UPDATE` is what makes the replay land on the same row it already wrote.
+ *
+ * The prune shares the write rather than living in a second scheduled job, because a job that prunes is a job
+ * that can stop — and the only thing that ever writes here is the thing that would then also stop pruning.
+ * Retention is therefore a property of the writer, and a table nobody writes to does not grow.
+ */
+export async function recordReconcileRun(
+  d1: D1Database,
+  input: ReconcileRunInput,
+  options: { now?: Date; retentionDays?: number } = {},
+): Promise<PaymentsReconcileRun> {
+  const now = options.now ?? new Date();
+  const retentionDays = options.retentionDays ?? RECONCILE_RUN_RETENTION_DAYS;
+  const db = paymentsDatabase(d1);
+  const row = PaymentsReconcileRun.encode({
+    id: input.id,
+    startedAt: input.startedAt,
+    finishedAt: input.finishedAt,
+    environment: input.environment,
+    rail: input.rail,
+    ...input.report,
+    createdAt: now,
+  });
+
+  await withD1Retry(() =>
+    db
+      .insertInto(PAYMENTS_RECONCILE_RUNS_TABLE)
+      // biome-ignore lint/suspicious/noExplicitAny: the row is the schema's z.input side; Kysely's insert type derives from it.
+      .values(row as any)
+      .onConflict((oc) =>
+        oc.column("id").doUpdateSet({
+          finishedAt: row.finishedAt,
+          pages: row.pages,
+          scanned: row.scanned,
+          unchanged: row.unchanged,
+          drifted: row.drifted,
+          superseded: row.superseded,
+          skipped: row.skipped,
+          failed: row.failed,
+          truncated: row.truncated,
+          dryRun: row.dryRun,
+          // biome-ignore lint/suspicious/noExplicitAny: as above — an encoded row, not the app shape.
+        } as any),
+      )
+      .execute(),
+  );
+
+  const cutoff = new Date(now.getTime() - retentionDays * 86_400_000);
+  await withD1Retry(() =>
+    db.deleteFrom(PAYMENTS_RECONCILE_RUNS_TABLE).where("startedAt", "<", SQLiteDate.encode(cutoff)).execute(),
+  );
+
+  const written = await db
+    .selectFrom(PAYMENTS_RECONCILE_RUNS_TABLE)
+    .selectAll()
+    .where("id", "=", input.id)
+    .executeTakeFirst();
+  if (written === undefined) {
+    throw new InternalError({
+      message: "The reconciliation run could not be recorded.",
+      action: "Retry. If it persists, check the app database for the pithy_payments_* tables.",
+      detail: `Wrote reconcile run ${input.id} but could not read it back.`,
+    });
+  }
+  return PaymentsReconcileRun.parse(written);
+}

package/src/data/renderMoney.ts

@@ -0,0 +1,180 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { DEFAULT_LOCALE } from "@pithy-sh/core/src/i18n/translator";
+import { minorUnitDigits } from "./money";
+
+/**
+ * An integer in a currency's minor unit, as a sentence a customer reads — `6582` to `$65.82`.
+ *
+ * ## Why this exists at all, when `client/paddle.ts` says never to format a price
+ *
+ * That rule stands, and this does not break it: **it never decides an amount.** Paddle's integer goes in
+ * and comes back out, digit for digit, with a separator placed and a symbol attached. Nothing here
+ * divides, rounds, sums or nets, and the minor amount stays on the shape beside the string, so a consumer
+ * that wants the integer still gets the integer (see `QuotedMoney`).
+ *
+ * The reason the kit gave for never doing this was wrong, and it was measured wrong on 2026-08-28 (#465).
+ * `client/paddle.ts` argued that `Intl.NumberFormat` "would have to carry a table of which currencies have
+ * two decimals, and would get one wrong". It carries exactly that table, from CLDR, and it is right about
+ * the zero-decimal currencies: `resolvedOptions().maximumFractionDigits` answers 2 for `USD` and `GBP` and
+ * 0 for `JPY`, `KRW` and `CLP`. Paddle's own documentation instructs adopters to do this — "use a currency
+ * library to format monetary values to the correct number of decimals… symbols and decimal separators are
+ * placed correctly" (api-reference/about/data-types) — and offers `formatted_totals` only on the
+ * pricing-preview endpoint, "for convenience". `subscriptions.preview` and `transactions.preview` return no
+ * formatted field at any depth, verified against the recordings. So a plan-change quote has minor units or
+ * it has nothing, and a confirmation screen with no figure on it is a customer agreeing to an amount they
+ * were never shown.
+ *
+ * ## The exponent is the store's, and `Intl`'s own is not it
+ *
+ * This is the part the correction above would get wrong if it stopped one sentence early. **CLDR's
+ * fraction digits are a display convention, not the denomination the money arrived in**, and they are
+ * maintained by different people for a different purpose.
+ *
+ * The example this originally carried was wrong and is worth keeping as the correction. It claimed
+ * `Intl` renders 6582 forint as `66 Ft`, from CLDR giving `HUF` no fraction. CLDR carries **two**
+ * fraction tables — standard digits, and `cashDigits` for rounding physical currency — and `HUF` and
+ * `COP` are zero only in the second. `Intl.NumberFormat` reads the first, answers 2 for both, and
+ * renders `65,82 Ft`. Re-measured on ICU 75.1: across every code this package can be paid in, CLDR and
+ * ISO 4217 agree on all of them, so there is no live divergence to point at.
+ *
+ * The pinning stays anyway, and agreement today is the reason it is cheap rather than the reason to
+ * drop it: `Intl` is asked for a symbol and separators, and a renderer that let it choose the exponent
+ * would be taking the denomination from a table that can move under a runtime upgrade.
+ *
+ * So the digits come from {@link minorUnitDigits} — ISO 4217, the table this package already converts
+ * every rail's amounts through and the one `client/wholeUnits.ts` already trusts against Paddle's own
+ * strings — and `Intl` is **pinned** to it on both ends. `Intl` decides the symbol, the separators, the
+ * grouping and the placement; it does not decide how much money this is.
+ *
+ * ## The scaling is a string operation, deliberately
+ *
+ * `9007199254740991 / 100` is `90071992547409.9` in binary floating point — a cent, gone, on the largest
+ * figure this package can hold. `Intl.NumberFormat.prototype.format` accepts a decimal **string** (ES2023,
+ * and available in Workers and Node 22 alike), so the point is placed by moving characters and the digits
+ * that arrived are the digits that render. There is no arithmetic to be wrong.
+ *
+ * ## Where the locale comes from
+ *
+ * Not from here, and not from a request field. `Translator.formattingLocale` — `c.var.t` on every route —
+ * is what the kit already negotiates per reader, and `@pithy-sh/email` sets the precedent by building a
+ * per-recipient translator from a stored locale rather than inventing a second rule. This module takes
+ * that string as a value, which is the seam's stated contract for exactly this case: "an adopter who
+ * already owns their date and number rendering needs the locale as a *value* to hand to `Intl`".
+ *
+ * When nothing resolves it, the answer is {@link RENDER_FALLBACK_LOCALE} and it is *stated*: a quote
+ * rendered in the wrong language is recoverable, and a quote with no figure on it is not.
+ */
+
+/**
+ * The language a figure is rendered in when the reader's own did not resolve.
+ *
+ * Core's `DEFAULT_LOCALE` rather than a second constant: it is already the locale a project falls back to
+ * and the one the kit writes in, and two answers to "what language when we do not know" is how a screen
+ * ends up in one and its money in another.
+ */
+export const RENDER_FALLBACK_LOCALE = DEFAULT_LOCALE;
+
+/**
+ * A currency code `Intl` can be asked about at all: three ASCII letters, which is every code ISO 4217
+ * issues.
+ *
+ * **The shape, deliberately, and not a list of codes.** `Intl` throws a `RangeError` only on a code that is
+ * not well-formed; a well-formed one nobody has heard of renders with the code itself standing in for the
+ * symbol, which is the honest answer and is what CLDR does for `XTS`. A second allowlist of currencies here
+ * would be a table to keep current and a way for a real currency to become unrenderable.
+ */
+const CURRENCY_CODE = /^[A-Za-z]{3}$/;
+
+/**
+ * `Intl.NumberFormat` with the `format` signature the runtime actually has.
+ *
+ * ES2023 — "NumberFormat V3" — widened `format` to accept a decimal **string**, and V8 has shipped it for
+ * years: it is what Workers and Node 22 both do, and `renderMoney.test.ts` proves it by asserting the
+ * cent that a `number` loses at the top of the safe-integer range. This repository compiles against
+ * `lib: ["ES2022"]`, whose declaration stops at `number | bigint` — and moving to TypeScript's own ES2023
+ * declaration would not help: it widens `format` to the template literal type `` `${number}` ``, which a
+ * string assembled at runtime is never assignable to.
+ *
+ * So the runtime's signature is named here, once, behind one assertion — rather than moving every
+ * package's `lib` for a single call, or passing a `number` and losing the digit the string exists to keep.
+ */
+interface DecimalFormatter {
+  /** The amount, as a decimal string in whole units — `"65.82"`, `"-6582"`, `"0.007"`. */
+  format(value: string): string;
+}
+
+/**
+ * The amount as a decimal string, with the point moved `digits` places left.
+ *
+ * Lexical from end to end. The caller's integer is documented as a safe integer — `minorAmount` refuses
+ * anything else and `QuotedMoney` refuses a float — and when that is violated the split produces a string
+ * `Intl` renders as `NaN`. That is the intended direction of the failure: loud, and impossible to mistake
+ * for a figure, where a rounded or truncated one would be a wrong number nobody notices.
+ */
+function decimalOf(amountMinor: number, digits: number): string {
+  const sign = amountMinor < 0 ? "-" : "";
+  const magnitude = String(Math.abs(amountMinor));
+  if (digits === 0) return `${sign}${magnitude}`;
+  const padded = magnitude.padStart(digits + 1, "0");
+  const point = padded.length - digits;
+  return `${sign}${padded.slice(0, point)}.${padded.slice(point)}`;
+}
+
+/**
+ * `amountMinor` of `currency`, rendered for a reader of `locale` — or `null` when the currency cannot be
+ * named.
+ *
+ * Null rather than a guess, which is the idiom `minorAmount` and `minorUnitsFromScaled` already set in this
+ * package: a store that answered `"dollars"` where a currency goes has answered with something no amount can
+ * be denominated in, and the caller refuses the whole quote on it rather than letting a `RangeError` out of
+ * `Intl` reach a confirmation screen as a 500. A **locale** `Intl` refuses is the other case entirely, and
+ * costs the reader only their language — see {@link RENDER_FALLBACK_LOCALE}.
+ *
+ * `locale` is optional so that a caller with nothing to pass writes nothing, rather than writing `"en"` at
+ * a call site and putting the fallback in two places.
+ */
+export function renderMoney(amountMinor: number, currency: string, locale?: string): string | null {
+  if (!CURRENCY_CODE.test(currency)) return null;
+  const digits = minorUnitDigits(currency);
+  const options: Intl.NumberFormatOptions = {
+    style: "currency",
+    // Uppercased only here. Lowercase is how this package stores a currency, and `Intl` accepts either —
+    // but the ISO spelling is what a reader of this line should see being handed over.
+    currency: currency.toUpperCase(),
+    // Pinned to the store's denomination on both ends, so `Intl` cannot round a figure off a quote. See
+    // the module note: CLDR would render `HUF` and `COP` with no fraction at all.
+    minimumFractionDigits: digits,
+    maximumFractionDigits: digits,
+  };
+  return formatter(options, locale).format(decimalOf(amountMinor, digits));
+}
+
+/**
+ * A formatter for `locale`, or one for {@link RENDER_FALLBACK_LOCALE} when `locale` is not a tag `Intl`
+ * accepts.
+ *
+ * The chain negotiates and canonicalizes every reader-supplied tag before it reaches a route, so the only
+ * way an unconstructible one arrives here is an adopter's own configured default. That is a mistake worth
+ * surviving rather than raising through a confirmation screen: the fallback keeps the amount readable and
+ * the misconfiguration is visible in the language, not in a 500.
+ *
+ * The fallback formatter cannot throw in turn — the currency was checked before this was called, and
+ * `RENDER_FALLBACK_LOCALE` is a constant.
+ */
+function formatter(options: Intl.NumberFormatOptions, locale: string | undefined): DecimalFormatter {
+  if (locale !== undefined && locale !== "") {
+    try {
+      return decimalFormatter(locale, options);
+    } catch {
+      // A `RangeError` from a malformed tag. Nothing else here can throw, and the reader still gets a figure.
+    }
+  }
+  return decimalFormatter(RENDER_FALLBACK_LOCALE, options);
+}
+
+/** The one assertion in this module. See {@link DecimalFormatter} for what it asserts and what proves it. */
+function decimalFormatter(locale: string, options: Intl.NumberFormatOptions): DecimalFormatter {
+  return new Intl.NumberFormat(locale, options) as unknown as DecimalFormatter;
+}

package/src/data/status.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+
+/**
+ * The normalized purchase status set. Each rail's events map into these nine, so nothing downstream of
+ * a rail module ever sees `DID_RENEW`, `SUBSCRIPTION_ON_HOLD`, or `invoice.payment_failed`.
+ *
+ * The set is deliberately about *state*, not about the event that produced it: a projection is keyed on a
+ * transaction, and a transaction has one current state however many notifications described it.
+ *
+ * ## Two endings, and the difference between them is the money
+ *
+ * **`expired` is a period we were paid for, ended.** A subscription that ran its course, a Stripe
+ * subscription Stripe closed, an Apple period past its `expiresDate`. It grants no access — the period is
+ * over — but it **credits**, because the invoice behind it cleared.
+ *
+ * **`never_paid` is a purchase that terminated before any money moved.** A delayed-payment checkout whose
+ * bank debit bounced, a Stripe subscription abandoned at `incomplete_expired`, a Play deferred purchase
+ * canceled before payment. It grants nothing and credits nothing, and no clawback ever follows one, because
+ * there is no payment to reverse. Leaning on `expired` for these is how a coin pack gets handed out for money
+ * that never arrived — see `UNPAID_STATUSES` in `grants/apply.ts`. Apple maps nothing here: StoreKit issues
+ * no transaction until the money moves.
+ */
+export const PurchaseStatus = z
+  .enum(["active", "in_grace", "on_hold", "canceled", "expired", "never_paid", "refunded", "revoked", "paused"])
+  .describe(
+    "The normalized purchase status. `active` is paid and current; `in_grace` is a failed renewal still inside the retry window; `on_hold` is a failed renewal past it; `canceled` is auto-renew turned off with the paid period still running; `expired` is a period we were paid for that has lapsed; `never_paid` terminated before any money cleared, so it credits nothing; `refunded` and `revoked` were taken back; `paused` is a subscription the user suspended.",
+  );
+export type PurchaseStatus = z.infer<typeof PurchaseStatus>;
+
+/**
+ * The statuses a purchase can grant access from — the candidate set the projection's SQL filters on
+ * before the expiry check. `in_grace`'s membership is then narrowed per project by
+ * {@link statusGrantsAccess}, so this set and that predicate must stay in step; a test asserts both.
+ *
+ * **`canceled` still grants**, and it is the member most often got wrong. A user who turns off
+ * auto-renew has not lost access — they have declined the *next* period. The period they paid for runs
+ * to its end, and `expiresAt` is what ends it.
+ */
+export const ACCESS_GRANTING_STATUSES: ReadonlySet<PurchaseStatus> = new Set<PurchaseStatus>([
+  "active",
+  "in_grace",
+  "canceled",
+]);
+
+/**
+ * Whether a purchase in this status grants its entitlements, given the project's grace policy. The
+ * expiry check is separate and applied alongside it — a status says whether the purchase is still
+ * standing, `expiresAt` says whether the period it paid for is over.
+ *
+ * `in_grace` granting access is the point of grace: a failed card should not lock a paying subscriber
+ * out mid-period. It is a described config flag rather than hardcoded policy because an app that sells
+ * something expensive may reasonably decide otherwise. `on_hold` never grants — by then the retry window
+ * is exhausted and the renewal has genuinely failed. `never_paid` never grants either, and never can: it
+ * says no money ever moved.
+ */
+export function statusGrantsAccess(status: PurchaseStatus, graceGrantsAccess: boolean): boolean {
+  if (status === "in_grace") return graceGrantsAccess;
+  return ACCESS_GRANTING_STATUSES.has(status);
+}
+
+/** The statuses that grant access under this project's grace policy — what the projection's SQL filters on. */
+export function grantingStatuses(graceGrantsAccess: boolean): PurchaseStatus[] {
+  return [...ACCESS_GRANTING_STATUSES].filter((status) => statusGrantsAccess(status, graceGrantsAccess));
+}