@pithy-sh/payments 0.1.0

package/src/data/discount.ts

@@ -0,0 +1,238 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { JsonDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+
+/**
+ * A discount, normalized — and every field here is named for **what it means to a customer's bill**, not for
+ * what either provider calls it.
+ *
+ * That is the whole design constraint, and it is not a style preference. Stripe and Lemon Squeezy agree on
+ * the concept of a discount and disagree on nearly every field, in ways that are invisible until somebody is
+ * charged the wrong amount:
+ *
+ * - **Duration.** Stripe's `duration_in_months` counts *months*. Lemon Squeezy's equivalent counts *billing
+ *   periods*. On a monthly plan they coincide. On an annual one, `12` means a year on one rail and twelve
+ *   years on the other — a decade of a discount nobody offered.
+ * - **Expiry.** On one rail the date stops *redemption*: after it the code cannot be claimed, and anyone
+ *   already holding it keeps their discount. On the other the same-looking field can stop *the discount
+ *   itself*, changing an existing customer's next invoice.
+ * - **Amount.** A fixed amount carries a currency and a percentage does not, and a fixed amount against a
+ *   subscription in another currency is a provider error at *redemption* — so the failure arrives at the
+ *   customer rather than at the adopter who created it.
+ *
+ * So this module models the customer-visible fact and each rail translates into its own vocabulary, with
+ * fixtures pinning the *meaning* rather than the field name. Where a translation needs something neither
+ * provider's create call carries — the plan's billing interval — it is required here rather than guessed,
+ * because guessing is the defect.
+ *
+ * **Pithy never computes a discounted amount.** The provider is the authority on what is owed; a second
+ * calculation here would be a second answer to the one question a customer checks against their statement.
+ * Everything in this module describes a discount's *terms*, never its arithmetic.
+ */
+
+/** The longest a discount code may be. Both providers are more generous; this is a legibility bound. */
+const MAX_CODE_LENGTH = 64;
+
+/** A discount code, as a customer types it. Case is preserved — both providers match case-insensitively. */
+export const DiscountCode = z
+  .string()
+  .min(1)
+  .max(MAX_CODE_LENGTH)
+  .regex(/^[A-Za-z0-9_-]+$/, "A discount code is letters, digits, underscores and dashes.")
+  .describe(
+    "The code a customer enters at checkout. Constrained to what both stores accept, so a code this project mints is redeemable on either rail.",
+  );
+export type DiscountCode = z.infer<typeof DiscountCode>;
+
+/**
+ * How much comes off — a percentage, or a fixed amount in a named currency.
+ *
+ * Discriminated rather than two optional fields, because the currency is meaningful for exactly one of them
+ * and meaningless for the other. A percentage with a currency would be a value nothing could act on.
+ */
+export const DiscountAmount = z
+  .discriminatedUnion("kind", [
+    z
+      .strictObject({
+        kind: z.literal("percent").describe("A percentage off, which carries no currency."),
+        percent: z
+          .number()
+          .positive()
+          .max(100)
+          .describe("How many percent off, 0 exclusive to 100 inclusive. 100 is a comped period, which is legal."),
+      })
+      .describe("A percentage off — the portable kind, which works whatever a subscription is priced in."),
+    z
+      .strictObject({
+        kind: z.literal("fixed").describe("A fixed amount off, which is only meaningful in a stated currency."),
+        amountMinor: z
+          .number()
+          .int()
+          .positive()
+          .describe("How much off, as an integer in the currency's minor unit. Never a float."),
+        currency: z
+          .string()
+          .regex(/^[a-z]{3}$/, "An ISO 4217 currency code is three lowercase letters.")
+          .describe(
+            "The currency the amount is in. A fixed amount against a subscription priced in another currency is refused before creation, because at the provider it would fail at redemption — in front of the customer.",
+          ),
+      })
+      .describe("A fixed amount off, in one currency and no other."),
+  ])
+  .describe(
+    "How much a discount takes off a bill. Strict on both members: a currency on a percentage is a value nothing can act on, and silently dropping it would leave an adopter believing they had set something.",
+  );
+export type DiscountAmount = z.infer<typeof DiscountAmount>;
+
+/**
+ * How long the discount lasts, in **billing periods** — the unit the customer experiences.
+ *
+ * Periods rather than months, because a period is what a customer sees on their statement: "the first twelve
+ * renewals are cheaper" means the same thing on a monthly plan and an annual one. Months are Stripe's
+ * internal unit and mean something different on an annual plan; translating into them is the Stripe rail's
+ * job, and {@link DiscountTerms.billingInterval} is what makes that translation possible rather than a guess.
+ */
+export const DiscountDuration = z
+  .discriminatedUnion("kind", [
+    z
+      .object({ kind: z.literal("once").describe("One billing period, then list price.") })
+      .describe("A single period's discount — a launch offer on the first invoice."),
+    z
+      .object({ kind: z.literal("forever").describe("Every period, for as long as the subscription runs.") })
+      .describe("A permanent rate. Nothing lapses, so nothing surprises anyone later."),
+    z
+      .object({
+        kind: z.literal("repeating").describe("A fixed number of billing periods, then list price."),
+        billingPeriods: z
+          .number()
+          .int()
+          .positive()
+          .describe(
+            "How many billing periods the discount applies to, counted the way a customer counts renewals. Twelve on a monthly plan is a year; twelve on an annual plan is twelve years.",
+          ),
+      })
+      .describe("A rate that lapses — the one whose end date a customer must be told about."),
+  ])
+  .describe("How long a discount lasts, in billing periods.");
+export type DiscountDuration = z.infer<typeof DiscountDuration>;
+
+/** How often the plan this discount is for renews. Required only to translate a repeating duration. */
+export const BillingInterval = z
+  .enum(["month", "year"])
+  .describe(
+    "How often the subscription this discount is meant for renews. Required for a repeating discount, because Stripe counts its duration in months and Lemon Squeezy counts it in periods — so without it, `12` on an annual plan is a year on one rail and twelve years on the other.",
+  );
+export type BillingInterval = z.infer<typeof BillingInterval>;
+
+/**
+ * Everything that decides what a discount does. The shape both rails are created from.
+ *
+ * Deliberately not a mirror of either provider's create body: the fields it does not have are as considered
+ * as the ones it does. There is no "applies to these products" — that is a commercial policy an adopter owns
+ * — and no "first-time customers only", which the two stores model incompatibly enough that supporting it
+ * would mean promising behavior on one rail we could not deliver on the other.
+ */
+export const DiscountTerms = z
+  .object({
+    code: DiscountCode.optional().describe(
+      "The code to mint, or omit it and let the store generate one. Supplying it is what lets an adopter mint one code per applicant against their own record of who was offered it.",
+    ),
+    amount: DiscountAmount.describe("How much comes off."),
+    duration: DiscountDuration.describe("How long it lasts, in billing periods."),
+    billingInterval: BillingInterval.optional().describe(
+      "How often the plan renews. Required when `duration` is `repeating`, and refused otherwise — a duration that does not lapse has nothing to count.",
+    ),
+    maxRedemptions: z
+      .number()
+      .int()
+      .positive()
+      .optional()
+      .describe(
+        "How many times the code may be claimed in total, or omit for unlimited. It guards the customer path and only the customer path: the store counts a redemption when a checkout or a transaction uses the code and refuses the next one past the limit, and it holds when a webhook never arrives because the count is the store's rather than ours. It does not guard an administrative application against an existing subscription. Measured against the Paddle sandbox on 2026-08-14: a code with `usage_limit: 1` was applied to two subscriptions with `times_used` still `0`, went to `1` only when a transaction billed under it completed, and refused the next transaction after that. Stripe and Lemon Squeezy are unmeasured, so assume the same of them. So a staff comp applied by updating a subscription is not stopped here, and an adopter's own record of who was offered a code is the only thing that would stop it.",
+      ),
+    redeemableUntil: JsonDate.optional().describe(
+      "After this moment the code can no longer be *claimed*. It does not end a discount already applied: a customer who redeemed it yesterday keeps their rate for its full duration. Named for that meaning because the providers' own fields do not agree on it, and a fixture pins each rail against a code already redeemed.",
+    ),
+  })
+  .describe("The terms of a discount, in customer-visible units, from which either rail can create one.")
+  .check((ctx) => {
+    const terms = ctx.value;
+
+    // The one cross-field rule, and the reason it exists is the annual-plan mistranslation above.
+    if (terms.duration.kind === "repeating" && terms.billingInterval === undefined) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["billingInterval"],
+        message:
+          "A repeating discount must state the plan's `billingInterval`. Stripe counts a duration in months and Lemon Squeezy counts it in billing periods, so without it the same number means a year on one rail and twelve years on the other.",
+      });
+    }
+
+    if (terms.duration.kind !== "repeating" && terms.billingInterval !== undefined) {
+      ctx.issues.push({
+        code: "custom",
+        input: ctx.value,
+        path: ["billingInterval"],
+        message:
+          "`billingInterval` is only meaningful for a `repeating` duration. A discount that runs once or forever has no periods to count.",
+      });
+    }
+  });
+export type DiscountTerms = z.output<typeof DiscountTerms>;
+export type DiscountTermsInput = z.input<typeof DiscountTerms>;
+
+/** A discount as a store created it: the terms we asked for, plus what the store decided. */
+export const CreatedDiscount = z
+  .object({
+    code: DiscountCode.describe("The code a customer enters — the one supplied, or the one the store generated."),
+    providerDiscountId: z
+      .string()
+      .min(1)
+      .describe("The store's own id for the object, so an adopter can find it in their dashboard."),
+    terms: DiscountTerms.describe("The terms it was created with, echoed back as this package models them."),
+  })
+  .describe("A discount that now exists at a store.");
+export type CreatedDiscount = z.output<typeof CreatedDiscount>;
+
+/**
+ * What a subscription is paying now, what it becomes, and when — the half that stops a bill changing
+ * unannounced.
+ *
+ * A capability that can apply a discount but not report its end date has shipped the half that creates the
+ * surprise: a discount that silently lapses is a customer's bill changing on a Tuesday with nothing having
+ * told them, and from where they sit that is indistinguishable from a billing error.
+ *
+ * Every amount here comes from the provider. Nothing in this package multiplies a price by a percentage.
+ */
+export const SubscriptionPricing = z
+  .object({
+    currency: z
+      .string()
+      .nullable()
+      .describe("The currency both amounts are in, or null when the store did not report one."),
+    currentAmountMinor: z
+      .number()
+      .int()
+      .nonnegative()
+      .nullable()
+      .describe("What the next invoice comes to under any discount in force, as the store computed it."),
+    listAmountMinor: z
+      .number()
+      .int()
+      .nonnegative()
+      .nullable()
+      .describe(
+        "What it comes to once the discount ends — the list price. Equal to `currentAmountMinor` when no discount is in force.",
+      ),
+    discountCode: DiscountCode.nullable().describe(
+      "The code in force, or null when the subscription is at list price.",
+    ),
+    discountEndsAt: JsonDate.nullable().describe(
+      "When the current discount stops applying, or null — which means either no discount or one that runs forever. A screen must say which, so read it beside `discountCode`.",
+    ),
+  })
+  .describe("What a subscription pays now, what it will pay, and when that changes.");
+export type SubscriptionPricing = z.output<typeof SubscriptionPricing>;

