@hearthkit/payments 0.1.0

package/src/payments-input-invalid.test.ts

@@ -0,0 +1,201 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres'
+import { afterAll, describe, expect, it } from 'vitest'
+import { expectPaymentsFailure } from '../test-fixtures/payments-gate-expectations.ts'
+import { defineGateFileContext } from '../test-fixtures/payments-gate-file-context.ts'
+import {
+  createGateDrizzleClientForUrl,
+  unreachableGateDatabaseUrl,
+} from '../test-fixtures/payments-gate-postgres-database.ts'
+import {
+  deadStripeApiBaseUrl,
+  gateCancelUrl,
+  gatePaymentsCatalog,
+  gateRelativeRedirectUrl,
+  gateReturnUrl,
+  gateSuccessUrl,
+  reserveDeadLoopbackPort,
+  uniqueGateBillingContactEmail,
+  uniqueGateBillingReferenceId,
+  uniqueGatePaymentsCatalogNames,
+} from '../test-fixtures/payments-gate-values.ts'
+import {
+  createGatePaymentsClient,
+  loadHearthkitPaymentsEntry,
+  type HearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import type {
+  CreateCheckoutSessionOptions,
+  PaymentsClient,
+  PaymentsInvalidFieldName,
+} from './payments-contract.ts'
+
+/**
+ * Every caller-supplied value is a plain string or number on the options object and is validated at
+ * runtime before any service is contacted, which is the same deliberate departure email made for `to`
+ * and auth made for `email`: these values always originate from user input or from an HTTP request.
+ *
+ * That "before any service is contacted" is what this file proves rather than assumes. The client is
+ * built with its Stripe API base URL on a closed local port and its Drizzle client on another, so a
+ * call that reached either service would come back payments-stripe-unreachable or
+ * payments-database-unavailable instead of the input failure each case asserts.
+ */
+
+type InvalidInputCase = {
+  caseName: string
+  invalidFieldName: PaymentsInvalidFieldName
+  overrides: Partial<CreateCheckoutSessionOptions>
+}
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  paymentsClient: PaymentsClient
+  subscriptionPriceName: string
+  closeDatabaseClient: () => Promise<void>
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  const { drizzleClient, closeDatabaseClient } = createGateDrizzleClientForUrl(
+    unreachableGateDatabaseUrl,
+    paymentsEntry.hearthkitPaymentsDrizzleSchema,
+  )
+  const catalogNames = uniqueGatePaymentsCatalogNames('input')
+  const paymentsClient = createGatePaymentsClient({
+    paymentsEntry,
+    drizzleClient: drizzleClient as NodePgDatabase<Record<string, unknown>>,
+    paymentsCatalog: gatePaymentsCatalog(catalogNames),
+    stripeApiBaseUrl: deadStripeApiBaseUrl(await reserveDeadLoopbackPort()),
+  })
+  return {
+    paymentsEntry,
+    paymentsClient,
+    subscriptionPriceName: catalogNames.subscriptionPriceName,
+    closeDatabaseClient,
+  }
+})
+
+afterAll(async () => {
+  await gateFile.releaseIfCreated(({ closeDatabaseClient }) => closeDatabaseClient())
+})
+
+describe('payments-input-invalid', () => {
+  it('rejects every caller-supplied value createCheckoutSession takes, naming the field and contacting no service', async () => {
+    const { paymentsEntry, paymentsClient, subscriptionPriceName } = await gateFile.read()
+    const validOptions: CreateCheckoutSessionOptions = {
+      paymentsClient,
+      billingReferenceId: uniqueGateBillingReferenceId('input'),
+      billingContactEmail: uniqueGateBillingContactEmail('input'),
+      priceName: subscriptionPriceName,
+      successUrl: gateSuccessUrl,
+      cancelUrl: gateCancelUrl,
+    }
+
+    const invalidInputCases: readonly InvalidInputCase[] = [
+      {
+        caseName: 'an empty billing reference',
+        invalidFieldName: 'billing-reference-id',
+        overrides: { billingReferenceId: '' },
+      },
+      {
+        caseName: 'an address that is not one',
+        invalidFieldName: 'billing-contact-email',
+        overrides: { billingContactEmail: 'gate-not-an-address' },
+      },
+      {
+        // A well-formed name the catalog does not have is payments-price-not-found, not this: a name
+        // that is not lowercase kebab-case could never be a Stripe lookup_key in the first place.
+        caseName: 'a price name that is not lowercase kebab-case',
+        invalidFieldName: 'price-name',
+        overrides: { priceName: 'Gate Not Kebab Case' },
+      },
+      {
+        caseName: 'a quantity of zero',
+        invalidFieldName: 'quantity',
+        overrides: { quantity: 0 },
+      },
+      {
+        caseName: 'a fractional quantity',
+        invalidFieldName: 'quantity',
+        overrides: { quantity: 1.5 },
+      },
+      {
+        caseName: 'a relative success URL',
+        invalidFieldName: 'success-url',
+        overrides: { successUrl: gateRelativeRedirectUrl },
+      },
+      {
+        caseName: 'a relative cancel URL',
+        invalidFieldName: 'cancel-url',
+        overrides: { cancelUrl: gateRelativeRedirectUrl },
+      },
+    ]
+
+    const wrongAnswers: string[] = []
+    for (const invalidInputCase of invalidInputCases) {
+      const result = await paymentsEntry.createCheckoutSession({
+        ...validOptions,
+        ...invalidInputCase.overrides,
+      })
+      const failure = expectPaymentsFailure(result, 'payments-input-invalid')
+      if (failure.invalidFieldName !== invalidInputCase.invalidFieldName) {
+        wrongAnswers.push(
+          `${invalidInputCase.caseName} was named ${failure.invalidFieldName}, expected ${invalidInputCase.invalidFieldName}`,
+        )
+      }
+      // The reason states the rule; it never echoes the rejected value back at a caller who may log it.
+      expect(failure.invalidFieldReason.length).toBeGreaterThan(0)
+    }
+    expect(
+      wrongAnswers,
+      'invalidFieldName is an enum so a gate asserts on it, not on message text',
+    ).toEqual([])
+
+    // The control that keeps every case above non-vacuous: the same options with nothing wrong get
+    // past validation and fail on a service instead, so each failure is attributable to its field.
+    const nothingWrong = await paymentsEntry.createCheckoutSession(validOptions)
+    expect(nothingWrong.kind).not.toBe('payments-input-invalid')
+  })
+
+  it('rejects the values createCustomerPortalSession and handleStripeWebhook take, naming the field', async () => {
+    const { paymentsEntry, paymentsClient } = await gateFile.read()
+
+    const emptyReference = await paymentsEntry.createCustomerPortalSession({
+      paymentsClient,
+      billingReferenceId: '',
+      returnUrl: gateReturnUrl,
+    })
+    expect(expectPaymentsFailure(emptyReference, 'payments-input-invalid').invalidFieldName).toBe(
+      'billing-reference-id',
+    )
+
+    const relativeReturnUrl = await paymentsEntry.createCustomerPortalSession({
+      paymentsClient,
+      billingReferenceId: uniqueGateBillingReferenceId('input-portal'),
+      returnUrl: gateRelativeRedirectUrl,
+    })
+    expect(
+      expectPaymentsFailure(relativeReturnUrl, 'payments-input-invalid').invalidFieldName,
+    ).toBe('return-url')
+
+    // rawRequestBody must be the exact bytes Stripe sent. A parsed object is the mistake a Next route
+    // handler makes by calling request.json() instead of request.text(), and stripe@22.6.1 throws
+    // rather than returning for it, so this package rejects it as input before verification.
+    const parsedBody = await paymentsEntry.handleStripeWebhook({
+      paymentsClient,
+      rawRequestBody: { id: 'evt_gate_parsed_object' } as unknown as string,
+      requestHeaders: new Headers(),
+    })
+    expect(expectPaymentsFailure(parsedBody, 'payments-input-invalid').invalidFieldName).toBe(
+      'raw-request-body',
+    )
+
+    // Headers are duck-typed on .get exactly as readAuthSession does it, so Next's read-only headers
+    // pass; an object carrying no .get at all cannot be read and is named rather than thrown on.
+    const headersWithoutGet = await paymentsEntry.handleStripeWebhook({
+      paymentsClient,
+      rawRequestBody: '{"id":"evt_gate_no_headers"}',
+      requestHeaders: { keys: () => [] } as unknown as Headers,
+    })
+    expect(
+      expectPaymentsFailure(headersWithoutGet, 'payments-input-invalid').invalidFieldName,
+    ).toBe('request-headers')
+  })
+})

