@hearthkit/payments 0.1.0

package/src/index.ts

@@ -0,0 +1,267 @@
+/** Public entry point of @hearthkit/payments: a named re-export of exactly the surface the contract lists, so no internal module is importable by consumers. */
+
+/** Validates the catalog and builds the Stripe client; synchronous, and contacts nothing. */
+export { createPaymentsClient } from './create-payments-client.ts'
+
+/** Pushes the held catalog to Stripe; idempotent, so a second run reports every price unchanged. */
+export { syncPaymentsCatalog } from './sync-payments-catalog.ts'
+
+/** Creates a hosted Checkout Session, putting a Stripe customer on file when the reference has none. */
+export { createCheckoutSession } from './create-checkout-session.ts'
+
+/** Opens Stripe's hosted billing portal; it creates nothing, so it is the only producer of customer-not-found. */
+export { createCustomerPortalSession } from './create-customer-portal-session.ts'
+
+/** Verifies a delivery with a local HMAC and records it; it needs Postgres but never the network. */
+export { handleStripeWebhook } from './handle-stripe-webhook.ts'
+
+/** The most recent subscription row for a reference, whatever its status; having none is a normal answer. */
+export { readPaymentsSubscription } from './read-payments-subscription.ts'
+
+/** Every completed one-time purchase for a reference, newest first; an empty list is a success. */
+export { listPaymentsPurchases } from './list-payments-purchases.ts'
+
+/** One query against information_schema; it takes the Drizzle client so a health check needs no Stripe key. */
+export { verifyPaymentsTablesExist } from './verify-payments-tables-exist.ts'
+
+/** The Drizzle table map, always carrying all three tables whatever the organizations flag is. */
+export { hearthkitPaymentsDrizzleSchema } from './hearthkit-payments-drizzle-schema.ts'
+
+/** Contract values: the unique literal prefix every returned failure message starts with. */
+export {
+  paymentsCatalogInvalidErrorPrefix,
+  paymentsCustomerNotFoundErrorPrefix,
+  paymentsDatabaseUnavailableErrorPrefix,
+  paymentsInputInvalidErrorPrefix,
+  paymentsPriceNotFoundErrorPrefix,
+  paymentsRequestFailedErrorPrefix,
+  paymentsStripeUnauthorizedErrorPrefix,
+  paymentsStripeUnreachableErrorPrefix,
+  paymentsWebhookSignatureInvalidErrorPrefix,
+} from './payments-contract.ts'
+
+/** Contract values: the Stripe literals this package matches by exact equality, each read off stripe@22.6.1 rather than from documentation. */
+export {
+  stripeForbiddenHttpStatus,
+  stripeOneTimeCheckoutMode,
+  stripeOneTimePriceType,
+  stripeParsedBodySignatureMessagePrefix,
+  stripeRecurringPriceType,
+  stripeSignatureHeaderName,
+  stripeSignatureScheme,
+  stripeSignatureToleranceSeconds,
+  stripeSubscriptionCheckoutMode,
+  stripeUnauthorizedHttpStatus,
+  stripeWrongSchemeSignatureMessage,
+  stripeWrongSecretSignatureMessagePrefix,
+} from './payments-contract.ts'
+
+/** Contract values: the Stripe metadata keys createCheckoutSession writes and the webhook handler reads back. */
+export {
+  hearthkitBillingReferenceMetadataKey,
+  hearthkitBillingScopeMetadataKey,
+  hearthkitPriceNameMetadataKey,
+  hearthkitQuantityMetadataKey,
+  hearthkitStripePriceIdMetadataKey,
+} from './payments-contract.ts'
+
+/** Contract values: the name lists, status lists and limits an app and a gate compare against. */
+export {
+  defaultCheckoutQuantity,
+  handledStripeWebhookEventTypeSchema,
+  handledStripeWebhookEventTypes,
+  hearthkitPaymentsTableNameSchema,
+  hearthkitPaymentsTableNames,
+  maximumPaymentsPriceNameLength,
+  maximumPaymentsProductNameLength,
+  paymentsActiveSubscriptionStatuses,
+  paymentsDatabaseUnavailableCauseCodes,
+  paymentsKnownSubscriptionStatuses,
+} from './payments-contract.ts'
+
+/** Contract values: this package's env fragment and the two secret schemas it is built from. */
+export {
+  paymentsEnvSchemaFragment,
+  stripeSecretKeySchema,
+  stripeWebhookSecretSchema,
+} from './payments-contract.ts'
+
+/** Contract values: the branded vocabulary schemas, so an app can parse an untrusted value before calling anything here. */
+export {
+  billingContactEmailSchema,
+  billingReferenceIdSchema,
+  billingScopeSchema,
+  paymentsCurrencyCodeSchema,
+  paymentsCustomerIdSchema,
+  paymentsPriceNameSchema,
+  paymentsProductNameSchema,
+  paymentsPurchaseIdSchema,
+  paymentsQuantitySchema,
+  paymentsRecurringIntervalSchema,
+  paymentsRedirectUrlSchema,
+  paymentsStripeApiBaseUrlSchema,
+  paymentsSubscriptionIdSchema,
+  paymentsSubscriptionStatusSchema,
+  paymentsUnitAmountMinorUnitsSchema,
+  stripeCheckoutSessionIdSchema,
+  stripeCustomerIdSchema,
+  stripeEventIdSchema,
+  stripePaymentIntentIdSchema,
+  stripePriceIdSchema,
+  stripeProductIdSchema,
+  stripeSubscriptionIdSchema,
+} from './payments-contract.ts'
+
+/** Contract values: the catalog schemas an app validates payments-catalog.ts with, and the three row shapes this package reports. */
+export {
+  paymentsCatalogPriceSchema,
+  paymentsCatalogProductSchema,
+  paymentsCatalogSchema,
+  paymentsCustomerSchema,
+  paymentsOneTimeCatalogPriceSchema,
+  paymentsPurchaseSchema,
+  paymentsSubscriptionCatalogPriceSchema,
+  paymentsSubscriptionSchema,
+} from './payments-contract.ts'
+
+/** Contract values: each failure variant's schema, the discriminator enums, and the union of all nine. */
+export {
+  paymentsCatalogInvalidFailureSchema,
+  paymentsCatalogIssueKindSchema,
+  paymentsCatalogIssueSchema,
+  paymentsCustomerNotFoundFailureSchema,
+  paymentsDatabaseUnavailableFailureSchema,
+  paymentsFailureSchema,
+  paymentsInputInvalidFailureSchema,
+  paymentsInvalidFieldNameSchema,
+  paymentsPriceNotFoundFailureSchema,
+  paymentsRequestFailedFailureSchema,
+  paymentsStripeUnauthorizedFailureSchema,
+  paymentsStripeUnreachableFailureSchema,
+  paymentsWebhookSignatureInvalidFailureSchema,
+  priceLookupFailureSchema,
+  webhookSignatureFailureReasonSchema,
+} from './payments-contract.ts'
+
+/** Contract values: the runtime checks for the three structural values this package takes in or hands back. */
+export {
+  paymentsClientSchema,
+  paymentsDrizzleClientSchema,
+  paymentsRequestHeadersSchema,
+} from './payments-contract.ts'
+
+/** Contract values: each function's options, success-only and full result schemas, so a narrowed result can be validated without rebuilding the schema. */
+export {
+  createCheckoutSessionOptionsSchema,
+  createCheckoutSessionResultSchema,
+  createCustomerPortalSessionOptionsSchema,
+  createCustomerPortalSessionResultSchema,
+  createPaymentsClientOptionsSchema,
+  createPaymentsClientResultSchema,
+  handleStripeWebhookOptionsSchema,
+  handleStripeWebhookResultSchema,
+  listPaymentsPurchasesOptionsSchema,
+  listPaymentsPurchasesResultSchema,
+  paymentsCatalogSyncedSchema,
+  paymentsCheckoutSessionCreatedSchema,
+  paymentsClientCreatedSchema,
+  paymentsPortalSessionCreatedSchema,
+  paymentsPriceSyncActionSchema,
+  paymentsPurchasesListedSchema,
+  paymentsSubscriptionAbsentSchema,
+  paymentsSubscriptionFoundSchema,
+  paymentsSyncedPriceSchema,
+  paymentsTablesMissingSchema,
+  paymentsTablesPresentSchema,
+  paymentsWebhookIgnoredReasonSchema,
+  paymentsWebhookIgnoredSchema,
+  paymentsWebhookOutcomeSchema,
+  paymentsWebhookProcessedSchema,
+  readPaymentsSubscriptionOptionsSchema,
+  readPaymentsSubscriptionResultSchema,
+  syncPaymentsCatalogOptionsSchema,
+  syncPaymentsCatalogResultSchema,
+  verifyPaymentsTablesExistOptionsSchema,
+  verifyPaymentsTablesExistResultSchema,
+} from './payments-contract.ts'
+
+/** Contract types: the branded vocabulary and the two scope words billing is keyed on. */
+export type {
+  BillingContactEmail,
+  BillingReferenceId,
+  BillingReferenceOwnerId,
+  BillingScope,
+  HandledStripeWebhookEventType,
+  HearthkitPaymentsTableName,
+  PaymentsCurrencyCode,
+  PaymentsCustomerId,
+  PaymentsPriceName,
+  PaymentsProductName,
+  PaymentsPurchaseId,
+  PaymentsRecurringInterval,
+  PaymentsSubscriptionId,
+  StripeCheckoutSessionId,
+  StripeCustomerId,
+  StripeEventId,
+  StripePaymentIntentId,
+  StripePriceId,
+  StripeProductId,
+  StripeSecretKey,
+  StripeSubscriptionId,
+  StripeWebhookSecret,
+} from './payments-contract.ts'
+
+/** Contract types: the env values, the catalog, the three records this package reports, and the Drizzle table map. */
+export type {
+  HearthkitPaymentsDrizzleSchema,
+  PaymentsCatalog,
+  PaymentsCatalogPrice,
+  PaymentsCatalogProduct,
+  PaymentsClient,
+  PaymentsCustomer,
+  PaymentsEnvValues,
+  PaymentsPurchase,
+  PaymentsSubscription,
+  PaymentsSyncedPrice,
+} from './payments-contract.ts'
+
+/** Contract types: the failure union and every discriminator carried on one. */
+export type {
+  PaymentsCatalogIssue,
+  PaymentsCatalogIssueKind,
+  PaymentsFailure,
+  PaymentsInvalidFieldName,
+  PaymentsPriceSyncAction,
+  PaymentsWebhookIgnoredReason,
+  PaymentsWebhookOutcome,
+  PriceLookupFailure,
+  WebhookSignatureFailureReason,
+} from './payments-contract.ts'
+
+/** Contract types: the option, result and function shapes of every function above. */
+export type {
+  CreateCheckoutSession,
+  CreateCheckoutSessionOptions,
+  CreateCheckoutSessionResult,
+  CreateCustomerPortalSession,
+  CreateCustomerPortalSessionOptions,
+  CreateCustomerPortalSessionResult,
+  CreatePaymentsClient,
+  CreatePaymentsClientOptions,
+  CreatePaymentsClientResult,
+  HandleStripeWebhook,
+  HandleStripeWebhookOptions,
+  HandleStripeWebhookResult,
+  ListPaymentsPurchases,
+  ListPaymentsPurchasesOptions,
+  ListPaymentsPurchasesResult,
+  ReadPaymentsSubscription,
+  ReadPaymentsSubscriptionOptions,
+  ReadPaymentsSubscriptionResult,
+  SyncPaymentsCatalog,
+  SyncPaymentsCatalogOptions,
+  SyncPaymentsCatalogResult,
+  VerifyPaymentsTablesExist,
+  VerifyPaymentsTablesExistOptions,
+  VerifyPaymentsTablesExistResult,
+} from './payments-contract.ts'

