@hearthkit/payments 0.1.0

package/src/payments-customer-record.ts

@@ -0,0 +1,89 @@
+import { eq } from 'drizzle-orm'
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres'
+import { paymentsCustomerTable } from './hearthkit-payments-drizzle-schema.ts'
+import { generatePaymentsRowId } from './payments-row-identifier.ts'
+import type { BillingScope } from './payments-contract.ts'
+
+/**
+ * Every read and write of payments_customer, in one place because the column billingContactEmail has
+ * two writers with different rules and keeping them apart is the whole point.
+ *
+ * createCheckoutSession sets the address from the value the app supplied, on insert and on update.
+ * The webhook path sets it only when it inserts a row: both Stripe fields it could read are
+ * influenced by the buyer on a page the app does not control, so letting a delivery overwrite the row
+ * would let a buyer silently redirect where receipts and dunning go.
+ */
+
+/** The values either writer supplies for one customer row; the row id and timestamps are decided here. */
+export type PaymentsCustomerRowValues = {
+  billingReferenceId: string
+  billingScope: BillingScope
+  stripeCustomerId: string
+  billingContactEmail: string
+  writtenAt: Date
+}
+
+/** One customer row as Postgres holds it, keyed by the Drizzle property names a caller reads. */
+export type PaymentsCustomerRow = typeof paymentsCustomerTable.$inferSelect
+
+/** The Stripe customer already on file for a reference, or nothing; an empty result is what makes customer-not-found deterministic offline. */
+export async function readPaymentsCustomerRow(
+  drizzleClient: NodePgDatabase<Record<string, unknown>>,
+  billingReferenceId: string,
+): Promise<PaymentsCustomerRow | undefined> {
+  const rows = await drizzleClient
+    .select()
+    .from(paymentsCustomerTable)
+    .where(eq(paymentsCustomerTable.billingReferenceId, billingReferenceId))
+    .limit(1)
+  return rows[0]
+}
+
+function customerInsertValues(values: PaymentsCustomerRowValues) {
+  return {
+    id: generatePaymentsRowId('paycus'),
+    billingReferenceId: values.billingReferenceId,
+    billingScope: values.billingScope,
+    stripeCustomerId: values.stripeCustomerId,
+    billingContactEmail: values.billingContactEmail,
+    createdAt: values.writtenAt,
+    updatedAt: values.writtenAt,
+  }
+}
+
+/** Upsert from a checkout call, which may set the receipt address on an existing row because the app supplied it. */
+export async function upsertPaymentsCustomerFromCheckout(
+  drizzleClient: NodePgDatabase<Record<string, unknown>>,
+  values: PaymentsCustomerRowValues,
+): Promise<void> {
+  await drizzleClient
+    .insert(paymentsCustomerTable)
+    .values(customerInsertValues(values))
+    .onConflictDoUpdate({
+      target: paymentsCustomerTable.billingReferenceId,
+      set: {
+        stripeCustomerId: values.stripeCustomerId,
+        billingContactEmail: values.billingContactEmail,
+        updatedAt: values.writtenAt,
+      },
+    })
+}
+
+// billingContactEmail is absent from the set clause on purpose, and that absence is the rule: on an
+// existing row the address stays exactly as createCheckoutSession wrote it, from what the app said.
+/** Upsert from a webhook delivery, which may seed the receipt address on a new row but never change one. */
+export async function upsertPaymentsCustomerFromWebhook(
+  drizzleClient: NodePgDatabase<Record<string, unknown>>,
+  values: PaymentsCustomerRowValues,
+): Promise<void> {
+  await drizzleClient
+    .insert(paymentsCustomerTable)
+    .values(customerInsertValues(values))
+    .onConflictDoUpdate({
+      target: paymentsCustomerTable.billingReferenceId,
+      set: {
+        stripeCustomerId: values.stripeCustomerId,
+        updatedAt: values.writtenAt,
+      },
+    })
+}

package/src/payments-database-unavailable.test.ts