package/src/data/entitlement.ts

@@ -0,0 +1,67 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteBoolean, SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { EntitlementKey } from "@pithy-sh/core/src/entitlement/entitlement";
+import { z } from "zod";
+import { PaymentsSubject } from "./subject";
+
+/**
+ * One entitlement a subject holds — the row in `pithy_payments_entitlements`, and the materialized read
+ * model `requireEntitlement()` hits. `UNIQUE (subjectType, subjectId, entitlement)`: one row per subject
+ * per key, whichever purchase currently grants it.
+ *
+ * **The holder is the pair, never the id alone.** Nothing in the kit keeps an organization id from
+ * equalling some user's id, so a key of `(subjectId, entitlement)` would let one holder read the other's
+ * grant. Both subject columns lead the unique, ahead of the key, so the per-subject read — every
+ * entitlement one holder has — is a covering prefix of the same index rather than an index of its own.
+ * The two columns are written together and compared together; see `data/subject.ts` for why.
+ *
+ * They are `PaymentsSubject`'s own fields rather than a second pair spelled the same way, so a row cannot
+ * carry an id the pair itself would refuse.
+ *
+ * The row **is** stored (issue #79 decision 5) — resolving entitlements per request from a KV cache or a
+ * token claim would make a revocation eventually-consistent, and a revocation must be immediate. What it
+ * is never stored *independently of* is the purchase state that produced it: only the projection writes
+ * this table, and it re-derives every affected row inside the same transaction as the purchase write.
+ *
+ * `active` and `expiresAt` are both here, and both matter. The flag is an optimization the projection
+ * wrote; the timestamp is the truth. A subscription can lapse with no notification arriving at all, so the
+ * read path evaluates `expiresAt` itself rather than trusting the flag — and a read never writes, because
+ * repairing a stale row is the reconciliation Workflow's job and the hot path stays a pure read.
+ */
+export const PaymentsEntitlement = z
+  .object({
+    id: z
+      .string()
+      .describe("The row's UUID. Text, like every id payments mints, so nothing about volume is inferable."),
+    subjectType: PaymentsSubject.shape.subjectType.describe(
+      "Whether `subjectId` names a user or an organization. Half the key — the id alone is ambiguous, so the two columns travel together.",
+    ),
+    subjectId: PaymentsSubject.shape.subjectId.describe(
+      "The subject holding the entitlement — a Pithy user id, or the adopter's organization id.",
+    ),
+    entitlement: EntitlementKey.describe(
+      "The entitlement key — what gating code names. `UNIQUE (subjectType, subjectId, entitlement)` is what makes this a read model rather than a log.",
+    ),
+    active: SQLiteBoolean.describe(
+      "Whether the granting purchase was in an access-granting status when the projection last wrote this row. An optimization, not the truth — `expiresAt` is rechecked on every read.",
+    ),
+    expiresAt: SQLiteDate.nullable().describe(
+      "When the grant lapses, or null for one that never does. The truth: a read applies it even when `active` still says 1.",
+    ),
+    sourcePurchaseId: z
+      .string()
+      .nullable()
+      .describe(
+        "Provenance — the purchase currently granting this entitlement, or null when nothing does. Answers 'why is this subject entitled' without a scan.",
+      ),
+    manual: SQLiteBoolean.describe(
+      "Whether a human wrote this row rather than the projection deriving it. A manual grant is held: the projection skips a row carrying it, so a support comp survives the subject's next renewal instead of being erased by it. A revoke clears the hold, handing the key back to the purchases that support it.",
+    ),
+    createdAt: SQLiteDate.describe("When this entitlement row first appeared for this subject."),
+    updatedAt: SQLiteDate.describe("When the projection last re-derived it."),
+  })
+  .describe("One entitlement a subject holds — the row in `pithy_payments_entitlements`, the read model gates hit.");
+export type PaymentsEntitlement = z.output<typeof PaymentsEntitlement>;
+export type PaymentsEntitlementRow = z.input<typeof PaymentsEntitlement>;

