@hearthkit/payments 0.1.0

package/src/sync-payments-catalog.test.ts

@@ -0,0 +1,208 @@
+import { afterAll, describe, expect, it } from 'vitest'
+import {
+  expectPaymentsFailure,
+  expectResultKind,
+  sortedGateNames,
+} 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 {
+  archiveGateStripeCatalog,
+  assertGateStripeIsTestMode,
+} from '../test-fixtures/payments-gate-stripe-account.ts'
+import {
+  gatePaymentsCatalog,
+  gateStripeSecretKey,
+  gateWrongStripeSecretKey,
+  hasGateStripeSecretKey,
+  uniqueGatePaymentsCatalogNames,
+  type GatePaymentsCatalogNames,
+} from '../test-fixtures/payments-gate-values.ts'
+import {
+  createGatePaymentsClient,
+  loadHearthkitPaymentsEntry,
+  type HearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import {
+  stripeForbiddenHttpStatus,
+  stripeUnauthorizedHttpStatus,
+  syncPaymentsCatalogResultSchema,
+  type PaymentsClient,
+  type PaymentsSyncedPrice,
+} from './payments-contract.ts'
+
+/**
+ * All of syncPaymentsCatalog is live: it is the one function whose whole job is to change a Stripe
+ * account, and nothing offline can stand in for that. It also settles the one thing CONTRACT.md lists
+ * under Still not verified that everything else in sync depends on — whether Stripe accepts a
+ * lowercase kebab-case custom product id, which is what makes sync idempotent without a search call.
+ *
+ * No database is needed here at all, so the Drizzle client points at a closed port: sync writes
+ * nothing locally, and a sync that queried would fail these gates rather than pass them.
+ */
+
+const createdStripePrices: PaymentsSyncedPrice[] = []
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  catalogNames: GatePaymentsCatalogNames
+  buildLiveClient: (unitAmountMinorUnits?: number, stripeSecretKey?: string) => PaymentsClient
+  closeDatabaseClient: () => Promise<void>
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  const { drizzleClient, closeDatabaseClient } = createGateDrizzleClientForUrl(
+    unreachableGateDatabaseUrl,
+    paymentsEntry.hearthkitPaymentsDrizzleSchema,
+  )
+  const catalogNames = uniqueGatePaymentsCatalogNames('sync')
+  return {
+    paymentsEntry,
+    catalogNames,
+    buildLiveClient: (unitAmountMinorUnits, stripeSecretKey = gateStripeSecretKey) =>
+      createGatePaymentsClient({
+        paymentsEntry,
+        drizzleClient,
+        paymentsCatalog: gatePaymentsCatalog(catalogNames, unitAmountMinorUnits),
+        stripeSecretKey,
+      }),
+    closeDatabaseClient,
+  }
+})
+
+/**
+ * The first sync of this run's catalog, with the test-mode guard asserted on the object Stripe
+ * answered with before anything else is created. Every live gate below reads this, so the guard runs
+ * once and holds for all of them however the file is ordered.
+ */
+const liveGateFile = defineGateFileContext<{
+  liveClient: PaymentsClient
+  firstSyncedPrices: readonly PaymentsSyncedPrice[]
+}>(async () => {
+  const { paymentsEntry, buildLiveClient } = await gateFile.read()
+  const liveClient = buildLiveClient()
+  const synced = expectResultKind(
+    await paymentsEntry.syncPaymentsCatalog({ paymentsClient: liveClient }),
+    'payments-catalog-synced',
+  )
+  assertGateStripeIsTestMode(synced.stripeLivemode)
+  createdStripePrices.push(...synced.syncedPrices)
+  return { liveClient, firstSyncedPrices: synced.syncedPrices }
+})
+
+afterAll(async () => {
+  await liveGateFile.releaseIfCreated(({ liveClient }) =>
+    archiveGateStripeCatalog(liveClient, createdStripePrices),
+  )
+  await gateFile.releaseIfCreated(({ closeDatabaseClient }) => closeDatabaseClient())
+})
+
+describe('syncPaymentsCatalog', () => {
+  it.skipIf(!hasGateStripeSecretKey)(
+    'creates a Stripe price for every catalog price on a first run, under a product whose id is the catalog product name',
+    async () => {
+      const { catalogNames } = await gateFile.read()
+      const { firstSyncedPrices } = await liveGateFile.read()
+
+      syncPaymentsCatalogResultSchema.parse({
+        kind: 'payments-catalog-synced',
+        syncedPrices: firstSyncedPrices,
+        stripeLivemode: false,
+      })
+      expect(sortedGateNames(firstSyncedPrices.map((price) => price.priceName))).toEqual(
+        sortedGateNames([catalogNames.subscriptionPriceName, catalogNames.oneTimePriceName]),
+      )
+      for (const syncedPrice of firstSyncedPrices) {
+        expect(syncedPrice.syncAction).toBe('created')
+        // The measurement CONTRACT.md says everything else in sync depends on: products.create
+        // accepts a caller-supplied id, and this asserts Stripe really accepts this id SHAPE. If it
+        // does not, sync needs a different identity mechanism and the contract comes back for a line.
+        expect(String(syncedPrice.stripeProductId)).toBe(catalogNames.productName)
+        expect(String(syncedPrice.stripePriceId).length).toBeGreaterThan(0)
+      }
+    },
+  )
+
+  it.skipIf(!hasGateStripeSecretKey)(
+    'reports every price unchanged on a second run of the same catalog, reusing the product rather than duplicating it',
+    async () => {
+      const { paymentsEntry } = await gateFile.read()
+      const { liveClient, firstSyncedPrices } = await liveGateFile.read()
+
+      const result = await paymentsEntry.syncPaymentsCatalog({ paymentsClient: liveClient })
+      syncPaymentsCatalogResultSchema.parse(result)
+      const synced = expectResultKind(result, 'payments-catalog-synced')
+      expect(synced.stripeLivemode).toBe(false)
+
+      // Idempotent means every price reports unchanged, and it means the product id was supplied
+      // rather than searched for: a second products.create on an id that already exists must not
+      // become a second product or a resource_already_exists failure.
+      for (const syncedPrice of synced.syncedPrices) {
+        expect(syncedPrice.syncAction).toBe('unchanged')
+      }
+      const firstPriceIdByName = new Map(
+        firstSyncedPrices.map((price) => [String(price.priceName), String(price.stripePriceId)]),
+      )
+      for (const syncedPrice of synced.syncedPrices) {
+        expect(String(syncedPrice.stripePriceId)).toBe(
+          firstPriceIdByName.get(String(syncedPrice.priceName)),
+        )
+      }
+    },
+  )
+
+  it.skipIf(!hasGateStripeSecretKey)(
+    'replaces a price whose amount changed, moving the lookup key onto a new Stripe price id',
+    async () => {
+      const { paymentsEntry, buildLiveClient } = await gateFile.read()
+      const { firstSyncedPrices } = await liveGateFile.read()
+
+      // Stripe prices are immutable in amount and currency, so the same lookup key at a new amount
+      // cannot be an update: a new price is created with transfer_lookup_key and the superseded one
+      // is archived. Existing subscriptions stay on the old price, which is Stripe's behaviour and
+      // not something this package migrates.
+      const repricedClient = buildLiveClient(2900)
+      const result = await paymentsEntry.syncPaymentsCatalog({ paymentsClient: repricedClient })
+      syncPaymentsCatalogResultSchema.parse(result)
+      const synced = expectResultKind(result, 'payments-catalog-synced')
+      createdStripePrices.push(...synced.syncedPrices)
+
+      const firstPriceIdByName = new Map(
+        firstSyncedPrices.map((price) => [String(price.priceName), String(price.stripePriceId)]),
+      )
+      for (const syncedPrice of synced.syncedPrices) {
+        expect(syncedPrice.syncAction, String(syncedPrice.priceName)).toBe('replaced')
+        // Nothing stores a Stripe price id as an identity, precisely because this happens. The
+        // catalog keys on the lookup key instead, which is stable across a replacement.
+        expect(String(syncedPrice.stripePriceId)).not.toBe(
+          firstPriceIdByName.get(String(syncedPrice.priceName)),
+        )
+      }
+    },
+  )
+
+  it.skipIf(!hasGateStripeSecretKey)(
+    'reports payments-stripe-unauthorized when Stripe refuses the API key, without echoing the key back',
+    async () => {
+      const { paymentsEntry, buildLiveClient } = await gateFile.read()
+      // A well-formed value that is not a key any account issued. This is the first-run state of
+      // every project that pasted the wrong key, and without a name it would arrive as an opaque
+      // catch-all in the one package that is holding somebody's money.
+      const wrongKeyClient = buildLiveClient(undefined, gateWrongStripeSecretKey)
+
+      const result = await paymentsEntry.syncPaymentsCatalog({ paymentsClient: wrongKeyClient })
+      syncPaymentsCatalogResultSchema.parse(result)
+      const failure = expectPaymentsFailure(result, 'payments-stripe-unauthorized')
+
+      // 401 is a wrong or revoked key and 403 is a restricted key without the permission. One
+      // variant, because the caller does the same thing with both; stripeErrorStatus is carried so
+      // a reader sees which. CONTRACT.md lists which one Stripe actually answers with as unmeasured.
+      expect([stripeUnauthorizedHttpStatus, stripeForbiddenHttpStatus]).toContain(
+        failure.stripeErrorStatus,
+      )
+      expect(failure.stripeFailureDetail.length).toBeGreaterThan(0)
+    },
+  )
+})

