@hearthkit/payments 0.1.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hearthkit/payments",
+  "version": "0.1.0",
+  "description": "Stripe subscriptions and one-time purchases: catalog sync, hosted checkout, the hosted customer portal, and the webhook handler",
+  "homepage": "https://github.com/chrisdevelops/hearthkit/tree/main/packages/payments",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrisdevelops/hearthkit.git",
+    "directory": "packages/payments"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./payments-contract": {
+      "types": "./src/payments-contract.ts",
+      "default": "./src/payments-contract.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": "24.20.0"
+  },
+  "dependencies": {
+    "drizzle-orm": "0.45.2",
+    "stripe": "22.6.1",
+    "zod": "4.4.3",
+    "@hearthkit/auth": "0.1.0",
+    "@hearthkit/db": "0.1.0",
+    "@hearthkit/config": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@types/pg": "8.23.1",
+    "pg": "8.23.0",
+    "typescript": "7.0.2",
+    "vitest": "4.1.11"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/create-checkout-session.test.ts

@@ -0,0 +1,268 @@
+import { afterAll, describe, expect, it } from 'vitest'
+import {
+  expectPaymentsFailure,
+  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 {
+  archiveGateStripeCatalog,
+  assertGateStripeIsTestMode,
+  deleteGateStripeCustomer,
+  readGateStripeCheckoutSession,
+} from '../test-fixtures/payments-gate-stripe-account.ts'
+import {
+  deadStripeApiBaseUrl,
+  gateCancelUrl,
+  gatePaymentsCatalog,
+  gateStripeSecretKey,
+  gateSuccessUrl,
+  gateSuccessUrlWithCheckoutSessionPlaceholder,
+  hasGateStripeSecretKey,
+  reserveDeadLoopbackPort,
+  uniqueGateBillingContactEmail,
+  uniqueGateBillingReferenceId,
+  uniqueGatePaymentsCatalogNames,
+  type GatePaymentsCatalogNames,
+} from '../test-fixtures/payments-gate-values.ts'
+import {
+  createGatePaymentsClient,
+  loadHearthkitPaymentsEntry,
+  type HearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import {
+  createCheckoutSessionResultSchema,
+  stripeOneTimeCheckoutMode,
+  stripeSubscriptionCheckoutMode,
+  type PaymentsClient,
+  type PaymentsSyncedPrice,
+} from './payments-contract.ts'
+
+/**
+ * The catalog half of the price lookup is a local map read and needs no network at all, so it is
+ * gated offline; the Stripe half needs a real test-mode account. Neither asks Stripe to tell us the
+ * price is missing: the Stripe arm is an empty prices.list result, which is a 200 with no data rather
+ * than an error, so depending on an API error code was never necessary.
+ */
+
+const createdStripeCustomerIds: string[] = []
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  gateDatabase: GatePaymentsDatabase
+  offlineClient: PaymentsClient
+  catalogNames: GatePaymentsCatalogNames
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  const gateDatabase = await createVerifiedGatePaymentsDatabase('checkout', paymentsEntry)
+  const catalogNames = uniqueGatePaymentsCatalogNames('checkout')
+  const offlineClient = createGatePaymentsClient({
+    paymentsEntry,
+    drizzleClient: gateDatabase.drizzleClient,
+    paymentsCatalog: gatePaymentsCatalog(catalogNames),
+    stripeApiBaseUrl: deadStripeApiBaseUrl(await reserveDeadLoopbackPort()),
+  })
+  return { paymentsEntry, gateDatabase, offlineClient, catalogNames }
+})
+
+/**
+ * The live account, with the catalog pushed to it once and the test-mode guard asserted on the very
+ * first object that came back. Everything else in this file that touches Stripe reads this, so
+ * nothing is created after a live key is detected.
+ */
+const liveGateFile = defineGateFileContext<{
+  liveClient: PaymentsClient
+  syncedPrices: readonly PaymentsSyncedPrice[]
+}>(async () => {
+  const { paymentsEntry, gateDatabase, catalogNames } = await gateFile.read()
+  const liveClient = createGatePaymentsClient({
+    paymentsEntry,
+    drizzleClient: gateDatabase.drizzleClient,
+    paymentsCatalog: gatePaymentsCatalog(catalogNames),
+    stripeSecretKey: gateStripeSecretKey,
+  })
+  const synced = expectResultKind(
+    await paymentsEntry.syncPaymentsCatalog({ paymentsClient: liveClient }),
+    'payments-catalog-synced',
+  )
+  assertGateStripeIsTestMode(synced.stripeLivemode)
+  return { liveClient, syncedPrices: synced.syncedPrices }
+})
+
+afterAll(async () => {
+  await liveGateFile.releaseIfCreated(async ({ liveClient, syncedPrices }) => {
+    for (const stripeCustomerId of createdStripeCustomerIds) {
+      await deleteGateStripeCustomer(liveClient, stripeCustomerId)
+    }
+    await archiveGateStripeCatalog(liveClient, syncedPrices)
+  })
+  await gateFile.releaseIfCreated(({ gateDatabase }) => gateDatabase.removeGatePaymentsDatabase())
+})
+
+describe('createCheckoutSession', () => {
+  it('reports payments-price-not-found with absent-from-catalog for a name the catalog does not have, contacting Stripe never', async () => {
+    const { paymentsEntry, offlineClient } = await gateFile.read()
+    const priceName = 'gate-price-no-catalog-ever-had'
+
+    // The client's Stripe API base URL is a closed local port, so a lookup that reached the network
+    // would answer payments-stripe-unreachable. absent-from-catalog is decided before that: it is a
+    // code mistake, and the operator's next step is to fix payments-catalog.ts rather than run sync.
+    const result = await paymentsEntry.createCheckoutSession({
+      paymentsClient: offlineClient,
+      billingReferenceId: uniqueGateBillingReferenceId('checkout-nocatalog'),
+      billingContactEmail: uniqueGateBillingContactEmail('checkout-nocatalog'),
+      priceName,
+      successUrl: gateSuccessUrl,
+      cancelUrl: gateCancelUrl,
+    })
+    createCheckoutSessionResultSchema.parse(result)
+    const failure = expectPaymentsFailure(result, 'payments-price-not-found')
+    expect(failure.priceLookupFailure).toBe('absent-from-catalog')
+    expect(failure.priceName).toBe(priceName)
+  })
+
+  it('accepts a success URL carrying Stripe placeholder braces rather than rejecting it as an invalid URL', async () => {
+    const { paymentsEntry, offlineClient, catalogNames } = await gateFile.read()
+
+    // CONTRACT.md lists "whether z.url() at zod@4.4.3 accepts a URL containing {CHECKOUT_SESSION_ID}"
+    // under Still not verified. If the schema rejects it this comes back payments-input-invalid
+    // naming success-url, and the schema has to loosen to a protocol-and-authority check. Reaching
+    // the closed Stripe port instead is what proves validation let the placeholder through.
+    const result = await paymentsEntry.createCheckoutSession({
+      paymentsClient: offlineClient,
+      billingReferenceId: uniqueGateBillingReferenceId('checkout-placeholder'),
+      billingContactEmail: uniqueGateBillingContactEmail('checkout-placeholder'),
+      priceName: catalogNames.subscriptionPriceName,
+      successUrl: gateSuccessUrlWithCheckoutSessionPlaceholder,
+      cancelUrl: gateCancelUrl,
+    })
+    createCheckoutSessionResultSchema.parse(result)
+    expect(result.kind).not.toBe('payments-input-invalid')
+    expectPaymentsFailure(result, 'payments-stripe-unreachable')
+  })
+
+  it.skipIf(!hasGateStripeSecretKey)(
+    'creates a hosted checkout session for a subscription price in test mode, handing the success URL to Stripe byte for byte',
+    async () => {
+      const { paymentsEntry, catalogNames } = await gateFile.read()
+      const { liveClient } = await liveGateFile.read()
+
+      const result = await paymentsEntry.createCheckoutSession({
+        paymentsClient: liveClient,
+        billingReferenceId: uniqueGateBillingReferenceId('checkout-live'),
+        billingContactEmail: uniqueGateBillingContactEmail('checkout-live'),
+        priceName: catalogNames.subscriptionPriceName,
+        quantity: 2,
+        successUrl: gateSuccessUrlWithCheckoutSessionPlaceholder,
+        cancelUrl: gateCancelUrl,
+      })
+      createCheckoutSessionResultSchema.parse(result)
+      const created = expectResultKind(result, 'payments-checkout-session-created')
+      createdStripeCustomerIds.push(String(created.stripeCustomerId))
+
+      // Read off the object Stripe answered with, which is a measurement rather than a match on an
+      // API key prefix.
+      expect(created.stripeLivemode).toBe(false)
+      expect(String(created.priceName)).toBe(catalogNames.subscriptionPriceName)
+      // Stripe types Session.url as `string | null` because it is only present while a hosted
+      // session is active; this package always creates hosted sessions, so a null there is not a
+      // contract state and would have come back as payments-request-failed instead.
+      expect(created.checkoutUrl.startsWith('https://')).toBe(true)
+
+      const storedSession = await readGateStripeCheckoutSession(
+        liveClient,
+        String(created.stripeCheckoutSessionId),
+      )
+      // A subscription price maps to checkout mode `subscription`, which happens to be the same word
+      // this package uses; the one-time case below is where the spellings diverge.
+      expect(storedSession.mode).toBe(stripeSubscriptionCheckoutMode)
+      // The URL is handed over unchanged, never round-tripped through `new URL(value).href`, which
+      // percent-encodes the braces and turns Stripe's placeholder into literal text it never
+      // substitutes. The symptom would be a success page receiving %7BCHECKOUT_SESSION_ID%7D.
+      expect(storedSession.success_url).toBe(gateSuccessUrlWithCheckoutSessionPlaceholder)
+    },
+  )
+
+  it.skipIf(!hasGateStripeSecretKey)(
+    'reuses the Stripe customer already on file when the same reference buys again, this time a one-time price',
+    async () => {
+      const { paymentsEntry, catalogNames } = await gateFile.read()
+      const { liveClient } = await liveGateFile.read()
+      const billingReferenceId = uniqueGateBillingReferenceId('checkout-reuse')
+      const billingContactEmail = uniqueGateBillingContactEmail('checkout-reuse')
+
+      const first = expectResultKind(
+        await paymentsEntry.createCheckoutSession({
+          paymentsClient: liveClient,
+          billingReferenceId,
+          billingContactEmail,
+          priceName: catalogNames.subscriptionPriceName,
+          successUrl: gateSuccessUrl,
+          cancelUrl: gateCancelUrl,
+        }),
+        'payments-checkout-session-created',
+      )
+      createdStripeCustomerIds.push(String(first.stripeCustomerId))
+
+      const second = expectResultKind(
+        await paymentsEntry.createCheckoutSession({
+          paymentsClient: liveClient,
+          billingReferenceId,
+          billingContactEmail,
+          priceName: catalogNames.oneTimePriceName,
+          successUrl: gateSuccessUrl,
+          cancelUrl: gateCancelUrl,
+        }),
+        'payments-checkout-session-created',
+      )
+
+      // One Stripe customer per billing reference. A second customer here would orphan the first
+      // one's payment methods and split one person's billing history in two.
+      expect(String(second.stripeCustomerId)).toBe(String(first.stripeCustomerId))
+      expect(String(second.priceName)).toBe(catalogNames.oneTimePriceName)
+
+      const storedSession = await readGateStripeCheckoutSession(
+        liveClient,
+        String(second.stripeCheckoutSessionId),
+      )
+      // Note the spelling: a one-time price is Stripe price type `one_time` with an underscore, but
+      // its checkout mode is `payment`. Three names for one idea, and all three are real.
+      expect(storedSession.mode).toBe(stripeOneTimeCheckoutMode)
+    },
+  )
+
+  it.skipIf(!hasGateStripeSecretKey)(
+    'reports payments-price-not-found with absent-from-stripe when the catalog has the price but sync has never run for it',
+    async () => {
+      const { paymentsEntry, gateDatabase } = await gateFile.read()
+      // A catalog whose names have never been pushed anywhere. Every name a gate run makes up is
+      // unique, so nothing in the shared test-mode account can be carrying this lookup key.
+      const unsyncedNames = uniqueGatePaymentsCatalogNames('checkoutunsynced')
+      const unsyncedClient = createGatePaymentsClient({
+        paymentsEntry,
+        drizzleClient: gateDatabase.drizzleClient,
+        paymentsCatalog: gatePaymentsCatalog(unsyncedNames),
+        stripeSecretKey: gateStripeSecretKey,
+      })
+
+      const result = await paymentsEntry.createCheckoutSession({
+        paymentsClient: unsyncedClient,
+        billingReferenceId: uniqueGateBillingReferenceId('checkout-unsynced'),
+        billingContactEmail: uniqueGateBillingContactEmail('checkout-unsynced'),
+        priceName: unsyncedNames.subscriptionPriceName,
+        successUrl: gateSuccessUrl,
+        cancelUrl: gateCancelUrl,
+      })
+      createCheckoutSessionResultSchema.parse(result)
+      const failure = expectPaymentsFailure(result, 'payments-price-not-found')
+      // The other half of the same variant. The caller does the same thing with both — tell the
+      // buyer this plan is unavailable — and only the operator's next step differs, which here is
+      // to run hearthkit payments sync against this account.
+      expect(failure.priceLookupFailure).toBe('absent-from-stripe')
+      expect(failure.priceName).toBe(unsyncedNames.subscriptionPriceName)
+    },
+  )
+})

package/src/create-checkout-session.ts

@@ -0,0 +1,216 @@
+import type Stripe from 'stripe'
+import { findPaymentsCatalogPrice } from './payments-catalog-lookup.ts'
+import {
+  billingContactEmailSchema,
+  billingReferenceIdSchema,
+  defaultCheckoutQuantity,
+  hearthkitBillingReferenceMetadataKey,
+  hearthkitBillingScopeMetadataKey,
+  hearthkitPriceNameMetadataKey,
+  hearthkitQuantityMetadataKey,
+  hearthkitStripePriceIdMetadataKey,
+  paymentsClientSchema,
+  paymentsPriceNameSchema,
+  paymentsQuantitySchema,
+  paymentsRedirectUrlSchema,
+  stripeCheckoutSessionIdSchema,
+  stripeCustomerIdSchema,
+  stripeOneTimeCheckoutMode,
+  stripeSubscriptionCheckoutMode,
+  type CreateCheckoutSessionOptions,
+  type CreateCheckoutSessionResult,
+  type PaymentsCatalogPrice,
+  type PaymentsClient,
+} from './payments-contract.ts'
+import {
+  readPaymentsCustomerRow,
+  upsertPaymentsCustomerFromCheckout,
+} from './payments-customer-record.ts'
+import {
+  paymentsInputInvalidFailure,
+  paymentsPriceNotFoundFailure,
+  paymentsRequestFailedFailure,
+} from './payments-failure-results.ts'
+import { findActiveStripePriceByLookupKey } from './stripe-price-lookup-key.ts'
+import { thrownPaymentsErrorToFailure } from './thrown-payments-error-failure.ts'
+
+/**
+ * Creates a hosted Checkout Session, creating the Stripe customer and the local customer row when
+ * neither exists yet. That is why this function can never report payments-customer-not-found: it is
+ * the thing that puts a customer on file, and only the portal call refuses to.
+ *
+ * Every caller-supplied value is a plain string or number on the options object and is validated here
+ * before any service is contacted, because these values always originate from user input or from an
+ * HTTP request and validating them late produces a diagnostic that points at the wrong cause.
+ */
+
+// Three spellings of one idea, and all three are real: this package's priceKind, Stripe's Price.type,
+// and Stripe's checkout mode. Note that the one-time case is `payment` here and `one_time` on the
+// price object, and that Stripe's own word changes between the two.
+function checkoutModeForCatalogPrice(
+  catalogPrice: PaymentsCatalogPrice,
+): Stripe.Checkout.SessionCreateParams.Mode {
+  return catalogPrice.priceKind === 'subscription'
+    ? stripeSubscriptionCheckoutMode
+    : stripeOneTimeCheckoutMode
+}
+
+type ValidatedCheckoutInput = {
+  paymentsClient: PaymentsClient
+  billingReferenceId: string
+  billingContactEmail: string
+  priceName: string
+  quantity: number
+  successUrl: string
+  cancelUrl: string
+}
+
+function validateCheckoutInput(
+  options: CreateCheckoutSessionOptions,
+): ValidatedCheckoutInput | CreateCheckoutSessionResult {
+  if (!paymentsClientSchema.safeParse(options.paymentsClient).success) {
+    return paymentsInputInvalidFailure('drizzle-client')
+  }
+  if (!billingReferenceIdSchema.safeParse(options.billingReferenceId).success) {
+    return paymentsInputInvalidFailure('billing-reference-id')
+  }
+  if (!billingContactEmailSchema.safeParse(options.billingContactEmail).success) {
+    return paymentsInputInvalidFailure('billing-contact-email')
+  }
+  // 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 have been a Stripe lookup key in the first place.
+  if (!paymentsPriceNameSchema.safeParse(options.priceName).success) {
+    return paymentsInputInvalidFailure('price-name')
+  }
+  const quantity = options.quantity ?? defaultCheckoutQuantity
+  if (!paymentsQuantitySchema.safeParse(quantity).success) {
+    return paymentsInputInvalidFailure('quantity')
+  }
+  if (!paymentsRedirectUrlSchema.safeParse(options.successUrl).success) {
+    return paymentsInputInvalidFailure('success-url')
+  }
+  if (!paymentsRedirectUrlSchema.safeParse(options.cancelUrl).success) {
+    return paymentsInputInvalidFailure('cancel-url')
+  }
+  return {
+    paymentsClient: options.paymentsClient,
+    billingReferenceId: options.billingReferenceId,
+    billingContactEmail: options.billingContactEmail,
+    priceName: options.priceName,
+    quantity,
+    // Handed to Stripe byte for byte, never round-tripped through `new URL(value).href`: Stripe
+    // supports a {CHECKOUT_SESSION_ID} placeholder in success_url, and normalising percent-encodes the
+    // braces, which turns the placeholder into literal text Stripe never substitutes.
+    successUrl: options.successUrl,
+    cancelUrl: options.cancelUrl,
+  }
+}
+
+async function resolveCheckoutStripeCustomerId(input: ValidatedCheckoutInput): Promise<string> {
+  const existingCustomerRow = await readPaymentsCustomerRow(
+    input.paymentsClient.drizzleClient,
+    input.billingReferenceId,
+  )
+  const stripeCustomerId =
+    existingCustomerRow?.stripeCustomerId ??
+    (
+      await input.paymentsClient.stripeClient.customers.create({
+        email: input.billingContactEmail,
+        metadata: {
+          [hearthkitBillingReferenceMetadataKey]: input.billingReferenceId,
+          [hearthkitBillingScopeMetadataKey]: input.paymentsClient.billingScope,
+        },
+      })
+    ).id
+
+  // One Stripe customer per billing reference: a second one would orphan the first one's payment
+  // methods and split one person's billing history in two.
+  await upsertPaymentsCustomerFromCheckout(input.paymentsClient.drizzleClient, {
+    billingReferenceId: input.billingReferenceId,
+    billingScope: input.paymentsClient.billingScope,
+    stripeCustomerId,
+    billingContactEmail: input.billingContactEmail,
+    writtenAt: new Date(),
+  })
+  return stripeCustomerId
+}
+
+/** Resolves the price, puts a Stripe customer on file, and opens a hosted Checkout Session. */
+export async function createCheckoutSession(
+  options: CreateCheckoutSessionOptions,
+): Promise<CreateCheckoutSessionResult> {
+  const input = validateCheckoutInput(options)
+  if ('kind' in input) {
+    return input
+  }
+
+  const catalogPrice = findPaymentsCatalogPrice(
+    input.paymentsClient.paymentsCatalog,
+    input.priceName,
+  )
+  if (catalogPrice === undefined) {
+    return paymentsPriceNotFoundFailure(input.priceName, 'absent-from-catalog')
+  }
+
+  try {
+    const stripePrice = await findActiveStripePriceByLookupKey(
+      input.paymentsClient.stripeClient,
+      input.priceName,
+    )
+    if (stripePrice === undefined) {
+      return paymentsPriceNotFoundFailure(input.priceName, 'absent-from-stripe')
+    }
+
+    const stripeCustomerId = await resolveCheckoutStripeCustomerId(input)
+    const referenceMetadata = {
+      [hearthkitBillingReferenceMetadataKey]: input.billingReferenceId,
+      [hearthkitBillingScopeMetadataKey]: input.paymentsClient.billingScope,
+    }
+    const checkoutMode = checkoutModeForCatalogPrice(catalogPrice)
+
+    const checkoutSession = await input.paymentsClient.stripeClient.checkout.sessions.create({
+      mode: checkoutMode,
+      customer: stripeCustomerId,
+      line_items: [{ price: stripePrice.id, quantity: input.quantity }],
+      success_url: input.successUrl,
+      cancel_url: input.cancelUrl,
+      // The price trio goes on the SESSION and never on subscription_data.metadata: a portal upgrade
+      // changes a subscription's price without touching metadata stamped at creation, so a stamped
+      // price name would go stale and then be reported as fact. It is here because a webhook delivery
+      // carries no line_items, so the purchase path has no other source for what it sold.
+      metadata: {
+        ...referenceMetadata,
+        [hearthkitPriceNameMetadataKey]: input.priceName,
+        [hearthkitStripePriceIdMetadataKey]: stripePrice.id,
+        [hearthkitQuantityMetadataKey]: String(input.quantity),
+      },
+      // The second copy of the two reference keys, so customer.subscription.* events carry them on the
+      // subscription object itself; without it those events have no reference at all.
+      ...(checkoutMode === stripeSubscriptionCheckoutMode
+        ? { subscription_data: { metadata: referenceMetadata } }
+        : {}),
+    })
+
+    // Stripe types Session.url as `string | null` because it is only present while a hosted session is
+    // active; this package always creates hosted sessions, so a null there is not a contract state.
+    if (checkoutSession.url === null) {
+      return paymentsRequestFailedFailure({
+        paymentsFailureDetail:
+          'Stripe created the checkout session without a hosted page URL, which a hosted session always has while it is active',
+      })
+    }
+
+    return {
+      kind: 'payments-checkout-session-created',
+      stripeCheckoutSessionId: stripeCheckoutSessionIdSchema.parse(checkoutSession.id),
+      checkoutUrl: checkoutSession.url,
+      stripeCustomerId: stripeCustomerIdSchema.parse(stripeCustomerId),
+      priceName: paymentsPriceNameSchema.parse(input.priceName),
+      // Read off the object Stripe answered with, whose own generated type says it is true in live
+      // mode and false in test mode. That is a measurement, not a match on an API key prefix.
+      stripeLivemode: checkoutSession.livemode,
+    }
+  } catch (thrownValue) {
+    return thrownPaymentsErrorToFailure(thrownValue, input.paymentsClient)
+  }
+}