package/src/data/money.ts

@@ -0,0 +1,75 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Money, as the three rails report it and as the purchases table stores it.
+ *
+ * `amountMinor` is an integer in the currency's minor unit — cents for USD, yen for JPY, fils for KWD.
+ * No rail reports that directly. Apple reports thousandths of the currency unit ("milliunits"), Google
+ * reports millionths ("micros"), and Stripe reports minor units already. Converting means dividing by the
+ * rail's scale and then multiplying by the currency's own exponent, and the exponent is the part that
+ * catches people out: dividing Apple's 500000 for ¥500 by ten yields 50000, a hundredfold overstatement,
+ * because the yen has no subunit to divide into.
+ *
+ * So this holds the short list of currencies whose exponent is not two. It is a fixed list — ISO 4217 does
+ * not churn — and an unknown code falls back to two rather than throwing, because a webhook must not fail
+ * over a reporting detail.
+ *
+ * **{@link minorUnitDigits} is read from the browser half too**, by `../client/wholeUnits`, which is why
+ * this module imports nothing and must keep importing nothing: it is on the browser allowlist in
+ * `../client/sameOrigin.test.ts`, so anything reached from here lands in an adopter's bundle. The
+ * exponent is the same fact on both sides — how many digits the fraction occupies — and a second table
+ * for the client would be the drift `#427` exists to remove.
+ */
+
+/** Currencies with no subunit — the amount is already in minor units whatever the rail's scale. */
+const ZERO_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set([
+  "BIF",
+  "CLP",
+  "DJF",
+  "GNF",
+  "ISK",
+  "JPY",
+  "KMF",
+  "KRW",
+  "PYG",
+  "RWF",
+  "UGX",
+  "UYI",
+  "VND",
+  "VUV",
+  "XAF",
+  "XOF",
+  "XPF",
+]);
+
+/** Currencies whose minor unit is a thousandth, not a hundredth. */
+const THREE_DECIMAL_CURRENCIES: ReadonlySet<string> = new Set(["BHD", "IQD", "JOD", "KWD", "LYD", "OMR", "TND"]);
+
+/** How many digits the currency's minor unit occupies. Two unless ISO 4217 says otherwise. */
+export function minorUnitDigits(currency: string): number {
+  const code = currency.toUpperCase();
+  if (ZERO_DECIMAL_CURRENCIES.has(code)) return 0;
+  if (THREE_DECIMAL_CURRENCIES.has(code)) return 3;
+  return 2;
+}
+
+/**
+ * Convert a rail-reported amount into minor units, or null when it cannot be trusted.
+ *
+ * `scale` is what one currency unit is worth in the rail's own integer — 1000 for Apple's milliunits,
+ * 1_000_000 for Google's micros, 10 ** `minorUnitDigits` for a rail already reporting minor units.
+ *
+ * Null is returned rather than an approximation for a missing price, a missing currency, a non-finite
+ * number, or a negative amount. The last matters: `pithy_payments_purchases` refuses a negative
+ * `amountMinor` by CHECK constraint, so a rail reporting one would abort the whole projection batch and
+ * lose the purchase. An absent amount costs a reporting figure; a lost purchase costs a subscriber.
+ */
+export function minorUnitsFromScaled(scaled: number | null, scale: number, currency: string | null): number | null {
+  if (scaled === null || currency === null) return null;
+  if (!Number.isFinite(scaled) || scaled < 0) return null;
+  // Multiply before dividing. `(1005 / 1000) * 100` is 100.49999999999999 in binary floating point, which
+  // rounds to 100 and quietly loses a cent on every price that lands on a half; `(1005 * 100) / 1000` is
+  // exactly 100.5. The operands are small integers, so the product cannot approach the safe-integer limit.
+  return Math.round((scaled * 10 ** minorUnitDigits(currency)) / scale);
+}