package/src/payments-purchase-record.ts

@@ -0,0 +1,63 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres'
+import { paymentsPurchaseTable } from './hearthkit-payments-drizzle-schema.ts'
+import { generatePaymentsRowId } from './payments-row-identifier.ts'
+
+/**
+ * The one write of payments_purchase. It upserts on stripeCheckoutSessionId, which is what makes a
+ * replayed delivery write the same values to the same row rather than a second one: idempotency here
+ * is structural rather than a bookkeeping table of processed event ids.
+ */
+
+/** Everything one completed one-time checkout puts in a row; every value comes from the delivery, none from the catalog. */
+export type PaymentsPurchaseRowValues = {
+  billingReferenceId: string
+  stripeCustomerId: string
+  stripeCheckoutSessionId: string
+  stripePaymentIntentId: string | null
+  priceName: string
+  stripePriceId: string
+  currency: string
+  amountTotalMinorUnits: number
+  quantity: number
+  purchasedAt: Date
+  writtenAt: Date
+}
+
+/** Records a completed purchase, or rewrites the same row when Stripe delivers the same session again. */
+export async function upsertPaymentsPurchaseRow(
+  drizzleClient: NodePgDatabase<Record<string, unknown>>,
+  values: PaymentsPurchaseRowValues,
+): Promise<void> {
+  await drizzleClient
+    .insert(paymentsPurchaseTable)
+    .values({
+      id: generatePaymentsRowId('paybuy'),
+      billingReferenceId: values.billingReferenceId,
+      stripeCustomerId: values.stripeCustomerId,
+      stripeCheckoutSessionId: values.stripeCheckoutSessionId,
+      stripePaymentIntentId: values.stripePaymentIntentId,
+      priceName: values.priceName,
+      stripePriceId: values.stripePriceId,
+      currency: values.currency,
+      amountTotalMinorUnits: values.amountTotalMinorUnits,
+      quantity: values.quantity,
+      purchasedAt: values.purchasedAt,
+      createdAt: values.writtenAt,
+      updatedAt: values.writtenAt,
+    })
+    .onConflictDoUpdate({
+      target: paymentsPurchaseTable.stripeCheckoutSessionId,
+      set: {
+        billingReferenceId: values.billingReferenceId,
+        stripeCustomerId: values.stripeCustomerId,
+        stripePaymentIntentId: values.stripePaymentIntentId,
+        priceName: values.priceName,
+        stripePriceId: values.stripePriceId,
+        currency: values.currency,
+        amountTotalMinorUnits: values.amountTotalMinorUnits,
+        quantity: values.quantity,
+        purchasedAt: values.purchasedAt,
+        updatedAt: values.writtenAt,
+      },
+    })
+}

