@pithy-sh/payments 0.1.0

package/src/rails/paddle/discounts.ts

@@ -0,0 +1,176 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { CreatedDiscount, DiscountTerms } from "../../data/discount";
+import { PaymentsDiscountInvalidError } from "../../error/errors";
+import type { PaymentsPaddleCredentials } from "../../secret/registry";
+import type { ListedDiscount } from "../contract";
+import { type PaddleEnvironment, type PaddleHttpFetch, paddleHttpFetch, paddleJson } from "./api";
+
+/**
+ * Minting a discount at Paddle, from the normalized terms.
+ *
+ * One object, like Lemon Squeezy's and unlike Stripe's pair: a Paddle discount carries the money, the
+ * duration, the redemption limit, the expiry and the code together.
+ *
+ * ## The two translations that decide whether a customer is charged correctly
+ *
+ * **Duration.** `recur: false` is `once`. `recur: true` with `maximum_recurring_intervals: null` is
+ * `forever`. `recur: true` with a number is `repeating`, and **Paddle counts billing periods** — the same
+ * unit `DiscountDuration` already uses, so the number passes through unconverted. This is the second rail
+ * where it does not convert; Stripe is the one where it must, because `duration_in_months` counts months.
+ * Round-tripped live: `recur: true, maximum_recurring_intervals: 12` came back as `12` on a percentage
+ * discount, which is twelve renewals and not twelve months.
+ *
+ * **Expiry.** `redeemableUntil` means the code can no longer be *claimed*. Paddle's `expires_at` stops
+ * redemption and leaves an existing subscriber's discount running, which is the same meaning — so it maps
+ * directly.
+ *
+ * ## The charset, which is Paddle's and narrower than the shared schema's
+ *
+ * `DiscountCode` allows `[A-Za-z0-9_-]` up to 64 characters and promises "a code this project mints is
+ * redeemable on either rail". Paddle enforces `^[a-zA-Z0-9]{1,32}$` — verified live, where
+ * `PITHY_RECON-25` was refused with a bare `"Invalid request."` and nothing else.
+ *
+ * **The shared schema is not narrowed, and the refusal lands here instead.** Narrowing `DiscountCode`
+ * would be a behavior change for every Stripe and Lemon Squeezy adopter, refusing codes those rails
+ * accept today, in service of a rail they do not run. So this rail checks its own rule and says what it
+ * is — the adopter reads a sentence naming the two characters Paddle will not take, rather than an
+ * opaque 400 from Paddle. `DiscountCode`'s promise is now conditional, and `docs/paddle.md` says so.
+ *
+ * ## Amount, and the currency that arrives at the customer
+ *
+ * `currency_code` is **uppercase** at Paddle where `DiscountAmount.currency` is lowercase — verified
+ * live. A fixed amount in a currency no restricted price uses is refused at creation naming both, because
+ * at Paddle it would fail at redemption, in front of whoever typed the code.
+ *
+ * Paddle sends and takes amounts as **strings** in the currency's lowest denomination, including for the
+ * zero-decimal currencies: ¥725 is `"725"`, not `"72500"`. Nothing here scales.
+ */
+
+/** What creating or listing a discount needs. */
+export interface PaddleDiscountOptions {
+  /** The rail's credentials. */
+  credentials: PaymentsPaddleCredentials;
+  /** Which Paddle account to reach. */
+  environment: PaddleEnvironment;
+  /**
+   * The currency this project's Paddle catalog prices in, when the project declared one.
+   *
+   * Only used to refuse a fixed discount in another currency before it reaches Paddle. Absent means the
+   * check cannot be made and Paddle's own judgment stands — better than inventing a currency.
+   */
+  storeCurrency?: string;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: PaddleHttpFetch;
+}
+
+/** What Paddle accepts as a discount code. Narrower than the shared schema's — see the module doc. */
+export const PADDLE_DISCOUNT_CODE = /^[a-zA-Z0-9]{1,32}$/;
+
+/** A discount as Paddle returns it. */
+const PaddleDiscount = z
+  .object({
+    id: z.string().min(1).describe("The discount — `dsc_…`."),
+    code: z.string().nullish().describe("The code a customer types, or null for one applicable only by id."),
+    type: z.string().nullish().describe("`percentage` or `flat`."),
+    amount: z.string().nullish().describe("The figure, as a string: a percentage, or a lowest-denomination amount."),
+    currency_code: z.string().nullish().describe("Uppercase ISO 4217, on a flat discount."),
+    times_used: z.number().nullish().describe("How many times it has been claimed."),
+  })
+  .loose()
+  .describe("A Paddle discount, as much of one as this package reads back.");
+
+/** Create a discount and return the code a customer will type. */
+export async function createPaddleDiscount(
+  terms: DiscountTerms,
+  options: PaddleDiscountOptions,
+): Promise<CreatedDiscount> {
+  if (terms.code !== undefined && !PADDLE_DISCOUNT_CODE.test(terms.code)) {
+    // Refused here rather than by Paddle, because Paddle's own refusal is the string "Invalid request."
+    // with no field named — an adopter reading that has nothing to act on.
+    throw new PaymentsDiscountInvalidError({
+      message: "Paddle won't take that code.",
+      action: "Use letters and digits only, up to 32 characters — no dashes and no underscores.",
+      detail: `Paddle enforces ^[a-zA-Z0-9]{1,32}$ on a discount code and refused "${terms.code}" with a bare "Invalid request.". The shared \`DiscountCode\` schema is deliberately wider, because narrowing it would refuse codes the Stripe and Lemon Squeezy rails accept today.`,
+    });
+  }
+
+  if (
+    terms.amount.kind === "fixed" &&
+    options.storeCurrency !== undefined &&
+    options.storeCurrency.toLowerCase() !== terms.amount.currency.toLowerCase()
+  ) {
+    throw new PaymentsDiscountInvalidError({
+      message: "That discount is in a currency this catalog does not sell in.",
+      action: `Create it in ${options.storeCurrency.toUpperCase()}, or use a percentage instead.`,
+      detail: `A fixed discount of ${terms.amount.amountMinor} ${terms.amount.currency.toUpperCase()} cannot apply to prices in ${options.storeCurrency.toUpperCase()}. Paddle accepts the object and refuses it at redemption, in front of the customer.`,
+    });
+  }
+
+  const body: Record<string, unknown> = {
+    // Paddle requires a description, and it is the internal label an adopter finds the discount by.
+    description: terms.code ?? "Pithy discount",
+    type: terms.amount.kind === "percent" ? "percentage" : "flat",
+    // A string, in the currency's lowest denomination, and never scaled. A percentage is a string too.
+    amount: terms.amount.kind === "percent" ? String(terms.amount.percent) : String(terms.amount.amountMinor),
+    // `recur: false` is `once`; `true` is `forever` unless a count narrows it. **Not converted** — Paddle
+    // counts billing periods, which is the unit the normalized terms already use.
+    recur: terms.duration.kind !== "once",
+    // A code supplied means a customer may type it; one minted without a code is applicable only by id.
+    enabled_for_checkout: terms.code !== undefined,
+  };
+  if (terms.amount.kind === "fixed") body.currency_code = terms.amount.currency.toUpperCase();
+  if (terms.code !== undefined) body.code = terms.code;
+  if (terms.duration.kind === "repeating") body.maximum_recurring_intervals = terms.duration.billingPeriods;
+  if (terms.maxRedemptions !== undefined) body.usage_limit = terms.maxRedemptions;
+  if (terms.redeemableUntil !== undefined) body.expires_at = terms.redeemableUntil.toISOString();
+
+  const answer = await paddleJson(options.transport ?? paddleHttpFetch, "/discounts", {
+    what: "a discount",
+    apiKey: options.credentials.apiKey,
+    environment: options.environment,
+    body,
+  });
+
+  const parsed = PaddleDiscount.safeParse(answer?.data);
+  const code = parsed.success ? parsed.data.code : null;
+  if (!parsed.success || typeof code !== "string" || code === "") {
+    throw new PaymentsDiscountInvalidError({
+      detail: "Paddle created a discount and returned no code for it.",
+    });
+  }
+
+  return { code, providerDiscountId: parsed.data.id, terms };
+}
+
+/** Every discount this account holds, newest first. Never reaches a browser — see {@link ListedDiscount}. */
+export async function listPaddleDiscounts(options: PaddleDiscountOptions): Promise<readonly ListedDiscount[]> {
+  const answer = await paddleJson(options.transport ?? paddleHttpFetch, "/discounts", {
+    what: "the discount list",
+    apiKey: options.credentials.apiKey,
+    environment: options.environment,
+    query: [
+      ["order_by", "created_at[DESC]"],
+      ["per_page", "200"],
+    ],
+  });
+
+  const parsed = z.array(PaddleDiscount).safeParse(answer?.data);
+  if (!parsed.success) return [];
+
+  return parsed.data
+    .filter((discount): discount is typeof discount & { code: string } => typeof discount.code === "string")
+    .map((discount) => ({
+      code: discount.code,
+      providerDiscountId: discount.id,
+      // Paddle's own figures, rendered rather than recomputed. A percentage carries no currency and a flat
+      // amount is a lowest-denomination integer — neither is divided by anything here.
+      amount:
+        discount.type === "percentage"
+          ? `${discount.amount ?? "?"}%`
+          : `${discount.amount ?? "?"} ${(discount.currency_code ?? "").toLowerCase()}`.trim(),
+      redemptions: typeof discount.times_used === "number" ? discount.times_used : null,
+    }));
+}