package/src/list-payments-purchases.test.ts

@@ -0,0 +1,132 @@
+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 {
+  buildGateCheckoutSessionObject,
+  buildGateStripeWebhookDelivery,
+  gateBillingReferenceMetadata,
+  gateCheckoutPriceMetadata,
+  gateNowSecondsSinceEpoch,
+  uniqueGateStripeId,
+} from '../test-fixtures/payments-gate-stripe-events.ts'
+import {
+  gatePaymentsCatalog,
+  uniqueGateBillingContactEmail,
+  uniqueGateBillingReferenceId,
+  uniqueGatePaymentsCatalogNames,
+} from '../test-fixtures/payments-gate-values.ts'
+import {
+  createGatePaymentsClient,
+  loadHearthkitPaymentsEntry,
+  type HearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import { listPaymentsPurchasesResultSchema, type PaymentsClient } from './payments-contract.ts'
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  paymentsClient: PaymentsClient
+  gateDatabase: GatePaymentsDatabase
+  oneTimePriceName: string
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  const gateDatabase = await createVerifiedGatePaymentsDatabase('listbuys', paymentsEntry)
+  const catalogNames = uniqueGatePaymentsCatalogNames('listbuys')
+  const paymentsClient = createGatePaymentsClient({
+    paymentsEntry,
+    drizzleClient: gateDatabase.drizzleClient,
+    paymentsCatalog: gatePaymentsCatalog(catalogNames),
+  })
+  return {
+    paymentsEntry,
+    paymentsClient,
+    gateDatabase,
+    oneTimePriceName: catalogNames.oneTimePriceName,
+  }
+})
+
+afterAll(async () => {
+  await gateFile.releaseIfCreated(({ gateDatabase }) => gateDatabase.removeGatePaymentsDatabase())
+})
+
+describe('listPaymentsPurchases', () => {
+  it('reports an empty list as a success for a reference that has bought nothing', async () => {
+    const { paymentsEntry, paymentsClient } = await gateFile.read()
+
+    // An empty array is a success rather than an -absent variant: "what has this customer bought"
+    // has a correct empty answer, whereas "which subscription is current" has no meaningful empty row.
+    const result = await paymentsEntry.listPaymentsPurchases({
+      paymentsClient,
+      billingReferenceId: uniqueGateBillingReferenceId('listbuys-none'),
+    })
+    listPaymentsPurchasesResultSchema.parse(result)
+    expect(expectResultKind(result, 'payments-purchases-listed').paymentsPurchases).toEqual([])
+  })
+
+  it('lists every completed purchase for a reference, newest first', async () => {
+    const { paymentsEntry, paymentsClient, oneTimePriceName } = await gateFile.read()
+    const billingReferenceId = uniqueGateBillingReferenceId('listbuys-two')
+    const nowSeconds = gateNowSecondsSinceEpoch()
+
+    async function deliverPurchase(
+      stripeCheckoutSessionId: string,
+      purchasedAtSeconds: number,
+    ): Promise<void> {
+      const delivery = buildGateStripeWebhookDelivery(paymentsClient, {
+        stripeEventType: 'checkout.session.completed',
+        // purchasedAt comes from the EVENT's created, so the ordering this gate asserts is chosen
+        // here rather than raced for: no sleeping, and no dependence on write order.
+        createdSecondsSinceEpoch: purchasedAtSeconds,
+        eventDataObject: buildGateCheckoutSessionObject({
+          stripeCheckoutSessionId,
+          stripeCustomerId: uniqueGateStripeId('cus'),
+          checkoutMode: 'payment',
+          paymentStatus: 'paid',
+          billingContactEmail: uniqueGateBillingContactEmail('listbuys'),
+          stripePaymentIntentId: uniqueGateStripeId('pi'),
+          currency: 'usd',
+          amountTotalMinorUnits: 29_900,
+          metadata: {
+            ...gateBillingReferenceMetadata(billingReferenceId),
+            ...gateCheckoutPriceMetadata(oneTimePriceName, uniqueGateStripeId('price'), 1),
+          },
+        }),
+      })
+      const result = await paymentsEntry.handleStripeWebhook({
+        paymentsClient,
+        rawRequestBody: delivery.rawRequestBody,
+        requestHeaders: delivery.requestHeaders,
+      })
+      expect(expectResultKind(result, 'payments-webhook-processed').webhookOutcome).toBe(
+        'purchase-recorded',
+      )
+    }
+
+    const olderSessionId = uniqueGateStripeId('cs')
+    const newerSessionId = uniqueGateStripeId('cs')
+    // Delivered oldest last, so a list that came back in insertion order would be wrong in the same
+    // direction as one that came back unsorted.
+    await deliverPurchase(newerSessionId, nowSeconds)
+    await deliverPurchase(olderSessionId, nowSeconds - 3_600)
+
+    const result = await paymentsEntry.listPaymentsPurchases({
+      paymentsClient,
+      billingReferenceId,
+    })
+    listPaymentsPurchasesResultSchema.parse(result)
+    const listed = expectResultKind(result, 'payments-purchases-listed').paymentsPurchases
+
+    expect(listed.map((purchase) => String(purchase.stripeCheckoutSessionId))).toEqual([
+      newerSessionId,
+      olderSessionId,
+    ])
+    // Only this reference's purchases: the other files' references are in other databases, but the
+    // empty-list gate above shares this one, so a query that ignored the reference would show here.
+    for (const purchase of listed) {
+      expect(String(purchase.billingReferenceId)).toBe(billingReferenceId)
+    }
+  })
+})