package/src/payments-row-identifier.ts

@@ -0,0 +1,10 @@
+import { randomUUID } from 'node:crypto'
+
+/**
+ * Row ids this package generates. They are ours, not Stripe's and not Better Auth's, and nothing
+ * outside this package may construct one: every table also carries the Stripe id it upserts on, which
+ * is what makes a replayed delivery write the same row rather than a second one.
+ */
+export function generatePaymentsRowId(rowKindPrefix: string): string {
+  return `${rowKindPrefix}_${randomUUID()}`
+}

package/src/payments-stripe-unreachable.test.ts

@@ -0,0 +1,91 @@
+import { afterAll, describe, expect, it } from 'vitest'
+import { expectPaymentsFailure } from '../test-fixtures/payments-gate-expectations.ts'
+import { defineGateFileContext } from '../test-fixtures/payments-gate-file-context.ts'
+import {
+  createVerifiedGatePaymentsDatabase,
+  type GatePaymentsDatabase,
+} from '../test-fixtures/payments-gate-postgres-database.ts'
+import {
+  deadStripeApiBaseUrl,
+  gateCancelUrl,
+  gatePaymentsCatalog,
+  gateSuccessUrl,
+  reserveDeadLoopbackPort,
+  uniqueGateBillingContactEmail,
+  uniqueGateBillingReferenceId,
+  uniqueGatePaymentsCatalogNames,
+} from '../test-fixtures/payments-gate-values.ts'
+import {
+  createGatePaymentsClient,
+  loadHearthkitPaymentsEntry,
+  type HearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import {
+  createCheckoutSessionResultSchema,
+  syncPaymentsCatalogResultSchema,
+  type PaymentsClient,
+} from './payments-contract.ts'
+
+/**
+ * The failure CONTRACT.md Decision 5 keeps stripeApiBaseUrl for. Pointed at a closed local port it
+ * produces payments-stripe-unreachable with no network and no Stripe account, which is what makes
+ * this the sibling of db's database-server-unreachable rather than a failure nobody can gate.
+ *
+ * The database here is real and migrated, so a checkout that writes a customer row before reaching
+ * Stripe still gets that far: the only thing that cannot be reached is Stripe.
+ */
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  paymentsClient: PaymentsClient
+  gateDatabase: GatePaymentsDatabase
+  subscriptionPriceName: string
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  const gateDatabase = await createVerifiedGatePaymentsDatabase('unreachable', paymentsEntry)
+  const catalogNames = uniqueGatePaymentsCatalogNames('unreachable')
+  const paymentsClient = createGatePaymentsClient({
+    paymentsEntry,
+    drizzleClient: gateDatabase.drizzleClient,
+    paymentsCatalog: gatePaymentsCatalog(catalogNames),
+    stripeApiBaseUrl: deadStripeApiBaseUrl(await reserveDeadLoopbackPort()),
+  })
+  return {
+    paymentsEntry,
+    paymentsClient,
+    gateDatabase,
+    subscriptionPriceName: catalogNames.subscriptionPriceName,
+  }
+})
+
+afterAll(async () => {
+  await gateFile.releaseIfCreated(({ gateDatabase }) => gateDatabase.removeGatePaymentsDatabase())
+})
+
+describe('payments-stripe-unreachable', () => {
+  it('reports it from sync and from checkout when the Stripe API base URL is a closed local port', async () => {
+    const { paymentsEntry, paymentsClient, subscriptionPriceName } = await gateFile.read()
+
+    const synced = await paymentsEntry.syncPaymentsCatalog({ paymentsClient })
+    syncPaymentsCatalogResultSchema.parse(synced)
+    const syncFailure = expectPaymentsFailure(synced, 'payments-stripe-unreachable')
+    // Deliberately not asserting a retry count: the SDK retries a closed connection once even when
+    // retries are disabled, so "Request was retried 1 times." is a legal part of this message.
+    expect(syncFailure.stripeFailureDetail.length).toBeGreaterThan(0)
+
+    // The same classification from a different producer, with a price name the catalog really has,
+    // so the call gets past the local map lookup and out to the network before it fails.
+    const checkout = await paymentsEntry.createCheckoutSession({
+      paymentsClient,
+      billingReferenceId: uniqueGateBillingReferenceId('unreachable'),
+      billingContactEmail: uniqueGateBillingContactEmail('unreachable'),
+      priceName: subscriptionPriceName,
+      successUrl: gateSuccessUrl,
+      cancelUrl: gateCancelUrl,
+    })
+    createCheckoutSessionResultSchema.parse(checkout)
+    expect(
+      expectPaymentsFailure(checkout, 'payments-stripe-unreachable').stripeFailureDetail.length,
+    ).toBeGreaterThan(0)
+  })
+})

