@pithy-sh/payments 0.1.0

package/src/rails/stripe/webhook.ts

@@ -0,0 +1,79 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PaymentsVerificationFailedError } from "../../error/errors";
+import type { PaymentsStripeCredentials } from "../../secret/registry";
+import type { VerifiedNotification, WebhookDelivery } from "../contract";
+import { mapStripeEvent, StripeEvent } from "./objects";
+import { STRIPE_SIGNATURE_HEADER, verifyStripeSignature } from "./signature";
+
+/**
+ * One Stripe webhook delivery: verified, read, and normalized.
+ *
+ * Three steps, in this order, and the order is the point. **Authenticity first** — the HMAC covers the exact
+ * received bytes, so nothing about the body is trustworthy until it passes, and a forgery is refused before a
+ * single field is read. Then the **envelope**, because an event's `type` is what says which object it carries.
+ * Then the **mapping**, which is `objects.ts`'s job and the only part that knows what Stripe's vocabulary means.
+ *
+ * The stored payload is the whole event, not the object inside it. The webhook row is the replay source, and
+ * the envelope carries the event id, the type, and Stripe's own timestamp — which is what makes "why didn't this
+ * renew" answerable from the table without going back to Stripe.
+ */
+
+/** What verifying one Stripe delivery needs: the endpoint's secret, and a clock for the replay window. */
+export interface StripeWebhookOptions {
+  /** Stripe's credential block. Only `webhookSecret` is used here; the API key belongs to the other paths. */
+  credentials: PaymentsStripeCredentials;
+  /** The clock, for the signature's freshness window. Injected so tests are deterministic. */
+  now: Date;
+  /** The freshness window, in seconds. Defaults to Stripe's own five minutes. */
+  toleranceSeconds?: number;
+}
+
+/** Verify and normalize one Stripe webhook delivery. Throws when authenticity cannot be established. */
+export async function parseStripeNotification(
+  delivery: WebhookDelivery,
+  options: StripeWebhookOptions,
+): Promise<VerifiedNotification> {
+  await verifyStripeSignature(
+    delivery.body,
+    delivery.headers.get(STRIPE_SIGNATURE_HEADER),
+    options.credentials.webhookSecret,
+    { now: options.now, toleranceSeconds: options.toleranceSeconds },
+  );
+
+  let raw: unknown;
+  try {
+    raw = JSON.parse(delivery.body) as unknown;
+  } catch (cause) {
+    // Cannot happen from Stripe — the bytes just proved they came from Stripe. If it ever does, it must not
+    // become a half-read event.
+    throw new PaymentsVerificationFailedError(
+      { detail: "Stripe: the delivery verified but its body is not JSON." },
+      { cause },
+    );
+  }
+
+  const parsed = StripeEvent.safeParse(raw);
+  if (!parsed.success) {
+    // Never echo the body: it is a customer's purchase, and it carries their Stripe identifiers.
+    throw new PaymentsVerificationFailedError({
+      detail: `Stripe: the delivery is not a Stripe event — ${parsed.error.issues
+        .map((issue) => `${issue.path.join(".") || "<root>"}:${issue.code}`)
+        .join(", ")}.`,
+    });
+  }
+
+  const event = parsed.data;
+  const mapped = mapStripeEvent(event);
+  return {
+    // Stripe's own event id. `UNIQUE (rail, providerEventId)` on it is what makes a redelivery recognized rather
+    // than reprocessed, and Stripe retries every non-2xx for three days.
+    providerEventId: event.id,
+    payload: event as Record<string, unknown>,
+    event: mapped.event,
+    providerAccountId: mapped.providerAccountId,
+    accountReference: mapped.accountReference,
+    note: mapped.note,
+  };
+}

package/src/secret/registry.ts