package/src/data/pause.ts

@@ -0,0 +1,148 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PaymentsVerificationFailedError } from "../error/errors";
+import type { PaymentsRail } from "./rail";
+import type { PurchaseStatus } from "./status";
+
+/**
+ * When a paused subscription comes back — the one place every rail answers it.
+ *
+ * A pause is not an ending, and the single most useful thing anything can say about one is the date it
+ * ends. Two rails parsed that date out of a provider response and then dropped it, which is worse than
+ * never reading it: the value was provably present and understood, and no caller could reach it (#369).
+ * So the answer is stated once here rather than per rail, and the seam is shaped so a sixth rail inherits
+ * it instead of repeating the omission.
+ *
+ * ## Three facts, and they are different facts
+ *
+ * - **Not paused.** `status` is anything but `paused`, and there is nothing to resume. `resumesAt` is null
+ *   and {@link pauseResumesAt} will not let it be anything else — a date beside a live subscription is a
+ *   sentence nobody can write ("active until it resumes on the 14th"), and the purchases table carries a
+ *   check constraint saying so.
+ * - **Paused, with a date.** The provider named it. `resumesAt` is that instant, decoded from the
+ *   provider's own string and never computed from anything else.
+ * - **Paused, indefinitely.** The provider was asked and said none: a Play pause with no `autoResumeTime`,
+ *   a Paddle pause with no scheduled resume, a Lemon Squeezy pause with `resumes_at: null`. `resumesAt` is
+ *   null, and "paused until the 14th" and "paused indefinitely" are different sentences a consumer will
+ *   want to write.
+ *
+ * **Null on a paused row therefore means indefinite, not "we did not look"** — and that is only true
+ * because {@link PAYMENTS_PAUSE_RESUMPTION} is total over the rails and every rail able to report `paused`
+ * either reads its provider's field or states why there is no field to read. A rail's `{ none }` reason is
+ * a fact about that store, so a consumer that wants to distinguish "this store never dates a pause" from
+ * "this pause has no date" reads the table: it is exported for exactly that question.
+ *
+ * ## Never computed
+ *
+ * The date is the provider's or it does not exist. Nothing here adds a pause duration to a start date, and
+ * nothing falls back to a period end — the fallback available when this was filed was `periodEnd`, which
+ * is a period end and not a resumption, and reaching for it would have put a wrong date in a letter to a
+ * paying customer. That is worse than an absent one. The only input this function takes is the string the
+ * provider sent, which is what makes "never computed" a property of the signature rather than a promise.
+ */
+
+/** How one rail answers "when does this come back": the provider field it reads, or why there is none. */
+export type PauseResumption =
+  | {
+      /** The provider field carrying the resume date, in that provider's own spelling. */
+      readonly field: string;
+    }
+  | {
+      /** Why this rail has no resume date to read. A fact about the store, not an exemption. */
+      readonly none: string;
+    };
+
+/**
+ * Every rail, and where its paused subscriptions state their resume date.
+ *
+ * `satisfies Record<PaymentsRail, …>` rather than a partial map, exactly as `PAYMENTS_TABLE_DISCLOSURE`
+ * is: **a sixth rail does not compile until somebody decides how it answers this.** That is the structural
+ * half of the gate; `pause.test.ts` is the other half, and drives each declared field through the rail
+ * that reads it.
+ */
+export const PAYMENTS_PAUSE_RESUMPTION = {
+  /**
+   * No pause at all. StoreKit has no paused state — a subscriber either renews, lapses, or is refunded —
+   * so `appleStatus` cannot produce `paused` and there is no date to look for.
+   */
+  apple: { none: "StoreKit has no paused subscription state, so no Apple purchase is ever projected as paused." },
+  /** Play states it directly. Absent for an indefinite pause, which is a state Play genuinely has. */
+  google: { field: "pausedStateContext.autoResumeTime" },
+  /**
+   * Stripe's `paused` is not a pause with a date. It is a trial that ended with no payment method while
+   * `trial_settings.end_behavior.missing_payment_method` is `pause`, and it resumes when a card arrives
+   * rather than on a date — Stripe publishes none for it.
+   *
+   * `pause_collection.resumes_at` is a **different mechanism**: pausing collection leaves the subscription
+   * `active`, so it never produces a row this field could sit on. Modeling that is a separate question
+   * about a state this package does not have, and it is on #369's sweep rather than smuggled in here.
+   */
+  stripe: {
+    none: "Stripe's `paused` is a trial ended without a payment method; it resumes when one arrives, and Stripe publishes no date for it. `pause_collection.resumes_at` is a different mechanism that leaves the status `active`.",
+  },
+  /** Lemon Squeezy states it on the pause object. Null there is an open-ended pause. */
+  lemonSqueezy: { field: "pause.resumes_at" },
+  /**
+   * Paddle states it on the scheduled change — and **not** in the field named after it.
+   *
+   * Verified against a live sandbox on 2026-08-15. Pausing immediately with a `resume_at` leaves
+   * `scheduled_change: { action: "resume", effective_at: "2026-10-01T00:00:00Z", resume_at: null }`: the
+   * date moves to `effective_at` and the field literally called `resume_at` is null. `resume_at` carries
+   * it only while a *pause* is scheduled and the subscription is still `active`, which is not a paused
+   * subscription and not this field. Pausing with no resume date leaves `scheduled_change: null` — an
+   * indefinite pause, reported as one.
+   *
+   * A fix keyed on `resume_at` alone would therefore have shipped null for every paused Paddle
+   * subscription while looking correct, so both spellings are read and the one that means resumption wins.
+   */
+  paddle: { field: "scheduled_change.effective_at (action `resume`), or scheduled_change.resume_at" },
+} as const satisfies Record<PaymentsRail, PauseResumption>;
+
+/**
+ * A rail that reads a resume date, as a type.
+ *
+ * Derived from the table rather than restated, so {@link pauseResumesAt} **cannot be called** for a rail
+ * declared `{ none }`: a store with no resume date has no way to report one, and the refusal is a compile
+ * error rather than a review comment.
+ */
+export type ResumingRail = {
+  [Rail in PaymentsRail]: (typeof PAYMENTS_PAUSE_RESUMPTION)[Rail] extends { readonly field: string } ? Rail : never;
+}[PaymentsRail];
+
+/** What a rail hands over: which rail, what state it is reporting, and the provider's own string. */
+export interface PauseResumptionInput {
+  /** The rail reporting. Only a rail declaring a field in {@link PAYMENTS_PAUSE_RESUMPTION} may. */
+  rail: ResumingRail;
+  /** The normalized status this event carries. Anything but `paused` has nothing to resume. */
+  status: PurchaseStatus;
+  /**
+   * The provider's own resume date, verbatim — an RFC 3339 string. Null, undefined or empty is the
+   * provider saying there is none, which is an indefinite pause rather than a missing read.
+   */
+  reported: string | null | undefined;
+}
+
+/**
+ * The resume date to project, from what the provider said.
+ *
+ * Refuses an unreadable string rather than passing it on: `new Date("soon")` is an Invalid Date, and
+ * `SQLiteDate` encodes one as `NaN` — a corrupt column value that no read can tell from a real instant.
+ * That is the same refusal every other timestamp on these rails makes, and it leaves the delivery recorded
+ * for the reconciliation pass rather than silently written.
+ */
+export function pauseResumesAt(input: PauseResumptionInput): Date | null {
+  // A resume date belongs to a pause. A live subscription's next date is its renewal, and a canceled
+  // one's is its period end; neither is a resumption, and neither may be written here.
+  if (input.status !== "paused") return null;
+  const { reported } = input;
+  if (reported === null || reported === undefined || reported === "") return null;
+
+  const parsed = new Date(reported);
+  if (Number.isNaN(parsed.getTime())) {
+    throw new PaymentsVerificationFailedError({
+      detail: `${input.rail}: the resume date "${reported}" is not a readable timestamp.`,
+    });
+  }
+  return parsed;
+}