package/src/rails/paddle/events.ts

@@ -0,0 +1,285 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { z } from "zod";
+import type { PaymentsPaddleCredentials } from "../../secret/registry";
+import type { VerifiedNotification } from "../contract";
+import { type PaddleEnvironment, type PaddleHttpFetch, paddleHttpFetch, paddleJson } from "./api";
+import { PaddleEvent } from "./objects";
+import { PADDLE_ADJUSTMENTS_INCLUDE, readTransaction } from "./read";
+import { recordedPayload } from "./recorded";
+import { type ParsePaddleNotificationOptions, readPaddleEvent } from "./webhook";
+
+/**
+ * The events sweep — the repair `refresh` cannot make.
+ *
+ * `refresh` re-reads rows this deployment already holds. A purchase whose webhook was never delivered and
+ * which no client submitted has no row, so it is invisible to `refresh` forever. Paddle publishes an
+ * account-wide event stream, so this rail can find those, and no other rail in this package can.
+ *
+ * **It does repair a delivery that arrived and failed, though that is not what it is for.** The sweep
+ * writes through the same table on the same `UNIQUE (rail, providerEventId)`, and since #337 both readers
+ * agree that a delivery which errored is still outstanding — `completeWebhook` leaves `processedAt` null
+ * beside its reason — so a swept event whose webhook failed is tried again rather than counted a
+ * duplicate. The primary repair for that case is the *next delivery*, on every rail; Paddle's replay
+ * endpoint reuses the same `event_id` and now reprocesses. What only this sweep can repair is a webhook
+ * that was never delivered at all — the case that has no row and is invisible to `refresh` forever.
+ *
+ * ## The stream is account-wide, and that is a hazard rather than a convenience
+ *
+ * Verified live: the assigned sandbox's own stream carries `api_key.created` and `client_token.created`.
+ * The `api_key` payload's `key` is redacted by Paddle; **the `client_token` payload's `token` is not.**
+ * Projecting every swept event through the webhook writer would fill `pithy_payments_webhook_events` with
+ * product, price, api-key and client-token rows — and persist live client tokens into a table an operator
+ * greps.
+ *
+ * There are therefore **two** controls, and only one of them is ours.
+ *
+ * The **query filter** asks Paddle for exactly {@link PADDLE_SWEPT_EVENT_TYPES}. It is sent in the form
+ * Paddle documents for an `array[string]` parameter — one key, values comma-separated,
+ * `event_type=a,b,c` — verified against the live sandbox API on 2026-08-13: filtering on two of the six
+ * types in that account's stream returned four events of exactly those two types, and an unrecognised
+ * value is refused with `Request does not pass validation` rather than ignored. An earlier build sent
+ * `event_type=a&event_type=b&…`, a repeated-key form Paddle documents nowhere; whether that form is read
+ * as an array, as one of its values, or not at all is not something this package can know.
+ *
+ * The **recording allowlist** is the control this package owns. A returned event whose type is not on
+ * that list yields a `null` notification, and the sweep writes no row for it at all. So an unhonoured
+ * filter costs a wasted page rather than a client token in D1, and the safety of this module does not
+ * rest on a query parameter being obeyed by someone else's service. See `recorded.ts` for the same
+ * argument on the webhook path, where there is no query to filter and the subscribed-event list is set
+ * by a human in Paddle's dashboard.
+ *
+ * ## The cursor, and the 90-day cliff
+ *
+ * `order_by=id[ASC]&after=<cursor>`, with the cursor persisted in `pithy_payments_sync_cursors`. It
+ * advances only past events fully projected, so a failure halts advancement and the step retries next run
+ * — for a bounded number of runs, after which the event is quarantined and the stream moves on. That bound
+ * belongs to the caller: see `workflows/paddleSweep.ts`, which owns the row and the attempt count.
+ *
+ * This function's own part in it is {@link SweptEvent.failure}: an event whose second read fails is
+ * returned carrying its failure rather than thrown, so the caller can halt at that one event instead of
+ * losing every healthy event on the page with it.
+ *
+ * **Paddle retains 90 days.** A cursor older than that can never be caught up — the events between it and
+ * the retention window are gone — so this reports a gap naming the window rather than silently restarting
+ * from the beginning and re-projecting three months of history.
+ */
+
+/** How many events one page asks for. Paddle's maximum, so a backlog is walked in as few calls as possible. */
+export const PADDLE_SWEEP_PAGE_SIZE = 200;
+
+/** How long Paddle keeps an event. Confirmed in the API reference and in the endpoint's own description. */
+export const PADDLE_EVENT_RETENTION_DAYS = 90;
+
+/**
+ * Every event type the sweep asks for — exactly the ones {@link readPaddleEvent} can act on.
+ *
+ * A type absent here is a type never fetched, never recorded, and therefore never a client token in a
+ * table. Adding a projection to the event map means adding its type here; a test asserts the two agree,
+ * because a map that grew a case the sweep never fetches would repair through the webhook path and not
+ * through the sweep, which is precisely the asymmetry the sweep exists to remove.
+ */
+export const PADDLE_SWEPT_EVENT_TYPES: readonly string[] = [
+  "transaction.paid",
+  "transaction.completed",
+  "transaction.payment_failed",
+  "transaction.past_due",
+  "transaction.canceled",
+  "transaction.updated",
+  "transaction.revised",
+  "transaction.billed",
+  "subscription.created",
+  "subscription.activated",
+  "subscription.resumed",
+  "subscription.trialing",
+  "subscription.past_due",
+  "subscription.paused",
+  "subscription.canceled",
+  "subscription.updated",
+  "subscription.imported",
+  "adjustment.created",
+  "adjustment.updated",
+];
+
+/** The same list as a set, for the lookup that decides whether an event is recorded at all. */
+const SWEPT_EVENT_TYPES: ReadonlySet<string> = new Set(PADDLE_SWEPT_EVENT_TYPES);
+
+/** What one sweep page needs. */
+export interface PaddleSweepOptions extends ParsePaddleNotificationOptions {
+  /** The rail's credentials. */
+  credentials: PaymentsPaddleCredentials;
+  /** Which Paddle account to sweep. */
+  environment: PaddleEnvironment;
+  /** The event id to resume after, or undefined to start at the oldest retained event. */
+  cursor?: string;
+  /** How many events to ask for. Defaults to Paddle's maximum. */
+  pageSize?: number;
+  /** The HTTP seam. Defaults to the runtime's `fetch`. */
+  transport?: PaddleHttpFetch;
+}
+
+/** One swept event: what it is, and what the shared event map made of it. */
+export interface SweptEvent {
+  /** Paddle's own event id — the same key the webhook path records, because the stream carries no other. */
+  eventId: string;
+  /** The event type, for the operator reading a run's report. */
+  eventType: string;
+  /**
+   * What the event map made of it, or **null for a type this build does not record at all**.
+   *
+   * Null is not "projects nothing" — that is a notification whose `event` is null, and it still earns a
+   * row. Null here means the type is off {@link PADDLE_SWEPT_EVENT_TYPES}, so Paddle returned something
+   * the query asked it not to, and the caller must advance its cursor past the event without writing
+   * anything. The body is never even read, so there is nothing to leak. It is also null when
+   * {@link SweptEvent.failure} is set, because there is nothing the map could make of it.
+   */
+  notification: VerifiedNotification | null;
+  /**
+   * Why this event could not be read, and the body to record against it — or null when it read cleanly.
+   *
+   * **Carried rather than thrown, because a page is not an event.** Reading an `adjustment.created`
+   * reaches Paddle a second time for the transaction it names, and that read can fail on its own — an
+   * outage, a deleted transaction, a shape a later Paddle changed. Throwing out of this function threw
+   * away the whole page with it, including every event *ahead* of the bad one that had already read
+   * perfectly, and the caller's per-event failure handling never saw any of them.
+   *
+   * The body travels with the failure so the caller can still record a row for the event, and it goes
+   * through `recordedPayload` on the way — a write to `pithy_payments_webhook_events` is a write to
+   * `pithy_payments_webhook_events` whichever branch reached it. It is present only on this branch: a
+   * withheld type carries no payload here, which is the point of the allowlist.
+   */
+  failure: { cause: unknown; payload: Record<string, unknown> } | null;
+}
+
+/** One page of the sweep. */
+export interface PaddleSweepPage {
+  /** The events on this page, oldest first. */
+  events: readonly SweptEvent[];
+  /** The cursor to resume after, or undefined when nothing was returned. */
+  cursor?: string;
+  /** Whether Paddle has more beyond this page. */
+  hasMore: boolean;
+  /**
+   * A gap this run cannot close, or null.
+   *
+   * Set when the sweep was asked to resume from a cursor Paddle no longer knows — which is what a cursor
+   * older than the retention window looks like. Reported rather than repaired: restarting from the
+   * beginning would re-project three months, and pretending the gap is not there would leave it forever.
+   */
+  gap: string | null;
+}
+
+/** Sweep one page of Paddle's event stream, projecting each event through the same map a webhook uses. */
+export async function sweepPaddleEvents(options: PaddleSweepOptions): Promise<PaddleSweepPage> {
+  const query: [string, string][] = [
+    ["order_by", "id[ASC]"],
+    ["per_page", String(options.pageSize ?? PADDLE_SWEEP_PAGE_SIZE)],
+    // One key, values comma-separated. That is the form Paddle documents for every `array[string]` query
+    // parameter, and the form verified against the live API. It is a request, not a guarantee — the
+    // allowlist below is what makes an unhonoured filter harmless.
+    ["event_type", PADDLE_SWEPT_EVENT_TYPES.join(",")],
+  ];
+  if (options.cursor !== undefined) query.push(["after", options.cursor]);
+
+  let answer: Awaited<ReturnType<typeof paddleJson>>;
+  try {
+    answer = await paddleJson(options.transport ?? paddleHttpFetch, "/events", {
+      what: "the event stream",
+      apiKey: options.credentials.apiKey,
+      environment: options.environment,
+      query,
+    });
+  } catch (cause) {
+    // A cursor Paddle will not resume from is the retention cliff, and it is not a transient failure —
+    // retrying it forever would be a step that never succeeds. Reported as a gap the operator can act on.
+    if (options.cursor !== undefined && isUnknownCursor(cause)) {
+      return {
+        events: [],
+        cursor: options.cursor,
+        hasMore: false,
+        gap: `Paddle no longer knows event ${options.cursor}, so the sweep cannot resume from it. Paddle retains ${PADDLE_EVENT_RETENTION_DAYS} days of events, and anything between that cursor and the retention window is gone. Reconcile the affected purchases with \`pithy payments reconcile --rail paddle\`, then clear the cursor to restart from the oldest retained event.`,
+      };
+    }
+    throw cause;
+  }
+
+  const parsed = z.array(PaddleEvent).safeParse(answer?.data);
+  if (!parsed.success) {
+    return { events: [], cursor: options.cursor, hasMore: false, gap: null };
+  }
+
+  // An adjustment says how much came off and never what the original was, so the map cannot tell a full
+  // refund from a partial one without reading the transaction — and it refuses rather than guessing when
+  // no reader is supplied. This module owns the credentials, the account and the transport, so it builds
+  // the reader itself: a caller cannot forget what it was never asked for.
+  const read: ParsePaddleNotificationOptions = {
+    ...options,
+    readTransaction:
+      options.readTransaction ??
+      ((id) =>
+        readTransaction(
+          id,
+          {
+            credentials: options.credentials,
+            environment: options.environment,
+            transport: options.transport ?? paddleHttpFetch,
+          },
+          // The one read on this rail that needs the array, and therefore the one that needs the key to
+          // carry `adjustment.read`. See `read.ts`.
+          PADDLE_ADJUSTMENTS_INCLUDE,
+        )),
+  };
+
+  const events: SweptEvent[] = [];
+  for (const event of parsed.data) {
+    // The allowlist, applied before the body is looked at. A type the query asked Paddle to withhold and
+    // Paddle returned anyway is walked past, not recorded — see the module doc.
+    if (!SWEPT_EVENT_TYPES.has(event.event_type)) {
+      events.push({ eventId: event.event_id, eventType: event.event_type, notification: null, failure: null });
+      continue;
+    }
+    try {
+      events.push({
+        eventId: event.event_id,
+        eventType: event.event_type,
+        notification: await readPaddleEvent(event, read),
+        failure: null,
+      });
+    } catch (cause) {
+      // One event's second read failing is one event's problem. The page still returns, so everything
+      // ahead of this event keeps its projection and the caller's cursor can stop exactly here.
+      //
+      // **Through `recordedPayload`, like every other write to that table.** `recorded.ts` states the
+      // control without an exception — `PaddleEvent` is `.loose()`, and a body this build cannot name is a
+      // body it cannot vouch for. Today the swept list is a subset of the recorded list, so this returns the
+      // whole event either way; that subset is an invariant two lists happen to satisfy, not a guarantee
+      // this branch is entitled to assume. A control with one path around it is not a control.
+      events.push({
+        eventId: event.event_id,
+        eventType: event.event_type,
+        notification: null,
+        failure: { cause, payload: recordedPayload(event) },
+      });
+    }
+  }
+
+  return {
+    events,
+    // The last event on the page, and only when there was one: advancing past an empty page would move
+    // the cursor onto nothing.
+    cursor: events.at(-1)?.eventId ?? options.cursor,
+    hasMore: answer?.hasMore === true,
+    gap: null,
+  };
+}
+
+/** Whether Paddle's refusal is "I do not know that cursor" rather than a credential or an outage. */
+function isUnknownCursor(cause: unknown): boolean {
+  if (typeof cause !== "object" || cause === null) return false;
+  const payload = (cause as { payload?: { code?: string; detail?: string } }).payload;
+  if (payload?.code !== "payments/rail_not_configured") return false;
+  // Paddle's own words. Narrow on purpose: a 401 or a 403 folds into the same code and is a rotated key,
+  // not a lost cursor, and reporting one as a retention gap would send an operator to the wrong page.
+  return /not_found|invalid_field|entity_not_found/i.test(payload.detail ?? "");
+}