@@ -0,0 +1,275 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { defineSecretRegistry } from "@pithy-sh/secrets/src/registry";
+import { z } from "zod";
+import type { PaymentsRail } from "../data/rail";
+import { PaymentsRailNotConfiguredError } from "../error/errors";
+
+/**
+ * The one secret payments reads, and the shape of it.
+ *
+ * **One entry, five optional rails.** Every rail's credentials live inside a single JSON secret rather than
+ * one secret per rail, and that is a storage decision worth stating: adding a rail then never reshapes
+ * storage, never adds a binding to a `wrangler.jsonc`, and never needs a migration of the secrets store. It
+ * is the arrangement `@pithy-sh/turnstile` uses for its per-mode widget keys, for the same reason — one
+ * secret serves one *or* both, so the second costs nothing.
+ *
+ * A rail's block is present or entirely absent. There is no partial credential: `strictObject` with every
+ * field required means an operator who supplies half of Stripe's pair gets a loud
+ * `secrets/invalid_value` at the read rather than a signature check that silently never passes.
+ *
+ * ## Reading it
+ *
+ * `await sharedSecretsStore(env, paymentsSecretsRegistry)` then `.get(PAYMENTS_PROVIDER_SECRET)`, at the
+ * point of need — never off a raw `env.X`, never through `CloudflareSecretsStoreManager`, never cached in a
+ * module variable, and never spread into a log or an audit payload. Grep `sharedSecretsStore(` to find every
+ * read site. `backend` is the single place the storage location is decided; moving this bundle to the
+ * Cloudflare Secrets Store would be a one-line edit here (plus a binding) and no change at any read site.
+ *
+ * `rotatable: true` because two of these genuinely rotate — Apple's App Store Connect key and Stripe's
+ * webhook signing secret — and a verifier that must span a rotation reads `getVersions` instead of `get`.
+ * Rotation changes nothing about how the value is stored, so declaring it now costs nothing and declaring it
+ * later would be a registry edit during an incident.
+ *
+ * ## What is not here
+ *
+ * Apple's **root certificates**, because they are public: they ship in `rails/apple/certs.ts` as pinned
+ * assets. Storing a public key as a secret would suggest the verification depends on its secrecy, and it does
+ * not — it depends on it being *ours*.
+ *
+ * The **bundle id** is here, in Apple's block, and it is not secret either. It sits with the credentials
+ * because it is part of the app's identity at Apple: it is what a notification is checked against, and it is
+ * the `bid` claim an App Store Server API token carries. Splitting it into config would put one half of one
+ * app's identity in git and the other in the secrets store.
+ */
+
+/** The name the credential bundle is stored and resolved under. The join key across every registry. */
+export const PAYMENTS_PROVIDER_SECRET = "payments-provider-credentials";
+
+/**
+ * The console each rail's credentials are taken from, and taken from again ninety days later.
+ *
+ * **This is the honest answer, and it does not fit in `documentation`.** That field holds one required
+ * URL; this secret spans five issuers, and every one of them publishes its own page. There is no sixth
+ * page that names all five, because no company documents a competitor's console. A single string can
+ * therefore be true of at most one rail out of five, and the entry has to say something for all of them.
+ *
+ * So the entry points at ours, `PAYMENTS_CREDENTIALS_PAGE`, whose only job is to carry this table to an
+ * operator who arrived by clicking. The table is the destination; the page is the redirect. That is one
+ * hop more than the field promises — `SecretOrigin` restricting `documentation` to a single URL is the
+ * reason, and #332 is where the shape is argued.
+ *
+ * Not a rail's marketing page and not a "how to integrate" guide: the deep link to the settings screen
+ * that shows the key, so an operator lands on the thing they came to copy.
+ */
+export const PAYMENTS_RAIL_CONSOLES: Readonly<Record<PaymentsRail, string>> = {
+  // Users and Access → Integrations → App Store Connect API. The `.p8` downloads exactly once here, and
+  // the key id and issuer id are both on this screen.
+  apple: "https://appstoreconnect.apple.com/access/integrations/api",
+  // The service account and its JSON key. Play Console grants that account access; the key is minted here.
+  google: "https://console.cloud.google.com/iam-admin/serviceaccounts",
+  // The secret key. The webhook signing secret is per endpoint, one screen across in Developers → Webhooks.
+  stripe: "https://dashboard.stripe.com/apikeys",
+  lemonSqueezy: "https://app.lemonsqueezy.com/settings/api",
+  paddle: "https://vendors.paddle.com/authentication-v2",
+};
+
+/**
+ * Where a human goes for these credentials, and where the same human replaces them.
+ *
+ * **Five consoles, one `issuer` field.** Apple's `.p8`, Google's service-account key, Stripe's key pair,
+ * Lemon Squeezy's API key and Paddle's are each taken by hand from a different company's console, and they
+ * share one secret because they share one storage decision (see above) — not because they share an issuer.
+ * The axis holds a single name, so the honest one is `other`: *somebody issues this, and it is not one
+ * somebody.* Naming any single rail would be wrong for every deployment that does not sell through it.
+ *
+ * So the link is the one page that names all five rather than a rail's settings page. It has to *name*
+ * them: this constant pointed at the same document before #332 and the document listed no console at all,
+ * which cost the click and returned the reader to the search they started with. The section is fixed by
+ * name, and `registry.test.ts` reads the file off disk and fails if a rail's console is not in it.
+ *
+ * The day this bundle is split per rail — or `SecretOrigin` grows a destination per issuer — each half
+ * names its own console and this constant goes.
+ */
+export const PAYMENTS_CREDENTIALS_PAGE =
+  "https://github.com/pithy-sh/pithy/blob/main/docs/commands/payments.md#where-each-rails-credentials-come-from";
+
+export const PaymentsAppleCredentials = z
+  .strictObject({
+    bundleId: z
+      .string()
+      .min(1)
+      .describe(
+        "The app's bundle id. Not a secret, but part of the app's identity at Apple: every notification and receipt is checked against it, because an Apple signature proves Apple signed the payload and never that it is about this app.",
+      ),
+    keyId: z
+      .string()
+      .min(1)
+      .describe("The App Store Connect API key id — the `kid` of the token that calls the App Store Server API."),
+    issuerId: z
+      .string()
+      .min(1)
+      .describe("The App Store Connect issuer id, from the Keys page. The `iss` of that same token."),
+    privateKey: z
+      .string()
+      .min(1)
+      .describe(
+        "The App Store Connect private key, the `.p8` file's contents including its PEM header and footer. Downloadable exactly once from App Store Connect, so it is supplied rather than minted.",
+      ),
+  })
+  .describe("Apple's credentials: the app's identity, and the App Store Connect key that signs server-API calls.");
+export type PaymentsAppleCredentials = z.infer<typeof PaymentsAppleCredentials>;
+
+export const PaymentsGoogleCredentials = z
+  .strictObject({
+    packageName: z
+      .string()
+      .min(1)
+      .describe(
+        "The Android application id. What a Play purchase token is looked up against, and the equivalent of Apple's bundle id.",
+      ),
+    serviceAccountEmail: z
+      .string()
+      .min(1)
+      .describe(
+        "The Google Cloud service account that reads the Play Developer API and is the audience of the Pub/Sub push token.",
+      ),
+    privateKey: z
+      .string()
+      .min(1)
+      .describe(
+        "The service account's private key, as the downloaded JSON's `private_key` field. Supplied, never minted.",
+      ),
+    pubsubAudience: z
+      .string()
+      .min(1)
+      .describe(
+        "The audience the Pub/Sub push OIDC token must claim. Checked on every notification: a token with the right signature and the wrong audience is one issued for somebody else's endpoint.",
+      ),
+  })
+  .describe("Google's credentials: the app's identity, the Play Developer API service account, and the push audience.");
+export type PaymentsGoogleCredentials = z.infer<typeof PaymentsGoogleCredentials>;
+
+export const PaymentsStripeCredentials = z
+  .strictObject({
+    secretKey: z
+      .string()
+      .min(1)
+      .describe(
+        "The Stripe secret API key — `sk_live_…` or `sk_test_…`. Creates Checkout and Billing Portal sessions.",
+      ),
+    webhookSecret: z
+      .string()
+      .min(1)
+      .describe(
+        "The webhook endpoint's signing secret — `whsec_…`. What the `Stripe-Signature` HMAC is checked against, and the one Stripe rotates.",
+      ),
+  })
+  .describe("Stripe's credentials: the secret key that creates hosted sessions, and the webhook signing secret.");
+export type PaymentsStripeCredentials = z.infer<typeof PaymentsStripeCredentials>;
+
+export const PaymentsLemonSqueezyCredentials = z
+  .strictObject({
+    apiKey: z
+      .string()
+      .min(1)
+      .describe(
+        "The Lemon Squeezy API key. Creates hosted checkouts, reads orders and subscriptions, and mints customer-portal links. Account-wide: it returns test-mode objects to a production deployment too, which is why `test_mode` on the object — never the key — decides a purchase's environment.",
+      ),
+    webhookSecret: z
+      .string()
+      .min(1)
+      .describe(
+        "The webhook's signing secret, set when the webhook is created. What the `X-Signature` HMAC-SHA256 over the exact received body is checked against.",
+      ),
+    storeId: z
+      .string()
+      .min(1)
+      .describe(
+        "The Lemon Squeezy store id this deployment sells through. Account-level identity, the way Apple's `bundleId` is, which is why it sits with the credentials rather than in config.",
+      ),
+  })
+  .describe("Lemon Squeezy's credentials: the API key, the webhook signing secret, and the store's identity.");
+export type PaymentsLemonSqueezyCredentials = z.infer<typeof PaymentsLemonSqueezyCredentials>;
+
+export const PaymentsPaddleCredentials = z
+  .strictObject({
+    apiKey: z
+      .string()
+      .min(1)
+      .describe(
+        "The Paddle API key — `pdl_live_apikey_…` or `pdl_sdbx_apikey_…`. Creates transactions and discounts, reads subscriptions and the event stream, and mints customer-portal sessions. It needs `customer_portal_session.write`, or Paddle returns a portal session with no authenticated URLs and the buyer lands on a sign-in page.",
+      ),
+    webhookSecret: z
+      .string()
+      .min(1)
+      .describe(
+        "The notification destination's signing secret — `pdl_ntfset_…`. What the `Paddle-Signature` HMAC-SHA256 over `ts:body` is checked against, and the key the checkout's ownership proof is domain-separated under.",
+      ),
+  })
+  .describe(
+    "Paddle's credentials: the API key, and the notification destination's signing secret. The client token is not here — it is publishable by design and lives in config, because putting it behind the secrets store would suggest verification depended on its secrecy.",
+  );
+export type PaymentsPaddleCredentials = z.infer<typeof PaymentsPaddleCredentials>;
+
+export const PaymentsProviderCredentials = z
+  .strictObject({
+    apple: PaymentsAppleCredentials.optional().describe("Apple's credentials, when the Apple rail is enabled."),
+    google: PaymentsGoogleCredentials.optional().describe("Google's credentials, when the Google rail is enabled."),
+    stripe: PaymentsStripeCredentials.optional().describe("Stripe's credentials, when the Stripe rail is enabled."),
+    lemonSqueezy: PaymentsLemonSqueezyCredentials.optional().describe(
+      "Lemon Squeezy's credentials, when that rail is enabled.",
+    ),
+    paddle: PaymentsPaddleCredentials.optional().describe("Paddle's credentials, when the Paddle rail is enabled."),
+  })
+  .describe(
+    "Every enabled rail's credentials, in one secret. A rail's block is present in full or absent entirely — adding a rail never reshapes storage.",
+  );
+export type PaymentsProviderCredentials = z.infer<typeof PaymentsProviderCredentials>;
+
+/** Payments' secret-registry slice, aggregated into the shared accessor at worker startup. */
+export const paymentsSecretsRegistry = defineSecretRegistry({
+  [PAYMENTS_PROVIDER_SECRET]: {
+    // An encrypted row in the per-environment secrets D1 — where this bundle actually lives. No
+    // wrangler template binds it from the Cloudflare Secrets Store; `pithy payments provision` writes
+    // it through `dispatchSecretWrite` → the manager Workflow → `SystemSecretsStore`, the D1 path.
+    backend: "d1",
+    scope: "environment",
+    rotatable: true,
+    valueType: "json",
+    schema: PaymentsProviderCredentials,
+    // `obtained`, and it always will be: a rail's key authenticates against that rail, so a minted one
+    // authenticates against nothing and hides the real gap behind a filled-in field.
+    origin: { kind: "obtained", issuer: "other", documentation: PAYMENTS_CREDENTIALS_PAGE },
+    // `manual`, and note it does not follow from `rotatable: true`. `rotatable` says the store may hold
+    // two live versions of this bundle at once — which it must, because a Stripe webhook signed under
+    // the old secret can arrive after the new one is written. Who performs the replacement is a human in
+    // a console, whatever the store can hold while they do it.
+    rotation: { kind: "manual", issuer: "other", documentation: PAYMENTS_CREDENTIALS_PAGE },
+  },
+});
+
+/**
+ * The credentials for one rail, or a refusal.
+ *
+ * A rail enabled in `pithy.config.ts` whose credentials were never provisioned is a 404, not a 500: from the
+ * caller's side that payment method genuinely is not available here, and telling a client which of config or
+ * provisioning is missing tells it about our deployment. `detail` carries the distinction for the operator.
+ *
+ * `action` carries the console. Which rail is missing is known here, so the one page out of five that
+ * answers "where do I get one" is known here too — and this is the moment the question is being asked.
+ */
+export function railCredentials<R extends PaymentsRail>(
+  credentials: PaymentsProviderCredentials,
+  rail: R,
+): NonNullable<PaymentsProviderCredentials[R]> {
+  const block = credentials[rail];
+  if (!block) {
+    throw new PaymentsRailNotConfiguredError({
+      detail: `The ${rail} rail has no credentials in "${PAYMENTS_PROVIDER_SECRET}" for this environment. Run \`pithy secrets set\` for it.`,
+      action: `Take the ${rail} credentials from ${PAYMENTS_RAIL_CONSOLES[rail]} and set them with \`pithy secrets set ${PAYMENTS_PROVIDER_SECRET}\`.`,
+    });
+  }
+  return block as NonNullable<PaymentsProviderCredentials[R]>;
+}