package/src/sync-payments-catalog.ts

@@ -0,0 +1,65 @@
+import {
+  paymentsClientSchema,
+  paymentsPriceNameSchema,
+  stripePriceIdSchema,
+  stripeProductIdSchema,
+  type PaymentsSyncedPrice,
+  type SyncPaymentsCatalogOptions,
+  type SyncPaymentsCatalogResult,
+} from './payments-contract.ts'
+import { paymentsInputInvalidFailure } from './payments-failure-results.ts'
+import { ensureStripeCatalogProduct } from './stripe-catalog-product-sync.ts'
+import { syncStripeCatalogPrice } from './stripe-catalog-price-sync.ts'
+import { thrownPaymentsErrorToFailure } from './thrown-payments-error-failure.ts'
+
+/**
+ * Pushes the catalog the client holds to Stripe and reports what it did to each price. It writes
+ * nothing locally: sync changes a Stripe account and nothing else, so it needs no database at all.
+ *
+ * Idempotent, because both halves are keyed on names the app chose: the product name is the Stripe
+ * product id and the price name is the Stripe price lookup key. A second run over an unchanged
+ * catalog therefore reports every price unchanged and creates nothing.
+ *
+ * stripeLivemode is read off the first object Stripe answered with, whose own generated type says it
+ * is true in live mode and false in test mode. That is the guard a caller checks before creating
+ * anything else, and it is a measurement rather than a match on an API key prefix.
+ */
+export async function syncPaymentsCatalog(
+  options: SyncPaymentsCatalogOptions,
+): Promise<SyncPaymentsCatalogResult> {
+  if (!paymentsClientSchema.safeParse(options.paymentsClient).success) {
+    return paymentsInputInvalidFailure('drizzle-client')
+  }
+
+  const { stripeClient, paymentsCatalog } = options.paymentsClient
+  const syncedPrices: PaymentsSyncedPrice[] = []
+  let stripeLivemode: boolean | undefined
+
+  try {
+    for (const catalogProduct of paymentsCatalog.products) {
+      const stripeProduct = await ensureStripeCatalogProduct(stripeClient, catalogProduct)
+      stripeLivemode ??= stripeProduct.livemode
+
+      for (const catalogPrice of catalogProduct.prices) {
+        const priceSync = await syncStripeCatalogPrice(stripeClient, stripeProduct.id, catalogPrice)
+        stripeLivemode ??= priceSync.stripePrice.livemode
+        syncedPrices.push({
+          priceName: paymentsPriceNameSchema.parse(String(catalogPrice.priceName)),
+          stripeProductId: stripeProductIdSchema.parse(stripeProduct.id),
+          stripePriceId: stripePriceIdSchema.parse(priceSync.stripePrice.id),
+          syncAction: priceSync.syncAction,
+        })
+      }
+    }
+  } catch (thrownValue) {
+    return thrownPaymentsErrorToFailure(thrownValue, options.paymentsClient)
+  }
+
+  return {
+    kind: 'payments-catalog-synced',
+    syncedPrices,
+    // A validated catalog always has at least one product with at least one price, so an object came
+    // back from Stripe and this is never the fallback in practice.
+    stripeLivemode: stripeLivemode ?? false,
+  }
+}

