@hearthkit/payments 0.1.0

package/src/create-customer-portal-session.test.ts

@@ -0,0 +1,160 @@
+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,
+} from '../test-fixtures/payments-gate-stripe-account.ts'
+import {
+  deadStripeApiBaseUrl,
+  gateCancelUrl,
+  gatePaymentsCatalog,
+  gateReturnUrl,
+  gateStripeSecretKey,
+  gateSuccessUrl,
+  hasGateStripeSecretKey,
+  reserveDeadLoopbackPort,
+  uniqueGateBillingContactEmail,
+  uniqueGateBillingReferenceId,
+  uniqueGatePaymentsCatalogNames,
+} from '../test-fixtures/payments-gate-values.ts'
+import {
+  createGatePaymentsClient,
+  loadHearthkitPaymentsEntry,
+  type HearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import {
+  createCustomerPortalSessionResultSchema,
+  type PaymentsClient,
+  type PaymentsSyncedPrice,
+} from './payments-contract.ts'
+
+/**
+ * createCustomerPortalSession never creates anything — opening a billing portal for a person who has
+ * never paid is not a thing to do quietly — so it is the only producer of
+ * payments-customer-not-found. That half needs no Stripe key. Opening a real portal does.
+ */
+
+const createdStripePrices: PaymentsSyncedPrice[] = []
+const createdStripeCustomerIds: string[] = []
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  gateDatabase: GatePaymentsDatabase
+  offlineClient: PaymentsClient
+  liveClient: PaymentsClient | undefined
+  subscriptionPriceName: string
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  const gateDatabase = await createVerifiedGatePaymentsDatabase('portal', paymentsEntry)
+  const catalogNames = uniqueGatePaymentsCatalogNames('portal')
+  const paymentsCatalog = gatePaymentsCatalog(catalogNames)
+  const offlineClient = createGatePaymentsClient({
+    paymentsEntry,
+    drizzleClient: gateDatabase.drizzleClient,
+    paymentsCatalog,
+    stripeApiBaseUrl: deadStripeApiBaseUrl(await reserveDeadLoopbackPort()),
+  })
+  const liveClient = hasGateStripeSecretKey
+    ? createGatePaymentsClient({
+        paymentsEntry,
+        drizzleClient: gateDatabase.drizzleClient,
+        paymentsCatalog,
+        stripeSecretKey: gateStripeSecretKey,
+      })
+    : undefined
+  return {
+    paymentsEntry,
+    gateDatabase,
+    offlineClient,
+    liveClient,
+    subscriptionPriceName: catalogNames.subscriptionPriceName,
+  }
+})
+
+afterAll(async () => {
+  await gateFile.releaseIfCreated(async ({ gateDatabase, liveClient }) => {
+    if (liveClient !== undefined) {
+      for (const stripeCustomerId of createdStripeCustomerIds) {
+        await deleteGateStripeCustomer(liveClient, stripeCustomerId)
+      }
+      await archiveGateStripeCatalog(liveClient, createdStripePrices)
+    }
+    await gateDatabase.removeGatePaymentsDatabase()
+  })
+})
+
+describe('createCustomerPortalSession', () => {
+  it('reports payments-customer-not-found for a reference with no customer row, without contacting Stripe', async () => {
+    const { paymentsEntry, offlineClient } = await gateFile.read()
+    const billingReferenceId = uniqueGateBillingReferenceId('portal-none')
+
+    // The client's Stripe API base URL is a closed local port, so a call that asked Stripe about the
+    // customer would answer payments-stripe-unreachable. This failure is an empty query result
+    // instead: no API-level error code is consulted, which is what makes it deterministic offline.
+    const result = await paymentsEntry.createCustomerPortalSession({
+      paymentsClient: offlineClient,
+      billingReferenceId,
+      returnUrl: gateReturnUrl,
+    })
+    createCustomerPortalSessionResultSchema.parse(result)
+    const failure = expectPaymentsFailure(result, 'payments-customer-not-found')
+    expect(String(failure.billingReferenceId)).toBe(billingReferenceId)
+  })
+
+  it.skipIf(!hasGateStripeSecretKey)(
+    'opens the hosted billing portal for a customer a checkout put on file',
+    async () => {
+      const { paymentsEntry, liveClient, subscriptionPriceName } = await gateFile.read()
+      expect(liveClient, 'this gate runs only with STRIPE_SECRET_KEY set').toBeDefined()
+      if (liveClient === undefined) {
+        return
+      }
+
+      const synced = expectResultKind(
+        await paymentsEntry.syncPaymentsCatalog({ paymentsClient: liveClient }),
+        'payments-catalog-synced',
+      )
+      createdStripePrices.push(...synced.syncedPrices)
+      assertGateStripeIsTestMode(synced.stripeLivemode)
+
+      const billingReferenceId = uniqueGateBillingReferenceId('portal-live')
+      const checkout = expectResultKind(
+        await paymentsEntry.createCheckoutSession({
+          paymentsClient: liveClient,
+          billingReferenceId,
+          billingContactEmail: uniqueGateBillingContactEmail('portal-live'),
+          priceName: subscriptionPriceName,
+          successUrl: gateSuccessUrl,
+          cancelUrl: gateCancelUrl,
+        }),
+        'payments-checkout-session-created',
+      )
+      createdStripeCustomerIds.push(String(checkout.stripeCustomerId))
+
+      // If this fails with a Stripe error about a portal configuration, the test-mode account needs
+      // its billing portal settings saved once in the Stripe dashboard. CONTRACT.md flags that under
+      // Still not verified precisely so the failure does not read as a bug in this package.
+      const result = await paymentsEntry.createCustomerPortalSession({
+        paymentsClient: liveClient,
+        billingReferenceId,
+        returnUrl: gateReturnUrl,
+      })
+      createCustomerPortalSessionResultSchema.parse(result)
+      const opened = expectResultKind(result, 'payments-portal-session-created')
+
+      // BillingPortal.Session.url is typed non-nullable, so unlike checkoutUrl there is no null case.
+      expect(opened.portalUrl.startsWith('https://')).toBe(true)
+      // The customer already on file, not a second one: this call never creates anything.
+      expect(String(opened.stripeCustomerId)).toBe(String(checkout.stripeCustomerId))
+    },
+  )
+})