package/src/seeds/example.ts

@@ -0,0 +1,181 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { EXAMPLE_ADA, EXAMPLE_ALAN, EXAMPLE_GRACE } from "@pithy-sh/core/src/seed/exampleIdentities";
+import { d1SeedGroup, defineSeed, type SeedSet } from "@pithy-sh/core/src/seed/seed";
+import { PaymentsEntitlement } from "../data/entitlement";
+import { PaymentsPurchase } from "../data/purchase";
+import { PAYMENTS_ENTITLEMENTS_TABLE, PAYMENTS_PURCHASES_TABLE } from "../data/tables";
+
+/**
+ * Three purchases and the entitlements they derive, for the canonical example cast.
+ *
+ * The set is spread deliberately rather than repeated: **Ada** holds a live Apple subscription, **Grace**
+ * a Stripe non-consumable she owns forever, **Alan** a refunded Google consumable. That is one row per
+ * rail, one per product type, and the three purchase states anything reading this table has to handle —
+ * so a fresh `dev` backend can render a real subscription screen, a real receipt, and a real refund
+ * without anybody authoring a fixture first.
+ *
+ * The users are the shared cast from `@pithy-sh/core`, so these purchases belong to the same people
+ * `auth` seeds and `ledger` opens balances for. Order 250 puts them after auth's users (100), exactly the
+ * way the migration registry encodes a dependency.
+ *
+ * **Every row is a `user` subject, and a project on `billingSubject: "organization"` gets rows that
+ * resolve for nobody.** That is honest rather than a bug. The shared cast is three people; the kit has no
+ * example organization, and inventing one here would mint an id nothing else joins to — no `auth` row, no
+ * membership, nothing the adopter's own subject seam would ever return. So the fixture shows the shape of
+ * the tables and the states a reader must handle, and under organization billing the only real subjects
+ * are the adopter's own. Pinning it to `EXAMPLE_ADA/GRACE/ALAN` is what keeps the set idempotent and
+ * connected; a fabricated organization would be neither.
+ *
+ * **Everything is fixed — the ids and the clock.** `pithy seed` is `INSERT OR IGNORE`, so a generated
+ * UUID would give Ada a second subscription on every run. A fixed `CREATED_AT` does the same job for the
+ * timestamps.
+ *
+ * **No payloads worth the name.** The `payload` column really holds a verified provider response, and a
+ * real one is a bearer artifact. A committed fixture gets an identifier and nothing else.
+ *
+ * Composed in only when the project turns on `seed.includeExamples`, and only for `dev` and `staging` —
+ * an example fixture never targets production, whatever that setting says.
+ */
+
+/** Where this set sorts in the whole project's seed registry. After auth (100), which owns these users. */
+const PAYMENTS_EXAMPLE_SEED_ORDER = 250;
+
+/** Fixed ids, so the fixture is idempotent and an entitlement's provenance cannot drift off its purchase. */
+const PRO_PURCHASE_ID = "b4e1f2a0-6c3d-4f18-9a52-1d7e8c0b3f41";
+const ADS_PURCHASE_ID = "c5f2a3b1-7d4e-4a29-8b63-2e8f9d1c4a52";
+const COINS_PURCHASE_ID = "d6a3b4c2-8e5f-4b3a-9c74-3f9a0e2d5b63";
+
+const PRO_ENTITLEMENT_ID = "e7b4c5d3-9f60-4c4b-8d85-4a0b1f3e6c74";
+const ADS_ENTITLEMENT_ID = "f8c5d6e4-a071-4d5c-9e96-5b1c2a4f7d85";
+
+/** One fixed moment every row was written at. The demo is about state, not about a calendar. */
+const CREATED_AT = new Date("2026-01-01T00:00:00.000Z");
+
+/**
+ * When Ada's subscription runs to.
+ *
+ * Deliberately far out rather than `now + 30 days`. A computed date would make the fixture depend on when
+ * it ran, which breaks the one property that matters — that re-seeding writes identical rows — and the
+ * read path evaluates `expiresAt` on every request, so a date in the past would quietly turn the live
+ * subscription into a lapsed one the day after somebody seeded it.
+ */
+const RENEWS_AT = new Date("2099-01-01T00:00:00.000Z");
+
+/** When Alan asked for his money back. */
+const REFUNDED_AT = new Date("2026-01-08T00:00:00.000Z");
+
+export const paymentsExampleSeed: SeedSet = defineSeed({
+  name: "example",
+  order: PAYMENTS_EXAMPLE_SEED_ORDER,
+  environments: ["dev", "staging"],
+  example: true,
+  d1: [
+    d1SeedGroup("app", PAYMENTS_PURCHASES_TABLE, PaymentsPurchase, [
+      {
+        id: PRO_PURCHASE_ID,
+        subjectType: "user",
+        subjectId: EXAMPLE_ADA.id,
+        rail: "apple",
+        role: "charge",
+        providerTransactionId: "2000000512345678",
+        productId: "pro_monthly",
+        providerProductId: "com.example.pro.monthly",
+        type: "subscription",
+        status: "active",
+        // Sandbox, because a seeded environment is dev or staging and a purchase carries where it happened.
+        environment: "sandbox",
+        purchasedAt: CREATED_AT,
+        expiresAt: RENEWS_AT,
+        revokedAt: null,
+        resumesAt: null,
+        // A renewal chains back to the transaction that started the subscription; this is that one.
+        originalTransactionId: "2000000512345678",
+        amountMinor: 999,
+        currency: "USD",
+        providerEventAt: CREATED_AT,
+        payload: { transactionId: "2000000512345678", type: "Auto-Renewable Subscription" },
+        createdAt: CREATED_AT,
+        updatedAt: CREATED_AT,
+      },
+      {
+        id: ADS_PURCHASE_ID,
+        subjectType: "user",
+        subjectId: EXAMPLE_GRACE.id,
+        rail: "stripe",
+        role: "charge",
+        providerTransactionId: "pi_3ExampleRemoveAds",
+        productId: "remove_ads",
+        providerProductId: "price_example_remove_ads",
+        type: "non_consumable",
+        status: "active",
+        environment: "sandbox",
+        purchasedAt: CREATED_AT,
+        // Owned forever. Null is what makes the read path stop checking a clock for this one.
+        expiresAt: null,
+        revokedAt: null,
+        resumesAt: null,
+        originalTransactionId: null,
+        amountMinor: 299,
+        currency: "USD",
+        providerEventAt: CREATED_AT,
+        payload: { id: "pi_3ExampleRemoveAds", object: "payment_intent" },
+        createdAt: CREATED_AT,
+        updatedAt: CREATED_AT,
+      },
+      {
+        id: COINS_PURCHASE_ID,
+        subjectType: "user",
+        subjectId: EXAMPLE_ALAN.id,
+        rail: "google",
+        role: "charge",
+        providerTransactionId: "GPA.3300-0000-0000-00000",
+        productId: "coins_100",
+        providerProductId: "coins_100",
+        type: "consumable",
+        status: "refunded",
+        environment: "sandbox",
+        purchasedAt: CREATED_AT,
+        expiresAt: null,
+        revokedAt: REFUNDED_AT,
+        resumesAt: null,
+        originalTransactionId: null,
+        amountMinor: 199,
+        currency: "USD",
+        providerEventAt: REFUNDED_AT,
+        payload: { orderId: "GPA.3300-0000-0000-00000", purchaseState: 0 },
+        createdAt: CREATED_AT,
+        updatedAt: REFUNDED_AT,
+      },
+    ]),
+    d1SeedGroup("app", PAYMENTS_ENTITLEMENTS_TABLE, PaymentsEntitlement, [
+      {
+        id: PRO_ENTITLEMENT_ID,
+        subjectType: "user",
+        subjectId: EXAMPLE_ADA.id,
+        entitlement: "pro",
+        active: true,
+        expiresAt: RENEWS_AT,
+        sourcePurchaseId: PRO_PURCHASE_ID,
+        manual: false,
+        createdAt: CREATED_AT,
+        updatedAt: CREATED_AT,
+      },
+      {
+        id: ADS_ENTITLEMENT_ID,
+        subjectType: "user",
+        subjectId: EXAMPLE_GRACE.id,
+        entitlement: "ads_removed",
+        active: true,
+        expiresAt: null,
+        sourcePurchaseId: ADS_PURCHASE_ID,
+        manual: false,
+        createdAt: CREATED_AT,
+        updatedAt: CREATED_AT,
+      },
+      // Alan gets no row, and that is the derivation rather than an omission: a consumable credits a
+      // balance, so a refunded one leaves nothing in the read model to take away.
+    ]),
+  ],
+});

package/src/version.generated.ts

@@ -0,0 +1,16 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+// GENERATED by scripts/stampVersions.ts — do not edit by hand. Regenerate with `bun run stamp-versions`.
+//
+// A Worker cannot read its own package.json, so this is how @pithy-sh/payments knows its own version at
+// runtime. The capability attaches it, and `GET /control-plane/manifest` reports it per capability —
+// which is what answers "should this project upgrade" and "is this customer exposed to what we just
+// fixed". Those questions are only answerable per module, because a project composes some capabilities
+// and not others.
+
+/** This package's npm name — the join key against a release feed. */
+export const PACKAGE_NAME = "@pithy-sh/payments";
+
+/** This package's version, stamped from its own package.json at generation time. */
+export const PACKAGE_VERSION = "0.1.0";