@@ -0,0 +1,152 @@
+import type { PostgresConnectionString } from '@hearthkit/db'
+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 {
+  absentGateDatabaseUrl,
+  createGateDrizzleClientForUrl,
+  createGatePaymentsDatabaseWithoutTables,
+  unreachableGateDatabaseUrl,
+  wrongPasswordGateDatabaseUrl,
+  type GatePaymentsDatabase,
+} from '../test-fixtures/payments-gate-postgres-database.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 type { PaymentsClient } from './payments-contract.ts'
+
+/**
+ * The four Postgres codes CONTRACT.md allowlists, reused verbatim from @hearthkit/auth, each produced
+ * the cheapest way it can be: two need only a changed connection string, one needs a closed port, one
+ * needs a real database with no tables. Every producer arrives as a DrizzleQueryError carrying no
+ * code of its own, with the real code exactly one .cause hop down and arriving from two unrelated
+ * error families — an AggregateError for the refused connection and pg's DatabaseError for the rest —
+ * so classifying any of these as payments-database-unavailable at all is what proves the
+ * implementation looked there.
+ */
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  unmigratedDatabase: GatePaymentsDatabase
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  const unmigratedDatabase = await createGatePaymentsDatabaseWithoutTables(
+    'dbfail',
+    paymentsEntry.hearthkitPaymentsDrizzleSchema,
+  )
+  return { paymentsEntry, unmigratedDatabase }
+})
+
+afterAll(async () => {
+  await gateFile.releaseIfCreated(({ unmigratedDatabase }) =>
+    unmigratedDatabase.removeGatePaymentsDatabase(),
+  )
+})
+
+/** A lazy client over a connection string that is expected to fail, plus the close the pool needs. */
+async function withDrizzleClientForUrl<TResult>(
+  databaseUrl: PostgresConnectionString,
+  run: (drizzleClient: NodePgDatabase<Record<string, unknown>>) => Promise<TResult>,
+): Promise<TResult> {
+  const { paymentsEntry } = await gateFile.read()
+  const { drizzleClient, closeDatabaseClient } = createGateDrizzleClientForUrl(
+    databaseUrl,
+    paymentsEntry.hearthkitPaymentsDrizzleSchema,
+  )
+  try {
+    return await run(drizzleClient)
+  } finally {
+    await closeDatabaseClient()
+  }
+}
+
+/** A payments client over a connection string that is expected to fail; building it opens no connection. */
+async function withPaymentsClientForUrl<TResult>(
+  databaseUrl: PostgresConnectionString,
+  run: (paymentsClient: PaymentsClient) => Promise<TResult>,
+): Promise<TResult> {
+  const { paymentsEntry } = await gateFile.read()
+  return withDrizzleClientForUrl(databaseUrl, (drizzleClient) =>
+    // The failure appears on the first call that queries, which is where the gate wants it.
+    run(
+      createGatePaymentsClient({
+        paymentsEntry,
+        drizzleClient,
+        paymentsCatalog: gatePaymentsCatalog(uniqueGatePaymentsCatalogNames('dbfail')),
+      }),
+    ),
+  )
+}
+
+describe('payments-database-unavailable', () => {
+  it('reports it when the connection string names a database that does not exist, and when its password is wrong', async () => {
+    const { paymentsEntry } = await gateFile.read()
+
+    // Postgres 3D000, from the table check, which needs no payments client and no Stripe key at all.
+    // Nothing about the environment is changed but the database name in the URL.
+    const absentDatabase = await withDrizzleClientForUrl(absentGateDatabaseUrl, (drizzleClient) =>
+      paymentsEntry.verifyPaymentsTablesExist({ drizzleClient }),
+    )
+    expect(
+      expectPaymentsFailure(absentDatabase, 'payments-database-unavailable').databaseFailureDetail
+        .length,
+    ).toBeGreaterThan(0)
+
+    // Postgres 28P01, on the same server and the same database, one wrong password apart. Read from
+    // a different function on purpose: every database call maps this the same way.
+    const wrongPassword = await withPaymentsClientForUrl(
+      wrongPasswordGateDatabaseUrl,
+      (paymentsClient) =>
+        paymentsEntry.listPaymentsPurchases({
+          paymentsClient,
+          billingReferenceId: uniqueGateBillingReferenceId('dbfail-password'),
+        }),
+    )
+    expectPaymentsFailure(wrongPassword, 'payments-database-unavailable')
+  })
+
+  it('reports it when Postgres refuses the connection outright', async () => {
+    const { paymentsEntry } = await gateFile.read()
+
+    // ECONNREFUSED, which arrives on an AggregateError rather than the pg DatabaseError the other
+    // three produce, so one handler has to read two unrelated error families.
+    const result = await withPaymentsClientForUrl(unreachableGateDatabaseUrl, (paymentsClient) =>
+      paymentsEntry.readPaymentsSubscription({
+        paymentsClient,
+        billingReferenceId: uniqueGateBillingReferenceId('dbfail-refused'),
+      }),
+    )
+    expect(
+      expectPaymentsFailure(result, 'payments-database-unavailable').databaseFailureDetail.length,
+    ).toBeGreaterThan(0)
+  })
+
+  it('reports it when the database is reachable but the payments tables were never created, without quoting the query parameters back', async () => {
+    const { paymentsEntry, unmigratedDatabase } = await gateFile.read()
+    const billingReferenceId = uniqueGateBillingReferenceId('dbfail-notables')
+
+    // Postgres 42P01, the first-run state of every project before hearthkit db migrate. The same
+    // database answers verifyPaymentsTablesExist with payments-tables-missing, which is a result and
+    // not a failure: asking whether the tables are there is not the same call as trying to use them.
+    const result = await withPaymentsClientForUrl(
+      unmigratedDatabase.connectionString,
+      (paymentsClient) =>
+        paymentsEntry.readPaymentsSubscription({ paymentsClient, billingReferenceId }),
+    )
+    const failure = expectPaymentsFailure(result, 'payments-database-unavailable')
+    expect(failure.databaseFailureDetail.length).toBeGreaterThan(0)
+
+    // The detail is built from the .cause, never from the DrizzleQueryError wrapper: the wrapper's
+    // message repeats the failing SQL AND its bound parameters, which on this package's tables would
+    // put a customer's email address and Stripe ids into a failure a caller is likely to log.
+    expect(JSON.stringify(failure)).not.toContain(billingReferenceId)
+  })
+})