package/src/list-payments-purchases.ts

@@ -0,0 +1,57 @@
+import { desc, eq } from 'drizzle-orm'
+import { paymentsPurchaseTable } from './hearthkit-payments-drizzle-schema.ts'
+import {
+  billingReferenceIdSchema,
+  paymentsClientSchema,
+  paymentsPurchaseSchema,
+  type ListPaymentsPurchasesOptions,
+  type ListPaymentsPurchasesResult,
+  type PaymentsPurchase,
+} from './payments-contract.ts'
+import {
+  paymentsInputInvalidFailure,
+  paymentsRequestFailedFailure,
+} from './payments-failure-results.ts'
+import { thrownPaymentsErrorToFailure } from './thrown-payments-error-failure.ts'
+
+/**
+ * Every completed one-time purchase for a reference, newest first by purchasedAt with id descending
+ * as the tiebreak. An empty array is a success rather than an -absent variant: "what has this
+ * customer bought" has a correct empty answer, whereas "which subscription is current" has no
+ * meaningful empty row.
+ */
+export async function listPaymentsPurchases(
+  options: ListPaymentsPurchasesOptions,
+): Promise<ListPaymentsPurchasesResult> {
+  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 purchaseRows: (typeof paymentsPurchaseTable.$inferSelect)[]
+  try {
+    purchaseRows = await options.paymentsClient.drizzleClient
+      .select()
+      .from(paymentsPurchaseTable)
+      .where(eq(paymentsPurchaseTable.billingReferenceId, String(parsedReference.data)))
+      .orderBy(desc(paymentsPurchaseTable.purchasedAt), desc(paymentsPurchaseTable.id))
+  } catch (thrownValue) {
+    return thrownPaymentsErrorToFailure(thrownValue, options.paymentsClient)
+  }
+
+  const paymentsPurchases: PaymentsPurchase[] = []
+  for (const purchaseRow of purchaseRows) {
+    const parsedPurchase = paymentsPurchaseSchema.safeParse(purchaseRow)
+    if (!parsedPurchase.success) {
+      return paymentsRequestFailedFailure({
+        paymentsFailureDetail:
+          'a payments_purchase row does not match the shape this package writes, so the table was written by something else',
+      })
+    }
+    paymentsPurchases.push(parsedPurchase.data)
+  }
+  return { kind: 'payments-purchases-listed', paymentsPurchases }
+}