package/src/payments-subscription-record.ts

@@ -0,0 +1,77 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres'
+import { paymentsSubscriptionTable } from './hearthkit-payments-drizzle-schema.ts'
+import { generatePaymentsRowId } from './payments-row-identifier.ts'
+
+/**
+ * The one write of payments_subscription. It upserts on stripeSubscriptionId, so created, updated and
+ * deleted deliveries for one subscription all land on the same row and a replay moves no count.
+ *
+ * createdAt is this package's own clock rather than the event's, because "most recent subscription"
+ * has to order two rows written seconds apart and Stripe's `created` is only second-resolution.
+ */
+
+/** Everything one subscription delivery puts in a row; the period dates come from the item, not the subscription. */
+export type PaymentsSubscriptionRowValues = {
+  billingReferenceId: string
+  stripeCustomerId: string
+  stripeSubscriptionId: string
+  priceName: string
+  stripePriceId: string
+  status: string
+  quantity: number
+  currentPeriodStart: Date | null
+  currentPeriodEnd: Date | null
+  cancelAtPeriodEnd: boolean
+  canceledAt: Date | null
+  endedAt: Date | null
+  trialStart: Date | null
+  trialEnd: Date | null
+  writtenAt: Date
+}
+
+/** Records what Stripe last said about a subscription, or rewrites the same row when it says it again. */
+export async function upsertPaymentsSubscriptionRow(
+  drizzleClient: NodePgDatabase<Record<string, unknown>>,
+  values: PaymentsSubscriptionRowValues,
+): Promise<void> {
+  await drizzleClient
+    .insert(paymentsSubscriptionTable)
+    .values({
+      id: generatePaymentsRowId('paysub'),
+      billingReferenceId: values.billingReferenceId,
+      stripeCustomerId: values.stripeCustomerId,
+      stripeSubscriptionId: values.stripeSubscriptionId,
+      priceName: values.priceName,
+      stripePriceId: values.stripePriceId,
+      status: values.status,
+      quantity: values.quantity,
+      currentPeriodStart: values.currentPeriodStart,
+      currentPeriodEnd: values.currentPeriodEnd,
+      cancelAtPeriodEnd: values.cancelAtPeriodEnd,
+      canceledAt: values.canceledAt,
+      endedAt: values.endedAt,
+      trialStart: values.trialStart,
+      trialEnd: values.trialEnd,
+      createdAt: values.writtenAt,
+      updatedAt: values.writtenAt,
+    })
+    .onConflictDoUpdate({
+      target: paymentsSubscriptionTable.stripeSubscriptionId,
+      set: {
+        billingReferenceId: values.billingReferenceId,
+        stripeCustomerId: values.stripeCustomerId,
+        priceName: values.priceName,
+        stripePriceId: values.stripePriceId,
+        status: values.status,
+        quantity: values.quantity,
+        currentPeriodStart: values.currentPeriodStart,
+        currentPeriodEnd: values.currentPeriodEnd,
+        cancelAtPeriodEnd: values.cancelAtPeriodEnd,
+        canceledAt: values.canceledAt,
+        endedAt: values.endedAt,
+        trialStart: values.trialStart,
+        trialEnd: values.trialEnd,
+        updatedAt: values.writtenAt,
+      },
+    })
+}