package/src/thrown-payments-error-details.ts

@@ -0,0 +1,134 @@
+import { paymentsDatabaseUnavailableCauseCodes } from './payments-contract.ts'
+
+/**
+ * Reads a thrown Stripe or Drizzle value without asserting anything about its shape. Every access
+ * path here is measured at stripe@22.6.1 and drizzle-orm@0.45.2, and the obvious spelling beside each
+ * one returns a plausible wrong answer rather than throwing, which is why they are read in one place
+ * instead of at each call site:
+ *
+ * - `error.type` is the SDK CLASS NAME, because StripeError's constructor sets
+ *   `this.type = type || this.constructor.name`. Stripe's own type string — `invalid_request_error`
+ *   and friends — is at `error.rawType`, so switching on `error.type` expecting the API's vocabulary
+ *   matches nothing and routes every case to the catch-all, silently;
+ * - the HTTP status is at `error.statusCode`, the API error code at `error.code`, and the offending
+ *   parameter name at `error.param`, all straight off the raw error body;
+ * - a database failure carries no code on the thrown value at all; it sits one `.cause` hop down, and
+ *   one call can throw from two unrelated families — an AggregateError and pg's DatabaseError.
+ */
+
+// The SDK class names, read off stripe@22.6.1's esm/Error.js where each subclass passes its own name
+// to the base constructor: StripeConnectionError at :164 and StripeSignatureVerificationError at :176.
+/** SDK class name of the error a request-level network failure or a timeout produces. */
+export const stripeConnectionErrorTypeName = 'StripeConnectionError'
+
+/** SDK class name of the error webhook signature verification throws; it also carries the raw body on `.payload`, which is never read. */
+export const stripeSignatureVerificationErrorTypeName = 'StripeSignatureVerificationError'
+
+// Deep enough for a DrizzleQueryError wrapping a pg DatabaseError, or an AggregateError listing the
+// attempts it made, and bounded so a self-referencing cause cannot spin.
+const maximumErrorCauseHops = 6
+
+/** What a thrown payments call yielded, with each value read from the spelling that actually carries it. */
+export type ThrownPaymentsErrorDetails = {
+  stripeErrorTypeName: string | undefined
+  stripeErrorCode: string | undefined
+  stripeErrorStatus: number | undefined
+  stripeErrorParam: string | undefined
+  databaseFailureDetail: string | undefined
+  paymentsFailureDetail: string
+}
+
+function readErrorMessage(error: unknown): string | undefined {
+  if (typeof error === 'object' && error !== null && 'message' in error) {
+    return typeof error.message === 'string' && error.message.length > 0 ? error.message : undefined
+  }
+  return undefined
+}
+
+function readErrorName(error: unknown): string | undefined {
+  if (typeof error === 'object' && error !== null && 'name' in error) {
+    return typeof error.name === 'string' && error.name.length > 0 ? error.name : undefined
+  }
+  return undefined
+}
+
+/** True when a thrown value is an object carrying the named property, which is all reading it by name needs. */
+function hasErrorProperty(error: unknown, propertyName: string): error is Record<string, unknown> {
+  return typeof error === 'object' && error !== null && propertyName in error
+}
+
+function readStringProperty(error: unknown, propertyName: string): string | undefined {
+  if (!hasErrorProperty(error, propertyName)) {
+    return undefined
+  }
+  const value = error[propertyName]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function readIntegerProperty(error: unknown, propertyName: string): number | undefined {
+  if (!hasErrorProperty(error, propertyName)) {
+    return undefined
+  }
+  const value = error[propertyName]
+  return typeof value === 'number' && Number.isInteger(value) ? value : undefined
+}
+
+/** Every value reachable from a thrown error by `.cause` hops and by an AggregateError's own list. */
+function relatedThrownValues(thrownValue: unknown): unknown[] {
+  const related: unknown[] = []
+  const pending: unknown[] = [thrownValue]
+  while (pending.length > 0 && related.length < maximumErrorCauseHops) {
+    const current = pending.shift()
+    if (typeof current !== 'object' || current === null) {
+      continue
+    }
+    related.push(current)
+    if ('cause' in current && current.cause !== undefined) {
+      pending.push(current.cause)
+    }
+    // A dead port arrives as an AggregateError whose own `code` is ECONNREFUSED, while an absent
+    // table arrives as a pg DatabaseError; one handler has to read both families.
+    if ('errors' in current && Array.isArray(current.errors)) {
+      for (const aggregated of current.errors) {
+        pending.push(aggregated)
+      }
+    }
+  }
+  return related
+}
+
+function readDatabaseFailureDetail(thrownValue: unknown): string | undefined {
+  for (const related of relatedThrownValues(thrownValue)) {
+    const code = readStringProperty(related, 'code')
+    if (
+      code !== undefined &&
+      (paymentsDatabaseUnavailableCauseCodes as readonly string[]).includes(code)
+    ) {
+      // Built from the cause and never from the DrizzleQueryError that wraps it: the wrapper's
+      // message repeats the failing statement AND its bound parameters, which on these tables would
+      // put a customer's address and Stripe ids into a failure a caller is likely to log.
+      return `Postgres reported ${code}: ${readErrorMessage(related) ?? readErrorName(related) ?? 'no message'}`
+    }
+  }
+  return undefined
+}
+
+/** Reads a thrown value once, so no call site has to remember which of the plausible spellings is real. */
+export function readThrownPaymentsErrorDetails(thrownValue: unknown): ThrownPaymentsErrorDetails {
+  const stripeErrorStatus = readIntegerProperty(thrownValue, 'statusCode')
+  const statusSuffix =
+    stripeErrorStatus === undefined ? '' : ` with status ${String(stripeErrorStatus)}`
+
+  return {
+    stripeErrorTypeName: readStringProperty(thrownValue, 'type'),
+    stripeErrorCode: readStringProperty(thrownValue, 'code'),
+    stripeErrorStatus,
+    stripeErrorParam: readStringProperty(thrownValue, 'param'),
+    databaseFailureDetail: readDatabaseFailureDetail(thrownValue),
+    // Never empty: a failure variant carrying an empty detail would fail its own schema, and some
+    // thrown values carry only a name.
+    paymentsFailureDetail:
+      readErrorMessage(thrownValue) ??
+      `${readErrorName(thrownValue) ?? 'an error with no message'}${statusSuffix}`,
+  }
+}

package/src/thrown-payments-error-failure.ts

@@ -0,0 +1,74 @@
+import { redactPaymentsClientSecrets } from './payments-client-secrets.ts'
+import {
+  paymentsDatabaseUnavailableFailure,
+  paymentsRequestFailedFailure,
+  paymentsStripeUnauthorizedFailure,
+  paymentsStripeUnreachableFailure,
+} from './payments-failure-results.ts'
+import {
+  stripeForbiddenHttpStatus,
+  stripeUnauthorizedHttpStatus,
+  type PaymentsClient,
+  type PaymentsFailure,
+} from './payments-contract.ts'
+import {
+  readThrownPaymentsErrorDetails,
+  stripeConnectionErrorTypeName,
+} from './thrown-payments-error-details.ts'
+
+/**
+ * Turns any thrown value into the failure CONTRACT.md maps it to, so no public function of this
+ * package ever throws. The mapping is fixed there rather than chosen here: a database cause code from
+ * the four-code allowlist wins first, then Stripe's 401 or 403, then a connection failure, and
+ * everything else lands in the catch-all carrying whatever Stripe supplied.
+ *
+ * Every quoted detail passes through the client's secret redaction first, because the words are the
+ * SDK's and the rule that neither secret leaves this package has no exceptions.
+ */
+export function thrownPaymentsErrorToFailure(
+  thrownValue: unknown,
+  paymentsClient: PaymentsClient | undefined,
+): PaymentsFailure {
+  const details = readThrownPaymentsErrorDetails(thrownValue)
+
+  if (details.databaseFailureDetail !== undefined) {
+    return paymentsDatabaseUnavailableFailure(
+      redactPaymentsClientSecrets(details.databaseFailureDetail, paymentsClient),
+    )
+  }
+
+  const paymentsFailureDetail = redactPaymentsClientSecrets(
+    details.paymentsFailureDetail,
+    paymentsClient,
+  )
+  // Redaction can only shorten text, and a variant carrying an empty detail would fail its own
+  // schema, so a detail that was nothing but a secret still has to say something.
+  const safeDetail =
+    paymentsFailureDetail.length > 0 ? paymentsFailureDetail : 'no detail available'
+
+  if (
+    details.stripeErrorStatus === stripeUnauthorizedHttpStatus ||
+    details.stripeErrorStatus === stripeForbiddenHttpStatus
+  ) {
+    return paymentsStripeUnauthorizedFailure(details.stripeErrorStatus, safeDetail)
+  }
+
+  if (details.stripeErrorTypeName === stripeConnectionErrorTypeName) {
+    return paymentsStripeUnreachableFailure(safeDetail)
+  }
+
+  return paymentsRequestFailedFailure({
+    paymentsFailureDetail: safeDetail,
+    ...(details.stripeErrorCode === undefined
+      ? {}
+      : { stripeErrorCode: redactPaymentsClientSecrets(details.stripeErrorCode, paymentsClient) }),
+    ...(details.stripeErrorStatus === undefined
+      ? {}
+      : { stripeErrorStatus: details.stripeErrorStatus }),
+    ...(details.stripeErrorParam === undefined
+      ? {}
+      : {
+          stripeErrorParam: redactPaymentsClientSecrets(details.stripeErrorParam, paymentsClient),
+        }),
+  })
+}

package/src/verify-payments-tables-exist.test.ts

@@ -0,0 +1,84 @@
+import { afterAll, describe, expect, it } from 'vitest'
+import { expectResultKind, sortedGateNames } from '../test-fixtures/payments-gate-expectations.ts'
+import { defineGateFileContext } from '../test-fixtures/payments-gate-file-context.ts'
+import {
+  createGatePaymentsDatabase,
+  createGatePaymentsDatabaseWithoutTables,
+  gateDatabaseExists,
+  type GatePaymentsDatabase,
+} from '../test-fixtures/payments-gate-postgres-database.ts'
+import {
+  loadHearthkitPaymentsEntry,
+  type HearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import {
+  hearthkitPaymentsTableNames,
+  verifyPaymentsTablesExistResultSchema,
+} from './payments-contract.ts'
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  migratedDatabase: GatePaymentsDatabase
+  unmigratedDatabase: GatePaymentsDatabase
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  // Not createVerifiedGatePaymentsDatabase: this file is where that check itself is the subject, so
+  // it builds the tables and then asks the question rather than assuming the answer during setup.
+  const migratedDatabase = await createGatePaymentsDatabase(
+    'tables',
+    paymentsEntry.hearthkitPaymentsDrizzleSchema,
+  )
+  const unmigratedDatabase = await createGatePaymentsDatabaseWithoutTables(
+    'notables',
+    paymentsEntry.hearthkitPaymentsDrizzleSchema,
+  )
+  return { paymentsEntry, migratedDatabase, unmigratedDatabase }
+})
+
+afterAll(async () => {
+  await gateFile.releaseIfCreated(async ({ migratedDatabase, unmigratedDatabase }) => {
+    await migratedDatabase.removeGatePaymentsDatabase()
+    await unmigratedDatabase.removeGatePaymentsDatabase()
+    // Both scratch databases are gone when this file is done, so a repeated run starts from nothing.
+    for (const gateDatabase of [migratedDatabase, unmigratedDatabase]) {
+      if (await gateDatabaseExists(String(gateDatabase.projectDatabaseName))) {
+        throw new Error(
+          `gate left the scratch database ${String(gateDatabase.projectDatabaseName)} behind`,
+        )
+      }
+    }
+  })
+})
+
+describe('verifyPaymentsTablesExist', () => {
+  it('reports all three tables present in a database built from the shipped Drizzle schema', async () => {
+    const { paymentsEntry, migratedDatabase } = await gateFile.read()
+
+    // It takes the Drizzle client rather than the payments client on purpose, so observability's
+    // /health can call it with no Stripe key at all. No payments client is built in this gate.
+    const result = await paymentsEntry.verifyPaymentsTablesExist({
+      drizzleClient: migratedDatabase.drizzleClient,
+    })
+    verifyPaymentsTablesExistResultSchema.parse(result)
+    const present = expectResultKind(result, 'payments-tables-present')
+
+    expect(sortedGateNames(present.presentTableNames)).toEqual(
+      sortedGateNames(hearthkitPaymentsTableNames),
+    )
+  })
+
+  it('reports payments-tables-missing, which is a successful check and not a failure, when migrations never ran', async () => {
+    const { paymentsEntry, unmigratedDatabase } = await gateFile.read()
+
+    // The function's whole job is to report presence, so a negative answer is a result. A database
+    // that is reachable and empty is the ordinary first-run state of every project.
+    const result = await paymentsEntry.verifyPaymentsTablesExist({
+      drizzleClient: unmigratedDatabase.drizzleClient,
+    })
+    verifyPaymentsTablesExistResultSchema.parse(result)
+    const missing = expectResultKind(result, 'payments-tables-missing')
+    expect(sortedGateNames(missing.missingTableNames)).toEqual(
+      sortedGateNames(hearthkitPaymentsTableNames),
+    )
+  })
+})