package/src/data/providerAccount.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { SQLiteDate } from "@pithy-sh/core/src/data/codecs";
+import { z } from "zod";
+import { PaymentsRail } from "./rail";
+import { PaymentsSubject } from "./subject";
+
+/**
+ * A provider identity mapped back to the subject that holds it — the row in
+ * `pithy_payments_provider_accounts`, keyed `UNIQUE (rail, providerAccountId)`.
+ *
+ * A Stripe webhook arrives carrying `cus_123`, and names no holder of ours. This table is the only way back. The
+ * link is established at purchase time, and all three rails provide the hook — Apple's `appAccountToken`,
+ * Google's `obfuscatedAccountId`, Stripe's `client_reference_id`. All three must be set by the app that
+ * starts the purchase, or webhooks arrive orphaned with nobody to project them against.
+ *
+ * What it maps back to is the **subject pair**, which is what makes the argument stronger rather than
+ * weaker: under organization billing the person who started the checkout is not the holder, so a row
+ * carrying only their user id would attribute every later renewal to them personally. The two columns are
+ * written together and read together — `data/subject.ts`.
+ *
+ * **The unique stays `(rail, providerAccountId)` and is never widened by the subject.** A provider
+ * identity binds to one holder, once, for the life of the link: widening the key would let a second
+ * subject claim the same `cus_123` and collect the first one's renewals. A rebind is a support operation
+ * with a deliberate delete, not something a purchase flow can do by writing a row.
+ */
+export const PaymentsProviderAccount = z
+  .object({
+    id: z.string().describe("The row's UUID."),
+    rail: PaymentsRail.describe("Which store this identity belongs to."),
+    providerAccountId: z
+      .string()
+      .describe(
+        "The rail's own account identifier — Stripe's customer id, Apple's appAccountToken, Google's obfuscatedAccountId.",
+      ),
+    subjectType: PaymentsSubject.shape.subjectType.describe(
+      "Whether `subjectId` names a user or an organization. Half the answer — the id alone is ambiguous, so the two columns travel together.",
+    ),
+    subjectId: PaymentsSubject.shape.subjectId.describe(
+      "The subject this provider identity resolves to — a Pithy user id, or the adopter's organization id.",
+    ),
+    createdAt: SQLiteDate.describe("When the link was established, which is the first purchase that carried it."),
+  })
+  .describe("A provider identity mapped to the subject that holds it — the row in `pithy_payments_provider_accounts`.");
+export type PaymentsProviderAccount = z.output<typeof PaymentsProviderAccount>;
+export type PaymentsProviderAccountRow = z.input<typeof PaymentsProviderAccount>;