package/src/create-customer-portal-session.ts

@@ -0,0 +1,66 @@
+import {
+  billingReferenceIdSchema,
+  paymentsClientSchema,
+  paymentsRedirectUrlSchema,
+  stripeCustomerIdSchema,
+  type CreateCustomerPortalSessionOptions,
+  type CreateCustomerPortalSessionResult,
+} from './payments-contract.ts'
+import { readPaymentsCustomerRow } from './payments-customer-record.ts'
+import {
+  paymentsCustomerNotFoundFailure,
+  paymentsInputInvalidFailure,
+} from './payments-failure-results.ts'
+import { thrownPaymentsErrorToFailure } from './thrown-payments-error-failure.ts'
+
+/**
+ * Opens Stripe's hosted billing portal for the customer already on file. It never creates one —
+ * opening a billing portal for a person who has never paid is not a thing to do quietly — which is
+ * why this is the only producer of payments-customer-not-found in the whole package.
+ *
+ * That failure is an empty query result rather than an API-level error code, so it is deterministic
+ * and needs no network at all: nothing here asks Stripe to tell us the customer is missing.
+ *
+ * If a live call fails with a Stripe error about a portal configuration, the account needs its
+ * test-mode billing portal settings saved once in the Stripe dashboard. That is a one-off human step
+ * rather than a bug in this package.
+ */
+export async function createCustomerPortalSession(
+  options: CreateCustomerPortalSessionOptions,
+): Promise<CreateCustomerPortalSessionResult> {
+  if (!paymentsClientSchema.safeParse(options.paymentsClient).success) {
+    return paymentsInputInvalidFailure('drizzle-client')
+  }
+  const parsedReference = billingReferenceIdSchema.safeParse(options.billingReferenceId)
+  if (!parsedReference.success) {
+    return paymentsInputInvalidFailure('billing-reference-id')
+  }
+  if (!paymentsRedirectUrlSchema.safeParse(options.returnUrl).success) {
+    return paymentsInputInvalidFailure('return-url')
+  }
+
+  try {
+    const customerRow = await readPaymentsCustomerRow(
+      options.paymentsClient.drizzleClient,
+      String(parsedReference.data),
+    )
+    if (customerRow === undefined) {
+      return paymentsCustomerNotFoundFailure(parsedReference.data)
+    }
+
+    // BillingPortal.Session.url is typed non-nullable, so unlike a checkout session's url there is no
+    // null case to rule out here.
+    const portalSession = await options.paymentsClient.stripeClient.billingPortal.sessions.create({
+      customer: customerRow.stripeCustomerId,
+      return_url: options.returnUrl,
+    })
+
+    return {
+      kind: 'payments-portal-session-created',
+      portalUrl: portalSession.url,
+      stripeCustomerId: stripeCustomerIdSchema.parse(customerRow.stripeCustomerId),
+    }
+  } catch (thrownValue) {
+    return thrownPaymentsErrorToFailure(thrownValue, options.paymentsClient)
+  }
+}