package/src/payments-env-schema-fragment.test.ts

@@ -0,0 +1,197 @@
+import { loadHearthkitConfig } from '@hearthkit/config'
+import { describe, expect, it } from 'vitest'
+import { expectResultKind } from '../test-fixtures/payments-gate-expectations.ts'
+import {
+  readPaymentsPackageManifest,
+  runPaymentsContractUnderBareNode,
+} from '../test-fixtures/payments-package-entry-points.ts'
+import {
+  importHearthkitPaymentsNamespace,
+  loadHearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import * as paymentsContract from './payments-contract.ts'
+
+const everyPaymentsVariableName = ['STRIPE_SECRET_KEY', 'STRIPE_WEBHOOK_SECRET'] as const
+
+const completePaymentsEnv = {
+  STRIPE_SECRET_KEY: 'sk_test_51GateSecretKeyThatIsNotRealAndHasNoWhitespace',
+  STRIPE_WEBHOOK_SECRET: 'whsec_GateSigningSecretThatIsNotRealEither',
+}
+
+// CONTRACT.md's entry point rule is mechanical: src/index.ts re-exports every value
+// src/payments-contract.ts exports, with no exceptions. So the required list is read off the contract
+// module's own namespace rather than typed out here. A hand-written list would fall behind the day
+// someone forgot to extend it; a derived list cannot.
+//
+// A module namespace carries value exports only. Every `export type` in payments-contract.ts is
+// erased before this file runs, so the types CONTRACT.md also asks the entry point to re-export are
+// outside what this gate can see and are covered by typecheck instead.
+function contractValueExportNames(contractModule: Record<string, unknown>): string[] {
+  return Object.keys(contractModule).toSorted()
+}
+
+// Named in so many words by CONTRACT.md: the nine message prefixes, the env fragment, the failure
+// union, the table name list, the two subscription status lists and the eight per-function result
+// schemas. Spelled out as strings so renaming one in the contract fails this gate loudly, instead of
+// quietly shrinking the derived list above to a set an entry point already satisfies.
+const contractExportNamesTheContractNamesOutright = [
+  'paymentsInputInvalidErrorPrefix',
+  'paymentsCatalogInvalidErrorPrefix',
+  'paymentsPriceNotFoundErrorPrefix',
+  'paymentsCustomerNotFoundErrorPrefix',
+  'paymentsWebhookSignatureInvalidErrorPrefix',
+  'paymentsStripeUnauthorizedErrorPrefix',
+  'paymentsStripeUnreachableErrorPrefix',
+  'paymentsDatabaseUnavailableErrorPrefix',
+  'paymentsRequestFailedErrorPrefix',
+  'paymentsEnvSchemaFragment',
+  'paymentsFailureSchema',
+  'hearthkitPaymentsTableNames',
+  'paymentsKnownSubscriptionStatuses',
+  'paymentsActiveSubscriptionStatuses',
+  'createPaymentsClientResultSchema',
+  'syncPaymentsCatalogResultSchema',
+  'createCheckoutSessionResultSchema',
+  'createCustomerPortalSessionResultSchema',
+  'handleStripeWebhookResultSchema',
+  'readPaymentsSubscriptionResultSchema',
+  'listPaymentsPurchasesResultSchema',
+  'verifyPaymentsTablesExistResultSchema',
+] as const
+
+// Not exported by payments-contract.ts, so the derived list cannot cover them: the eight public
+// functions and the Drizzle table map.
+const entryPointOnlyExportNames = [
+  'createPaymentsClient',
+  'syncPaymentsCatalog',
+  'createCheckoutSession',
+  'createCustomerPortalSession',
+  'handleStripeWebhook',
+  'readPaymentsSubscription',
+  'listPaymentsPurchases',
+  'verifyPaymentsTablesExist',
+  'hearthkitPaymentsDrizzleSchema',
+] as const
+
+describe('paymentsEnvSchemaFragment', () => {
+  it('declares two required variables, names both at load when neither is set, treats an empty value as unset, and rejects one carrying whitespace', async () => {
+    const { paymentsEnvSchemaFragment } = await loadHearthkitPaymentsEntry()
+    expect(Object.keys(paymentsEnvSchemaFragment.shape).toSorted()).toEqual([
+      ...everyPaymentsVariableName,
+    ])
+
+    const nothingSet = expectResultKind(
+      loadHearthkitConfig({ fragments: [paymentsEnvSchemaFragment], env: {} }),
+      'config-validation-failed',
+    )
+    expect(nothingSet.message).toContain('STRIPE_SECRET_KEY')
+    expect(nothingSet.message).toContain('STRIPE_WEBHOOK_SECRET')
+    expect(nothingSet.issues).toHaveLength(2)
+
+    // An empty string is unset, per config's contract: a compose file carrying `STRIPE_SECRET_KEY=`
+    // is the accident that rule exists to catch, and both variables are required here.
+    const bothEmpty = expectResultKind(
+      loadHearthkitConfig({
+        fragments: [paymentsEnvSchemaFragment],
+        env: { STRIPE_SECRET_KEY: '', STRIPE_WEBHOOK_SECRET: '' },
+      }),
+      'config-validation-failed',
+    )
+    expect(bothEmpty.issues).toHaveLength(2)
+
+    // Whitespace is the mistake upstream itself names: stripe@22.6.1 tests `/\s/.test(secret)` and
+    // warns that whitespace "often indicates an extra newline or space is in the value". A copied
+    // secret arrives with a trailing newline, which is why the rule is /^\S+$/ and not a prefix.
+    const trailingNewline = expectResultKind(
+      loadHearthkitConfig({
+        fragments: [paymentsEnvSchemaFragment],
+        env: {
+          STRIPE_SECRET_KEY: `${completePaymentsEnv.STRIPE_SECRET_KEY}\n`,
+          STRIPE_WEBHOOK_SECRET: completePaymentsEnv.STRIPE_WEBHOOK_SECRET,
+        },
+      }),
+      'config-validation-failed',
+    )
+    expect(trailingNewline.message).toContain('STRIPE_SECRET_KEY')
+    expect(trailingNewline.issues).toHaveLength(1)
+
+    const innerSpace = expectResultKind(
+      loadHearthkitConfig({
+        fragments: [paymentsEnvSchemaFragment],
+        env: {
+          STRIPE_SECRET_KEY: completePaymentsEnv.STRIPE_SECRET_KEY,
+          STRIPE_WEBHOOK_SECRET: 'whsec_Gate Signing Secret',
+        },
+      }),
+      'config-validation-failed',
+    )
+    expect(innerSpace.message).toContain('STRIPE_WEBHOOK_SECRET')
+    expect(innerSpace.issues).toHaveLength(1)
+
+    const loaded = expectResultKind(
+      loadHearthkitConfig({ fragments: [paymentsEnvSchemaFragment], env: completePaymentsEnv }),
+      'config-loaded',
+    )
+    expect(String(loaded.config.STRIPE_SECRET_KEY)).toBe(completePaymentsEnv.STRIPE_SECRET_KEY)
+    expect(String(loaded.config.STRIPE_WEBHOOK_SECRET)).toBe(
+      completePaymentsEnv.STRIPE_WEBHOOK_SECRET,
+    )
+  })
+})
+
+describe('@hearthkit/payments entry point', () => {
+  it('re-exports by name every value payments-contract.ts exports, plus the eight functions and the Drizzle schema', async () => {
+    const namespace = await importHearthkitPaymentsNamespace()
+    const contractModule = paymentsContract as unknown as Record<string, unknown>
+    const requiredExportNames = contractValueExportNames(contractModule)
+
+    const renamedInTheContract = contractExportNamesTheContractNamesOutright.filter(
+      (exportName) => !requiredExportNames.includes(exportName),
+    )
+    expect(
+      renamedInTheContract,
+      'payments-contract.ts must still export the constants and schemas CONTRACT.md names outright',
+    ).toEqual([])
+
+    // Both lists are compared whole rather than one name at a time, so a failure names every export
+    // that is wrong instead of stopping at the first and hiding the rest behind a rerun.
+    const missingFromTheEntryPoint = requiredExportNames.filter(
+      (exportName) => namespace[exportName] === undefined,
+    )
+    expect(
+      missingFromTheEntryPoint,
+      'src/index.ts must re-export these by name from payments-contract.ts',
+    ).toEqual([])
+
+    const rebuiltInsteadOfReExported = requiredExportNames.filter(
+      (exportName) => namespace[exportName] !== contractModule[exportName],
+    )
+    expect(
+      rebuiltInsteadOfReExported,
+      'these must be the identical value payments-contract.ts exports, not a second copy of it',
+    ).toEqual([])
+
+    const missingImplementationExports = entryPointOnlyExportNames.filter(
+      (exportName) => namespace[exportName] === undefined,
+    )
+    expect(
+      missingImplementationExports,
+      'src/index.ts must re-export the public functions and the Drizzle schema by name',
+    ).toEqual([])
+  })
+
+  it('publishes ./payments-contract as a second subpath that a bare node process can load', async () => {
+    const manifest = await readPaymentsPackageManifest()
+    expect(manifest.packageName).toBe('@hearthkit/payments')
+    expect(Object.keys(manifest.exportsMap).toSorted()).toEqual(['.', './payments-contract'])
+    expect(JSON.stringify(manifest.exportsMap['./payments-contract'])).toContain(
+      './src/payments-contract.ts',
+    )
+
+    // The reason the subpath exists: the `.` entry imports the Stripe SDK, drizzle-orm/pg-core and
+    // the table definitions, while this file imports zod at runtime and nothing else — its stripe,
+    // drizzle-orm/node-postgres and @hearthkit/auth/auth-contract imports are type-only and erased.
+    const bareNodeRun = await runPaymentsContractUnderBareNode()
+    expect(bareNodeRun.exitCode, bareNodeRun.standardError).toBe(0)
+  })
+})

package/src/payments-failure-results.ts

@@ -0,0 +1,185 @@
+import {
+  maximumPaymentsPriceNameLength,
+  paymentsCatalogInvalidErrorPrefix,
+  paymentsCustomerNotFoundErrorPrefix,
+  paymentsDatabaseUnavailableErrorPrefix,
+  paymentsInputInvalidErrorPrefix,
+  paymentsPriceNotFoundErrorPrefix,
+  paymentsRequestFailedErrorPrefix,
+  paymentsStripeUnauthorizedErrorPrefix,
+  paymentsStripeUnreachableErrorPrefix,
+  paymentsWebhookSignatureInvalidErrorPrefix,
+  type BillingReferenceId,
+  type PaymentsCatalogIssue,
+  type PaymentsFailure,
+  type PaymentsInvalidFieldName,
+  type PriceLookupFailure,
+  type WebhookSignatureFailureReason,
+} from './payments-contract.ts'
+
+/**
+ * The one place a failure value is built, so every message keeps its unique literal prefix and no
+ * variant is ever assembled twice with two different wordings.
+ */
+
+/** One variant of the failure union, selected by its kind, so a producer states which failure it returns. */
+export type PaymentsFailureOfKind<TKind extends PaymentsFailure['kind']> = Extract<
+  PaymentsFailure,
+  { kind: TKind }
+>
+
+// The rule that was broken, never the value that broke it. A billing reference, an address and a
+// redirect URL are all things a caller may log, and a reason that quoted its input would put one of
+// them back in front of whoever reads the failure.
+/** Why each caller-supplied field was rejected, stated as the rule and never as the rejected value. */
+export const paymentsInvalidFieldReasons: Record<PaymentsInvalidFieldName, string> = {
+  'billing-reference-id': 'must be a non-empty identifier that Better Auth generated',
+  'billing-contact-email': 'must be a single valid mailbox',
+  'price-name': `must be lowercase kebab-case of at most ${String(maximumPaymentsPriceNameLength)} characters`,
+  quantity: 'must be a positive whole number of units',
+  'success-url': 'must be an absolute http or https URL, because Stripe rejects a relative path',
+  'cancel-url': 'must be an absolute http or https URL, because Stripe rejects a relative path',
+  'return-url': 'must be an absolute http or https URL, because Stripe rejects a relative path',
+  'raw-request-body':
+    'must be the exact request text Stripe sent, so read request.text() and never request.json()',
+  'request-headers': 'must be a Headers-like object carrying a get method',
+  'stripe-api-base-url': 'must be an absolute http or https URL when it is supplied at all',
+  'payments-env':
+    'must carry STRIPE_SECRET_KEY and STRIPE_WEBHOOK_SECRET as non-empty values with no whitespace',
+  'drizzle-client': 'must be the Drizzle client @hearthkit/db built',
+}
+
+/** Failure for a caller-supplied value rejected before any database or Stripe call is made. */
+export function paymentsInputInvalidFailure(
+  invalidFieldName: PaymentsInvalidFieldName,
+): PaymentsFailureOfKind<'payments-input-invalid'> {
+  const invalidFieldReason = paymentsInvalidFieldReasons[invalidFieldName]
+  return {
+    kind: 'payments-input-invalid',
+    invalidFieldName,
+    invalidFieldReason,
+    message: `${paymentsInputInvalidErrorPrefix} ${invalidFieldName} ${invalidFieldReason}`,
+  }
+}
+
+/** Failure naming every problem in the app's catalog in one list, because fixing one error per boot is miserable. */
+export function paymentsCatalogInvalidFailure(
+  catalogIssues: readonly PaymentsCatalogIssue[],
+): PaymentsFailureOfKind<'payments-catalog-invalid'> {
+  const perIssue = catalogIssues.map(
+    (issue) =>
+      `${issue.catalogIssueKind} at ${issue.catalogEntryName}: ${issue.catalogIssueReason}`,
+  )
+  return {
+    kind: 'payments-catalog-invalid',
+    catalogIssues: catalogIssues.map((issue) => ({ ...issue })),
+    message: `${paymentsCatalogInvalidErrorPrefix} ${perIssue.join('; ')}`,
+  }
+}
+
+// One variant with a discriminator rather than two kinds: the caller does the same thing with both,
+// which is to tell the buyer this plan is unavailable, and only the operator's next step differs.
+/** Failure when the named price is in neither the catalog nor Stripe; priceLookupFailure says which. */
+export function paymentsPriceNotFoundFailure(
+  priceName: string,
+  priceLookupFailure: PriceLookupFailure,
+): PaymentsFailureOfKind<'payments-price-not-found'> {
+  const nextStep =
+    priceLookupFailure === 'absent-from-catalog'
+      ? 'no price in payments-catalog.ts carries that name'
+      : 'the catalog carries that name but no active Stripe price does, so run the catalog sync against this account'
+  return {
+    kind: 'payments-price-not-found',
+    priceName,
+    priceLookupFailure,
+    message: `${paymentsPriceNotFoundErrorPrefix} ${priceName} is ${priceLookupFailure}, ${nextStep}`,
+  }
+}
+
+/** Failure when no customer row exists for the reference; only the portal call produces it, because checkout creates the row. */
+export function paymentsCustomerNotFoundFailure(
+  billingReferenceId: BillingReferenceId,
+): PaymentsFailureOfKind<'payments-customer-not-found'> {
+  return {
+    kind: 'payments-customer-not-found',
+    billingReferenceId,
+    message: `${paymentsCustomerNotFoundErrorPrefix} that billing reference has never completed a checkout, so there is no Stripe customer to open a portal for`,
+  }
+}
+
+// stripeFailureDetail is the SDK error's message and nothing else. StripeSignatureVerificationError
+// also carries `.payload`, which is the raw webhook body and therefore whatever customer data the
+// event held, so nothing here ever reads it.
+/** Failure when a webhook request carried no signature header or one that does not verify. */
+export function paymentsWebhookSignatureInvalidFailure(
+  signatureFailureReason: WebhookSignatureFailureReason,
+  stripeFailureDetail?: string,
+): PaymentsFailureOfKind<'payments-webhook-signature-invalid'> {
+  return {
+    kind: 'payments-webhook-signature-invalid',
+    signatureFailureReason,
+    ...(stripeFailureDetail === undefined || stripeFailureDetail.length === 0
+      ? {}
+      : { stripeFailureDetail }),
+    message: `${paymentsWebhookSignatureInvalidErrorPrefix} ${signatureFailureReason}, so this request did not come from Stripe`,
+  }
+}
+
+/** Failure when Stripe refused the API key with 401 or its permissions with 403; the status says which. */
+export function paymentsStripeUnauthorizedFailure(
+  stripeErrorStatus: number,
+  stripeFailureDetail: string,
+): PaymentsFailureOfKind<'payments-stripe-unauthorized'> {
+  return {
+    kind: 'payments-stripe-unauthorized',
+    stripeErrorStatus,
+    stripeFailureDetail,
+    message: `${paymentsStripeUnauthorizedErrorPrefix} Stripe answered ${String(stripeErrorStatus)}: ${stripeFailureDetail}`,
+  }
+}
+
+/** Failure when the Stripe API could not be reached or the request timed out. */
+export function paymentsStripeUnreachableFailure(
+  stripeFailureDetail: string,
+): PaymentsFailureOfKind<'payments-stripe-unreachable'> {
+  return {
+    kind: 'payments-stripe-unreachable',
+    stripeFailureDetail,
+    message: `${paymentsStripeUnreachableErrorPrefix} ${stripeFailureDetail}`,
+  }
+}
+
+/** Failure when Postgres refuses, the password or database is wrong, or the migrations never ran. */
+export function paymentsDatabaseUnavailableFailure(
+  databaseFailureDetail: string,
+): PaymentsFailureOfKind<'payments-database-unavailable'> {
+  return {
+    kind: 'payments-database-unavailable',
+    databaseFailureDetail,
+    message: `${paymentsDatabaseUnavailableErrorPrefix} ${databaseFailureDetail}`,
+  }
+}
+
+// No discriminator, deliberately: several producers land here — a null checkoutUrl, a null
+// session.currency, a null session.amount_total — and a caller cannot tell them apart. The detail is
+// for a human reading a log; anything that genuinely needs a branch gets its own variant instead.
+/** Catch-all failure carrying whatever Stripe supplied, so no call ever throws instead of returning. */
+export function paymentsRequestFailedFailure(details: {
+  paymentsFailureDetail: string
+  stripeErrorCode?: string
+  stripeErrorStatus?: number
+  stripeErrorParam?: string
+}): PaymentsFailureOfKind<'payments-request-failed'> {
+  return {
+    kind: 'payments-request-failed',
+    ...(details.stripeErrorCode === undefined ? {} : { stripeErrorCode: details.stripeErrorCode }),
+    ...(details.stripeErrorStatus === undefined
+      ? {}
+      : { stripeErrorStatus: details.stripeErrorStatus }),
+    ...(details.stripeErrorParam === undefined
+      ? {}
+      : { stripeErrorParam: details.stripeErrorParam }),
+    paymentsFailureDetail: details.paymentsFailureDetail,
+    message: `${paymentsRequestFailedErrorPrefix} ${details.paymentsFailureDetail}`,
+  }
+}