package/src/verify-payments-tables-exist.ts

@@ -0,0 +1,67 @@
+import { sql } from 'drizzle-orm'
+import { z } from 'zod'
+import {
+  hearthkitPaymentsTableNames,
+  paymentsDrizzleClientSchema,
+  type HearthkitPaymentsTableName,
+  type VerifyPaymentsTablesExistOptions,
+  type VerifyPaymentsTablesExistResult,
+} from './payments-contract.ts'
+import { paymentsInputInvalidFailure } from './payments-failure-results.ts'
+import { thrownPaymentsErrorToFailure } from './thrown-payments-error-failure.ts'
+
+// node-postgres answers with a QueryResult carrying `rows`; a driver that answers the rows directly
+// is read the same way, so neither shape has to be assumed.
+const tableNameRowsSchema = z.array(z.object({ table_name: z.string() }))
+const queryResultSchema = z.union([
+  tableNameRowsSchema,
+  z.object({ rows: tableNameRowsSchema }).transform((queryResult) => queryResult.rows),
+])
+
+/**
+ * One query against information_schema, so it is safe to call from a health check. It takes the
+ * Drizzle client rather than the payments client precisely so observability's /health can call it
+ * with no Stripe key at all.
+ *
+ * payments-tables-missing is a result rather than a failure: the function's whole job is to report
+ * presence, and a reachable database with no payments tables in it is the ordinary first-run state of
+ * every project. A database that cannot be reached is a different answer, and that one is a failure.
+ *
+ * Names are read back and compared here rather than filtered in SQL, because information_schema types
+ * its identifiers as a domain and a bound array comparison against one needs a cast that adds
+ * nothing: the three names are known and the result set is small either way.
+ */
+export async function verifyPaymentsTablesExist(
+  options: VerifyPaymentsTablesExistOptions,
+): Promise<VerifyPaymentsTablesExistResult> {
+  if (!paymentsDrizzleClientSchema.safeParse(options.drizzleClient).success) {
+    return paymentsInputInvalidFailure('drizzle-client')
+  }
+
+  let queryResult: unknown
+  try {
+    queryResult = await options.drizzleClient.execute(
+      sql`select table_name from information_schema.tables where table_schema = 'public'`,
+    )
+  } catch (thrownValue) {
+    return thrownPaymentsErrorToFailure(thrownValue, undefined)
+  }
+
+  const parsedRows = queryResultSchema.safeParse(queryResult)
+  const tableNamesInDatabase = new Set((parsedRows.data ?? []).map((row) => row.table_name))
+
+  const presentTableNames: HearthkitPaymentsTableName[] = []
+  const missingTableNames: HearthkitPaymentsTableName[] = []
+  for (const paymentsTableName of hearthkitPaymentsTableNames) {
+    if (tableNamesInDatabase.has(paymentsTableName)) {
+      presentTableNames.push(paymentsTableName)
+    } else {
+      missingTableNames.push(paymentsTableName)
+    }
+  }
+
+  if (missingTableNames.length > 0) {
+    return { kind: 'payments-tables-missing', missingTableNames }
+  }
+  return { kind: 'payments-tables-present', presentTableNames }
+}