package/src/create-payments-client.test.ts

@@ -0,0 +1,231 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres'
+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 {
+  gatePaymentsCatalog,
+  gatePaymentsEnv,
+  uniqueGatePaymentsCatalogNames,
+} from '../test-fixtures/payments-gate-values.ts'
+import {
+  loadHearthkitPaymentsEntry,
+  type HearthkitPaymentsEntry,
+} from '../test-fixtures/hearthkit-payments-entry.ts'
+import {
+  createPaymentsClientResultSchema,
+  type PaymentsCatalog,
+  type PaymentsEnvValues,
+} from './payments-contract.ts'
+
+/**
+ * createPaymentsClient contacts nothing: building a Stripe instance does no I/O and the Drizzle
+ * client is lazy. So this whole file runs with no service anywhere, and the Drizzle client it uses
+ * points at a closed port on purpose — if any gate here reached the database it would fail with
+ * payments-database-unavailable rather than the answer it asserts.
+ */
+
+const gateFile = defineGateFileContext<{
+  paymentsEntry: HearthkitPaymentsEntry
+  drizzleClient: NodePgDatabase<Record<string, unknown>>
+  closeDatabaseClient: () => Promise<void>
+}>(async () => {
+  const paymentsEntry = await loadHearthkitPaymentsEntry()
+  const { drizzleClient, closeDatabaseClient } = createGateDrizzleClientForUrl(
+    unreachableGateDatabaseUrl,
+    paymentsEntry.hearthkitPaymentsDrizzleSchema,
+  )
+  return { paymentsEntry, drizzleClient, closeDatabaseClient }
+})
+
+afterAll(async () => {
+  await gateFile.releaseIfCreated(({ closeDatabaseClient }) => closeDatabaseClient())
+})
+
+// Four problems in one catalog, which is the point: CONTRACT.md says catalogIssues 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. `gate-shared-price` appears under two different products, which
+// is the case a per-product uniqueness check would miss.
+const catalogWithEveryProblem = {
+  products: [
+    {
+      productName: 'gate-duplicated',
+      displayName: 'Gate Duplicated',
+      prices: [
+        {
+          priceName: 'gate-shared-price',
+          currency: 'usd',
+          unitAmountMinorUnits: 1900,
+          priceKind: 'subscription',
+          recurringInterval: 'month',
+        },
+      ],
+    },
+    {
+      productName: 'gate-duplicated',
+      displayName: 'Gate Duplicated Again',
+      prices: [
+        {
+          priceName: 'gate-other-price',
+          currency: 'usd',
+          unitAmountMinorUnits: 500,
+          priceKind: 'one-time',
+        },
+      ],
+    },
+    {
+      productName: 'gate-third',
+      displayName: 'Gate Third',
+      prices: [
+        {
+          priceName: 'gate-shared-price',
+          currency: 'usd',
+          unitAmountMinorUnits: 2900,
+          priceKind: 'one-time',
+        },
+      ],
+    },
+    { productName: 'gate-empty', displayName: 'Gate Empty', prices: [] },
+    {
+      productName: 'Gate Invalid Name',
+      displayName: 'Gate Invalid',
+      prices: [
+        {
+          priceName: 'gate-invalid-price',
+          currency: 'USD',
+          unitAmountMinorUnits: 19.5,
+          priceKind: 'one-time',
+        },
+      ],
+    },
+  ],
+}
+
+describe('createPaymentsClient', () => {
+  it('builds a client in both scaffold modes and echoes the flag back with the billing scope it decided', async () => {
+    const { paymentsEntry, drizzleClient } = await gateFile.read()
+    const paymentsCatalog = gatePaymentsCatalog(uniqueGatePaymentsCatalogNames('client'))
+
+    const userScoped = paymentsEntry.createPaymentsClient({
+      ...gatePaymentsEnv(),
+      drizzleClient,
+      paymentsCatalog,
+      organizationsEnabled: false,
+    })
+    // Not run through expectValueCarriesNoSecret: the client handle is the one value CONTRACT.md
+    // allows to carry the webhook secret, because carrying it to handleStripeWebhook is its job.
+    createPaymentsClientResultSchema.parse(userScoped)
+    const userMode = expectResultKind(userScoped, 'payments-client-created')
+    expect(userMode.organizationsEnabled).toBe(false)
+    expect(userMode.billingScope).toBe('user')
+    expect(userMode.paymentsClient.billingScope).toBe('user')
+    // The client carries the validated catalog, which is what makes the price lookup a local map
+    // read needing no network at all.
+    expect(
+      sortedGateNames(userMode.paymentsClient.paymentsCatalog.products.map((p) => p.productName)),
+    ).toEqual(sortedGateNames(paymentsCatalog.products.map((product) => product.productName)))
+
+    const orgScoped = paymentsEntry.createPaymentsClient({
+      ...gatePaymentsEnv(),
+      drizzleClient,
+      paymentsCatalog,
+      organizationsEnabled: true,
+    })
+    createPaymentsClientResultSchema.parse(orgScoped)
+    const orgMode = expectResultKind(orgScoped, 'payments-client-created')
+    expect(orgMode.organizationsEnabled).toBe(true)
+    // The flag decides this one value and nothing else. It never decides which tables exist, for the
+    // same reason auth defines the organization tables in both modes: changing the flag later
+    // re-homes existing rows, which is a data migration.
+    expect(orgMode.billingScope).toBe('organization')
+    expect(orgMode.paymentsClient.billingScope).toBe('organization')
+  })
+
+  it('reports every catalog problem in one pass, and reports catalog-has-no-products for an empty catalog', async () => {
+    const { paymentsEntry, drizzleClient } = await gateFile.read()
+
+    const result = paymentsEntry.createPaymentsClient({
+      ...gatePaymentsEnv(),
+      drizzleClient,
+      // Deliberately not parsed through paymentsCatalogSchema: the whole point of this gate is a
+      // catalog an app got wrong, which the schema would refuse to build.
+      paymentsCatalog: catalogWithEveryProblem as unknown as PaymentsCatalog,
+      organizationsEnabled: false,
+    })
+    const failure = expectPaymentsFailure(result, 'payments-catalog-invalid')
+
+    expect(
+      sortedGateNames([...new Set(failure.catalogIssues.map((issue) => issue.catalogIssueKind))]),
+    ).toEqual(
+      sortedGateNames([
+        'duplicate-price-name',
+        'duplicate-product-name',
+        'entry-invalid',
+        'product-has-no-prices',
+      ]),
+    )
+    for (const issue of failure.catalogIssues) {
+      expect(issue.catalogIssueReason.length).toBeGreaterThan(0)
+    }
+    // The reason states the rule that was broken, never the value, matching payments-input-invalid's
+    // discipline. A catalog is app source rather than user input, but the rule is the same one.
+    const everyReason = failure.catalogIssues.map((issue) => issue.catalogIssueReason).join(' ')
+    expect(everyReason).not.toContain('19.5')
+
+    const emptyCatalog = paymentsEntry.createPaymentsClient({
+      ...gatePaymentsEnv(),
+      drizzleClient,
+      paymentsCatalog: { products: [] } as unknown as PaymentsCatalog,
+      organizationsEnabled: false,
+    })
+    const emptyFailure = expectPaymentsFailure(emptyCatalog, 'payments-catalog-invalid')
+    expect(emptyFailure.catalogIssues.map((issue) => issue.catalogIssueKind)).toContain(
+      'catalog-has-no-products',
+    )
+  })
+
+  it('rejects a Stripe API base URL, an environment object and a Drizzle client it cannot use, naming the field', async () => {
+    const { paymentsEntry, drizzleClient } = await gateFile.read()
+    const paymentsCatalog = gatePaymentsCatalog(uniqueGatePaymentsCatalogNames('badinput'))
+
+    const badBaseUrl = paymentsEntry.createPaymentsClient({
+      ...gatePaymentsEnv(),
+      drizzleClient,
+      paymentsCatalog,
+      organizationsEnabled: false,
+      // Absolute http(s) only: it overrides the Stripe API host, port and protocol, and a relative
+      // value would silently point the SDK at nothing.
+      stripeApiBaseUrl: 'api.stripe.test/v1',
+    })
+    expect(expectPaymentsFailure(badBaseUrl, 'payments-input-invalid').invalidFieldName).toBe(
+      'stripe-api-base-url',
+    )
+
+    const badEnv = paymentsEntry.createPaymentsClient({
+      paymentsEnv: { STRIPE_SECRET_KEY: '' } as unknown as PaymentsEnvValues,
+      drizzleClient,
+      paymentsCatalog,
+      organizationsEnabled: false,
+    })
+    expect(expectPaymentsFailure(badEnv, 'payments-input-invalid').invalidFieldName).toBe(
+      'payments-env',
+    )
+
+    const badDrizzleClient = paymentsEntry.createPaymentsClient({
+      ...gatePaymentsEnv(),
+      drizzleClient: undefined as unknown as NodePgDatabase<Record<string, unknown>>,
+      paymentsCatalog,
+      organizationsEnabled: false,
+    })
+    expect(expectPaymentsFailure(badDrizzleClient, 'payments-input-invalid').invalidFieldName).toBe(
+      'drizzle-client',
+    )
+  })
+})