package/src/payments-catalog-lookup.ts

@@ -0,0 +1,23 @@
+import type { PaymentsCatalog, PaymentsCatalogPrice } from './payments-contract.ts'
+
+/**
+ * Resolving a price name against the catalog the client was built with. It is a local map read that
+ * touches no network at all, which is what makes the absent-from-catalog half of
+ * payments-price-not-found deterministic offline: nothing here asks Stripe to tell us a price is
+ * missing, because that answer would be an API error code this repo cannot measure without a key.
+ */
+
+/** The catalog price a name refers to, or nothing when the catalog has never carried that name. */
+export function findPaymentsCatalogPrice(
+  paymentsCatalog: PaymentsCatalog,
+  priceName: string,
+): PaymentsCatalogPrice | undefined {
+  for (const catalogProduct of paymentsCatalog.products) {
+    for (const catalogPrice of catalogProduct.prices) {
+      if (String(catalogPrice.priceName) === priceName) {
+        return catalogPrice
+      }
+    }
+  }
+  return undefined
+}

package/src/payments-catalog-validation.ts

@@ -0,0 +1,190 @@
+import { z } from 'zod'
+import {
+  maximumPaymentsPriceNameLength,
+  maximumPaymentsProductNameLength,
+  paymentsCatalogPriceSchema,
+  paymentsCatalogProductSchema,
+  paymentsCatalogSchema,
+  type PaymentsCatalog,
+  type PaymentsCatalogIssue,
+} from './payments-contract.ts'
+
+/**
+ * Validates the catalog an app wrote in payments-catalog.ts and names every problem in one pass, the
+ * way config reports every bad variable at once, because fixing a catalog one error per boot is
+ * miserable.
+ *
+ * Each reason states the rule that was broken and never the value that broke it, matching
+ * payments-input-invalid's discipline. A catalog is app source rather than user input, but a boot log
+ * is just as public and the rule is cheaper to keep than to reason about case by case.
+ */
+
+// The product schema with its "at least one price" rule lifted, so a product with an empty price list
+// is reported once as product-has-no-prices rather than a second time as a schema rejection, while
+// every other problem in that same entry is still found in this pass.
+const paymentsCatalogProductEntrySchema = paymentsCatalogProductSchema.extend({
+  prices: z.array(paymentsCatalogPriceSchema),
+})
+
+// A hand-written rule per field, for the same reason auth writes authInvalidFieldReasons out by hand:
+// a library's own message is free to quote the input it rejected, and one that did would put a
+// catalog value into a returned failure.
+const paymentsCatalogFieldRules: Record<string, string> = {
+  products: 'must be a list of catalog products',
+  productName: `must be lowercase kebab-case of at most ${String(maximumPaymentsProductNameLength)} characters, because it is also the Stripe product id`,
+  displayName: 'must be from 1 to 250 characters, because a buyer reads it on the checkout page',
+  description: 'must be from 1 to 1000 characters when it is present at all',
+  prices: 'must be a list of catalog prices',
+  priceName: `must be lowercase kebab-case of at most ${String(maximumPaymentsPriceNameLength)} characters, because it is also the Stripe price lookup key`,
+  currency: 'must be exactly three lowercase letters, which is how Stripe spells ISO 4217',
+  unitAmountMinorUnits: 'must be a positive integer of minor currency units',
+  priceKind: 'must be subscription or one-time',
+  recurringInterval: 'must be day, week, month or year, and only on a subscription price',
+  recurringIntervalCount: 'must be a positive integer when it is present at all',
+}
+
+const unknownCatalogFieldRule = 'must match the shape paymentsCatalogSchema describes'
+
+/** True for any non-null object, which is all a catalog entry needs to be before its properties are read one by one. */
+function isCatalogEntryRecord(candidate: unknown): candidate is Record<string, unknown> {
+  return typeof candidate === 'object' && candidate !== null
+}
+
+function readCatalogEntryName(candidate: unknown, propertyName: string): string | undefined {
+  if (!isCatalogEntryRecord(candidate)) {
+    return undefined
+  }
+  const value = candidate[propertyName]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+function readCatalogFieldRule(issuePath: readonly PropertyKey[]): string {
+  for (let index = issuePath.length - 1; index >= 0; index -= 1) {
+    const segment = issuePath[index]
+    if (typeof segment === 'string' && segment in paymentsCatalogFieldRules) {
+      return paymentsCatalogFieldRules[segment] ?? unknownCatalogFieldRule
+    }
+  }
+  return unknownCatalogFieldRule
+}
+
+function readCatalogProductEntries(candidate: unknown): unknown[] | undefined {
+  if (typeof candidate !== 'object' || candidate === null) {
+    return undefined
+  }
+  const { products } = candidate as { products?: unknown }
+  return Array.isArray(products) ? products : undefined
+}
+
+function collectDuplicateNameIssues(
+  names: readonly string[],
+  catalogIssueKind: 'duplicate-product-name' | 'duplicate-price-name',
+  catalogIssueReason: string,
+): PaymentsCatalogIssue[] {
+  const seenCounts = new Map<string, number>()
+  for (const entryName of names) {
+    seenCounts.set(entryName, (seenCounts.get(entryName) ?? 0) + 1)
+  }
+  return [...seenCounts.entries()]
+    .filter(([, count]) => count > 1)
+    .map(([entryName]) => ({ catalogIssueKind, catalogEntryName: entryName, catalogIssueReason }))
+}
+
+/** A catalog this package will hold, or every reason it will not; never a first failure and never the rejected value. */
+export type PaymentsCatalogValidation =
+  | { kind: 'catalog-valid'; paymentsCatalog: PaymentsCatalog }
+  | { kind: 'catalog-invalid'; catalogIssues: PaymentsCatalogIssue[] }
+
+/** Checks an app-supplied catalog once at boot, so a malformed one fails there rather than at a buyer's checkout. */
+export function validatePaymentsCatalogEntries(candidate: unknown): PaymentsCatalogValidation {
+  const productEntries = readCatalogProductEntries(candidate)
+  if (productEntries === undefined || productEntries.length === 0) {
+    return {
+      kind: 'catalog-invalid',
+      catalogIssues: [
+        {
+          catalogIssueKind: 'catalog-has-no-products',
+          catalogEntryName: 'products',
+          catalogIssueReason:
+            'must carry at least one product, because an empty catalog sells nothing',
+        },
+      ],
+    }
+  }
+
+  const catalogIssues: PaymentsCatalogIssue[] = []
+  const productNames: string[] = []
+  const priceNames: string[] = []
+
+  for (const [entryIndex, productEntry] of productEntries.entries()) {
+    const productName = readCatalogEntryName(productEntry, 'productName')
+    const catalogEntryName = productName ?? `products[${String(entryIndex)}]`
+    if (productName !== undefined) {
+      productNames.push(productName)
+    }
+
+    const priceEntries = isCatalogEntryRecord(productEntry) ? productEntry.prices : undefined
+    if (Array.isArray(priceEntries)) {
+      if (priceEntries.length === 0) {
+        catalogIssues.push({
+          catalogIssueKind: 'product-has-no-prices',
+          catalogEntryName,
+          catalogIssueReason:
+            'must carry at least one price, because a product with none is nothing anyone can buy',
+        })
+      }
+      for (const priceEntry of priceEntries) {
+        const priceName = readCatalogEntryName(priceEntry, 'priceName')
+        if (priceName !== undefined) {
+          priceNames.push(priceName)
+        }
+      }
+    }
+
+    const parsedEntry = paymentsCatalogProductEntrySchema.safeParse(productEntry)
+    if (!parsedEntry.success) {
+      for (const issue of parsedEntry.error.issues) {
+        catalogIssues.push({
+          catalogIssueKind: 'entry-invalid',
+          catalogEntryName: `${catalogEntryName}.${issue.path.map(String).join('.') || 'products'}`,
+          catalogIssueReason: readCatalogFieldRule(issue.path),
+        })
+      }
+    }
+  }
+
+  catalogIssues.push(
+    ...collectDuplicateNameIssues(
+      productNames,
+      'duplicate-product-name',
+      'must name each product once, because the product name is also the Stripe product id',
+    ),
+  )
+  // Across the whole catalog and not merely within one product: the price name is also the Stripe
+  // price lookup key, which is unique among active prices in an account, so a per-product check
+  // would pass a catalog Stripe will refuse.
+  catalogIssues.push(
+    ...collectDuplicateNameIssues(
+      priceNames,
+      'duplicate-price-name',
+      'must name each price once across the whole catalog, because the price name is also the Stripe price lookup key',
+    ),
+  )
+
+  if (catalogIssues.length > 0) {
+    return { kind: 'catalog-invalid', catalogIssues }
+  }
+
+  const parsedCatalog = paymentsCatalogSchema.safeParse(candidate)
+  if (!parsedCatalog.success) {
+    return {
+      kind: 'catalog-invalid',
+      catalogIssues: parsedCatalog.error.issues.map((issue) => ({
+        catalogIssueKind: 'entry-invalid' as const,
+        catalogEntryName: issue.path.map(String).join('.') || 'products',
+        catalogIssueReason: readCatalogFieldRule(issue.path),
+      })),
+    }
+  }
+  return { kind: 'catalog-valid', paymentsCatalog: parsedCatalog.data }
+}