package/src/rails/paddle/fixtures/browserForged.ts

@@ -0,0 +1,54 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Two `custom_data` objects a browser wrote onto real Paddle transactions, recorded from the live sandbox.
+ *
+ * Not invented. Both were produced on 2026-08-13 by a page holding nothing but a publishable client token,
+ * driving `Paddle.Checkout.open` and paying with `4242 4242 4242 4242`; both are what Paddle stored and
+ * handed back from `GET /transactions/{id}` afterwards. That distinction is the point of the file: a
+ * forgery a test author typed proves the reader agrees with the author, and a forgery Paddle stored proves
+ * the attack exists.
+ *
+ * They matter because #309's design rested on the opposite belief — that `custom_data` could only be
+ * written by the server, so an ownership stamp needed no proof. It rested on that belief being true of the
+ * `transactionId` form in particular. **It is true of neither.**
+ */
+
+/**
+ * The `items[]` forgery: a checkout the page opened for a price the page chose, stamped by the page.
+ *
+ * Recorded from `txn_01kzybmw15rve4bhj3zsbf1k5d`, which Paddle recorded with `origin: "web"` and a paid
+ * total of `544`. No server was involved at any point. The `pithy_` key names are exported constants in an
+ * open-source package and the environment is one of three, so an attacker guesses nothing here — which is
+ * why the third key exists and why it is a MAC.
+ */
+export const BROWSER_ITEMS_FORGERY: Record<string, unknown> = {
+  pithy_env: "prod",
+  pithy_user: "victim",
+  pithy_ref_proof: "0000000000000000000000000000000000000000000000000000000000000000",
+};
+
+/**
+ * The overwrite: a checkout opened for a transaction **the server created and stamped**, whose stamp the
+ * browser replaced on its way through.
+ *
+ * Recorded from `txn_01kzybt89pnvvnwgkabefsjy2z`. The server created it with
+ * `{ pithy_user: "server-owner", pithy_env: "prod", pithy_ref_proof: "aa…aa" }`; the page called
+ * `Paddle.Checkout.open({ transactionId, customData: { … } })` and paid, and this is what the transaction
+ * carried afterwards. Paddle kept `origin: "api"`, so even *that* field does not distinguish the two.
+ *
+ * **This is the measurement that settles the issue's open question.** Choosing `transactionId` over
+ * `items[]` is still right — it fixes the price and the buyer, which a page must never name — but it buys
+ * nothing at all for `custom_data`. The stamp is protected by the MAC and by nothing else, on either form.
+ *
+ * **And the overwrite lands on open, not on payment.** A second probe opened a checkout for a `draft`
+ * transaction and closed it without paying; the transaction's `custom_data` had already been replaced. So
+ * the stamp on any pending transaction is writable by anyone who knows its id — which is one more reason
+ * the field is a claim to be proved rather than a record to be read.
+ */
+export const BROWSER_OVERWROTE_SERVER_STAMP: Record<string, unknown> = {
+  pithy_env: "prod",
+  pithy_user: "attacker",
+  pithy_ref_proof: "bb",
+};