package/src/read-payments-subscription.test.ts

@@ -0,0 +1,126 @@
+import { afterAll, describe, expect, it } from 'vitest'
+import { expectResultKind } from '../test-fixtures/payments-gate-expectations.ts'
+import { defineGateFileContext } from '../test-fixtures/payments-gate-file-context.ts'
+import {
+  createVerifiedGatePaymentsDatabase,
+  type GatePaymentsDatabase,
+} from '../test-fixtures/payments-gate-postgres-database.ts'
+import {
+  buildGateStripeWebhookDelivery,
+  buildGateSubscriptionObject,
+  gateBillingReferenceMetadata,
+  gateNowSecondsSinceEpoch,
+  uniqueGateStripeId,
+} from '../test-fixtures/payments-gate-stripe-events.ts'
+import {
+  gatePaymentsCatalog,
+  uniqueGateBillingReferenceId,
+  uniqueGatePaymentsCatalogNames,
+} from '../test-fixtures/payments-gate-values.ts'
+import {
+  createGatePaymentsClient,
+  loadHearthkitPaymentsEntry,
+  type HearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import { readPaymentsSubscriptionResultSchema, type PaymentsClient } from './payments-contract.ts'
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  paymentsClient: PaymentsClient
+  gateDatabase: GatePaymentsDatabase
+  subscriptionPriceName: string
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  const gateDatabase = await createVerifiedGatePaymentsDatabase('readsub', paymentsEntry)
+  const catalogNames = uniqueGatePaymentsCatalogNames('readsub')
+  const paymentsClient = createGatePaymentsClient({
+    paymentsEntry,
+    drizzleClient: gateDatabase.drizzleClient,
+    paymentsCatalog: gatePaymentsCatalog(catalogNames),
+  })
+  return {
+    paymentsEntry,
+    paymentsClient,
+    gateDatabase,
+    subscriptionPriceName: catalogNames.subscriptionPriceName,
+  }
+})
+
+afterAll(async () => {
+  await gateFile.releaseIfCreated(({ gateDatabase }) => gateDatabase.removeGatePaymentsDatabase())
+})
+
+describe('readPaymentsSubscription', () => {
+  it('reports payments-subscription-absent, which is a normal answer and not a failure, for a reference that has none', async () => {
+    const { paymentsEntry, paymentsClient } = await gateFile.read()
+
+    // Nobody having a subscription is the ordinary state of most accounts. Modelling it as an error
+    // would send every entitlement check's happy path through a catch.
+    const result = await paymentsEntry.readPaymentsSubscription({
+      paymentsClient,
+      billingReferenceId: uniqueGateBillingReferenceId('readsub-none'),
+    })
+    readPaymentsSubscriptionResultSchema.parse(result)
+    expectResultKind(result, 'payments-subscription-absent')
+  })
+
+  it('returns the most recent subscription for a reference whatever its status, rather than the first or the active one', async () => {
+    const { paymentsEntry, paymentsClient, subscriptionPriceName } = await gateFile.read()
+    const billingReferenceId = uniqueGateBillingReferenceId('readsub-latest')
+    const periodStartSeconds = gateNowSecondsSinceEpoch()
+
+    async function deliverSubscription(
+      stripeSubscriptionId: string,
+      subscriptionStatus: string,
+    ): Promise<void> {
+      const delivery = buildGateStripeWebhookDelivery(paymentsClient, {
+        stripeEventType: 'customer.subscription.created',
+        eventDataObject: buildGateSubscriptionObject({
+          stripeSubscriptionId,
+          stripeCustomerId: uniqueGateStripeId('cus'),
+          subscriptionStatus,
+          metadata: gateBillingReferenceMetadata(billingReferenceId),
+          items: [
+            {
+              stripePriceId: uniqueGateStripeId('price'),
+              priceLookupKey: subscriptionPriceName,
+              quantity: 1,
+              currentPeriodStartSeconds: periodStartSeconds,
+              currentPeriodEndSeconds: periodStartSeconds + 2_592_000,
+            },
+          ],
+        }),
+      })
+      const result = await paymentsEntry.handleStripeWebhook({
+        paymentsClient,
+        rawRequestBody: delivery.rawRequestBody,
+        requestHeaders: delivery.requestHeaders,
+      })
+      expect(expectResultKind(result, 'payments-webhook-processed').webhookOutcome).toBe(
+        'subscription-upserted',
+      )
+    }
+
+    const olderSubscriptionId = uniqueGateStripeId('sub')
+    const newerSubscriptionId = uniqueGateStripeId('sub')
+    await deliverSubscription(olderSubscriptionId, 'active')
+    // "Most recent" means greatest createdAt, which this package writes from its own clock. A quarter
+    // of a second between the two writes puts them in different milliseconds with room to spare, so
+    // the id-descending tiebreak — whose values no gate can predict — never has to decide this.
+    await new Promise((resolve) => setTimeout(resolve, 250))
+    await deliverSubscription(newerSubscriptionId, 'canceled')
+
+    const result = await paymentsEntry.readPaymentsSubscription({
+      paymentsClient,
+      billingReferenceId,
+    })
+    readPaymentsSubscriptionResultSchema.parse(result)
+    const found = expectResultKind(result, 'payments-subscription-found').paymentsSubscription
+
+    expect(String(found.stripeSubscriptionId)).toBe(newerSubscriptionId)
+    // The newer row is the canceled one on purpose. The row is returned whatever its status and the
+    // caller reads status and decides, so an implementation that filtered to the active ones would
+    // hand back the older subscription here and fail.
+    expect(found.status).toBe('canceled')
+  })
+})