package/src/create-payments-client.ts

@@ -0,0 +1,90 @@
+import Stripe from 'stripe'
+import { validatePaymentsCatalogEntries } from './payments-catalog-validation.ts'
+import { rememberPaymentsClientSecrets } from './payments-client-secrets.ts'
+import {
+  paymentsCatalogInvalidFailure,
+  paymentsInputInvalidFailure,
+} from './payments-failure-results.ts'
+import {
+  paymentsDrizzleClientSchema,
+  paymentsEnvSchemaFragment,
+  paymentsStripeApiBaseUrlSchema,
+  type CreatePaymentsClientOptions,
+  type CreatePaymentsClientResult,
+  type PaymentsClient,
+} from './payments-contract.ts'
+
+/**
+ * Builds the handle every other function here takes. It contacts nothing: constructing a Stripe
+ * instance does no I/O and the Drizzle client is lazy, so an app can call this at module scope in
+ * lib/payments.ts and a wrong key surfaces on the first request rather than at import.
+ *
+ * The catalog is validated here so a malformed one fails at boot rather than at a buyer's checkout,
+ * and organizationsEnabled is a parameter rather than an environment variable, exactly as in
+ * @hearthkit/auth, so it stays a literal in the generated app's source.
+ */
+
+// host, port and protocol are first-class StripeConfig options. They are set from one absolute URL so
+// a caller has one thing to supply, and left unset entirely when none was given, which is every real
+// deployment.
+function stripeApiBaseUrlConfig(stripeApiBaseUrl: string): Stripe.StripeConfig {
+  const baseUrl = new URL(stripeApiBaseUrl)
+  return {
+    host: baseUrl.hostname,
+    protocol: baseUrl.protocol === 'https:' ? 'https' : 'http',
+    ...(baseUrl.port === '' ? {} : { port: baseUrl.port }),
+  }
+}
+
+/** Validates the catalog and builds the Stripe client; synchronous, and opens no connection. */
+export function createPaymentsClient(
+  options: CreatePaymentsClientOptions,
+): CreatePaymentsClientResult {
+  const parsedEnv = paymentsEnvSchemaFragment.safeParse(options.paymentsEnv)
+  if (!parsedEnv.success) {
+    return paymentsInputInvalidFailure('payments-env')
+  }
+
+  if (!paymentsDrizzleClientSchema.safeParse(options.drizzleClient).success) {
+    return paymentsInputInvalidFailure('drizzle-client')
+  }
+
+  let stripeApiConfig: Stripe.StripeConfig = {}
+  if (options.stripeApiBaseUrl !== undefined) {
+    if (!paymentsStripeApiBaseUrlSchema.safeParse(options.stripeApiBaseUrl).success) {
+      return paymentsInputInvalidFailure('stripe-api-base-url')
+    }
+    stripeApiConfig = stripeApiBaseUrlConfig(options.stripeApiBaseUrl)
+  }
+
+  const validatedCatalog = validatePaymentsCatalogEntries(options.paymentsCatalog)
+  if (validatedCatalog.kind === 'catalog-invalid') {
+    return paymentsCatalogInvalidFailure(validatedCatalog.catalogIssues)
+  }
+
+  // No apiVersion and no maxNetworkRetries: the SDK's generated types describe only its own default
+  // version, so pinning a different one would make every Stripe type in this package a lie, and the
+  // default retry count is the behaviour the SDK's own idempotency logic was written against.
+  const stripeClient = new Stripe(String(parsedEnv.data.STRIPE_SECRET_KEY), stripeApiConfig)
+  const billingScope = options.organizationsEnabled ? 'organization' : 'user'
+
+  const paymentsClient: PaymentsClient = {
+    stripeClient,
+    drizzleClient: options.drizzleClient,
+    paymentsCatalog: validatedCatalog.paymentsCatalog,
+    stripeWebhookSecret: parsedEnv.data.STRIPE_WEBHOOK_SECRET,
+    organizationsEnabled: options.organizationsEnabled,
+    billingScope,
+  }
+  rememberPaymentsClientSecrets(paymentsClient, {
+    stripeSecretKey: String(parsedEnv.data.STRIPE_SECRET_KEY),
+    stripeWebhookSecret: String(parsedEnv.data.STRIPE_WEBHOOK_SECRET),
+  })
+
+  return {
+    kind: 'payments-client-created',
+    paymentsClient,
+    organizationsEnabled: options.organizationsEnabled,
+    billingScope,
+  }
+}