package/src/rails/paddle/fixtures/pausedSubscription.ts

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * What Paddle actually stores on a paused subscription, recorded from the live sandbox on 2026-08-15.
+ *
+ * Not invented. `sub_01kzybh940drg5p1dagqv4xj37` was paused through the API twice — once with a resume
+ * date, once without — and read back with `GET /subscriptions/{id}` each time. Every value below is from
+ * those responses: the pause fields from the paused reads, which were narrowed to exactly these, and the
+ * identity fields (`id`, `customer_id`, `created_at`, the item's price) from the same subscription, which
+ * was resumed afterwards and is active again. Nothing is here that was not read back.
+ *
+ * **The recording refutes the obvious fix.** #369 describes the Paddle half as "`scheduled_change.resume_at`
+ * is the same story", and a change keyed on that field would have shipped null for every paused Paddle
+ * subscription while reading as if it worked: pausing with `resume_at: "2026-10-01T00:00:00Z"` moves the
+ * date onto a **`resume` scheduled change's `effective_at`** and leaves `resume_at` **null**. That field
+ * carries a date only while a `pause` is scheduled and the subscription is still `active`, which is not a
+ * paused subscription at all.
+ *
+ * The pair also pins the other half of the design: an open-ended pause is `scheduled_change: null`, so a
+ * null resume date on a paused Paddle row is Paddle saying "indefinitely" rather than this rail declining
+ * to look.
+ */
+
+/** The date the pause was asked to end at, verbatim as it was sent and as Paddle echoed it back. */
+export const PADDLE_PAUSE_RESUME_AT = "2026-10-01T00:00:00Z";
+
+/**
+ * A subscription paused **with** a resume date — `pause({ effective_from: "immediately", resume_at })`.
+ *
+ * Note `resume_at: null` beside an `effective_at` carrying the date. That inversion is the whole reason
+ * `subscriptionResumesAt` reads the action rather than the field named after the answer.
+ */
+export const PADDLE_PAUSED_WITH_RESUME_DATE = {
+  id: "sub_01kzybh940drg5p1dagqv4xj37",
+  status: "paused",
+  customer_id: "ctm_01kzybg67tdbn7emh9c2n3zs17",
+  paused_at: "2026-08-15T13:43:55.956Z",
+  scheduled_change: { action: "resume", effective_at: PADDLE_PAUSE_RESUME_AT, resume_at: null, items: null },
+  current_billing_period: { starts_at: "2026-08-13T20:03:06.313818Z", ends_at: "2026-09-13T20:03:06.313818Z" },
+  next_billed_at: PADDLE_PAUSE_RESUME_AT,
+  items: [{ price: { id: "pri_01kzvyz9e21z9vbhd7xqq3csyh" }, status: "inactive" }],
+  created_at: "2026-08-13T20:03:07.008Z",
+};
+
+/**
+ * The same subscription paused **without** one — `pause({ effective_from: "immediately" })`.
+ *
+ * `scheduled_change` is null and so is `next_billed_at`: Paddle has nothing to say about when this comes
+ * back, because nothing decided it. That is the indefinite pause, and it is a real state rather than a gap.
+ */
+export const PADDLE_PAUSED_INDEFINITELY = {
+  id: "sub_01kzybh940drg5p1dagqv4xj37",
+  status: "paused",
+  customer_id: "ctm_01kzybg67tdbn7emh9c2n3zs17",
+  paused_at: "2026-08-15T13:44:10.712Z",
+  scheduled_change: null,
+  current_billing_period: { starts_at: "2026-08-15T13:44:09.279Z", ends_at: "2026-09-15T13:44:09.279Z" },
+  next_billed_at: null,
+  items: [{ price: { id: "pri_01kzvyz9e21z9vbhd7xqq3csyh" }, status: "inactive" }],
+  created_at: "2026-08-13T20:03:07.008Z",
+};