package/src/read-payments-subscription.ts

@@ -0,0 +1,61 @@
+import { desc, eq } from 'drizzle-orm'
+import { paymentsSubscriptionTable } from './hearthkit-payments-drizzle-schema.ts'
+import {
+  billingReferenceIdSchema,
+  paymentsClientSchema,
+  paymentsSubscriptionSchema,
+  type ReadPaymentsSubscriptionOptions,
+  type ReadPaymentsSubscriptionResult,
+} from './payments-contract.ts'
+import {
+  paymentsInputInvalidFailure,
+  paymentsRequestFailedFailure,
+} from './payments-failure-results.ts'
+import { thrownPaymentsErrorToFailure } from './thrown-payments-error-failure.ts'
+
+/**
+ * The most recent subscription row for a reference, whatever its status. Nobody having a subscription
+ * is a normal answer and comes back as payments-subscription-absent rather than a failure, because
+ * modelling it as an error would send every entitlement check's happy path through a catch.
+ *
+ * "Most recent" is the greatest createdAt, which this package writes from its own clock, with id
+ * descending as the tiebreak so the answer is deterministic. The row is returned whatever its status:
+ * the caller reads status and decides, comparing against paymentsActiveSubscriptionStatuses.
+ */
+export async function readPaymentsSubscription(
+  options: ReadPaymentsSubscriptionOptions,
+): Promise<ReadPaymentsSubscriptionResult> {
+  if (!paymentsClientSchema.safeParse(options.paymentsClient).success) {
+    return paymentsInputInvalidFailure('drizzle-client')
+  }
+  const parsedReference = billingReferenceIdSchema.safeParse(options.billingReferenceId)
+  if (!parsedReference.success) {
+    return paymentsInputInvalidFailure('billing-reference-id')
+  }
+
+  let subscriptionRows: (typeof paymentsSubscriptionTable.$inferSelect)[]
+  try {
+    subscriptionRows = await options.paymentsClient.drizzleClient
+      .select()
+      .from(paymentsSubscriptionTable)
+      .where(eq(paymentsSubscriptionTable.billingReferenceId, String(parsedReference.data)))
+      .orderBy(desc(paymentsSubscriptionTable.createdAt), desc(paymentsSubscriptionTable.id))
+      .limit(1)
+  } catch (thrownValue) {
+    return thrownPaymentsErrorToFailure(thrownValue, options.paymentsClient)
+  }
+
+  const subscriptionRow = subscriptionRows[0]
+  if (subscriptionRow === undefined) {
+    return { kind: 'payments-subscription-absent' }
+  }
+
+  const parsedSubscription = paymentsSubscriptionSchema.safeParse(subscriptionRow)
+  if (!parsedSubscription.success) {
+    return paymentsRequestFailedFailure({
+      paymentsFailureDetail:
+        'a payments_subscription row does not match the shape this package writes, so the table was written by something else',
+    })
+  }
+  return { kind: 'payments-subscription-found', paymentsSubscription: parsedSubscription.data }
+}

package/src/redact-payments-secrets.ts

@@ -0,0 +1,18 @@
+// The literal that stands in for a secret wherever one would otherwise have reached a message. It is
+// a fixed string rather than a length-preserving mask so nothing about the secret survives redaction.
+const redactedSecretMarker = '[redacted]'
+
+/**
+ * Replaces every occurrence of the configured secrets in third-party error text, so the Stripe SDK's
+ * own words can be quoted in a failure without carrying the API key or the signing secret out with
+ * them; the rule is absolute but the words belong to somebody else.
+ */
+export function redactPaymentsSecrets(text: string, secrets: readonly string[]): string {
+  let redactedText = text
+  for (const secret of secrets) {
+    if (secret.length > 0) {
+      redactedText = redactedText.replaceAll(secret, redactedSecretMarker)
+    }
+  }
+  return redactedText
+}