@hearthkit/payments 0.1.0

package/src/handle-stripe-webhook.ts

@@ -0,0 +1,133 @@
+import type Stripe from 'stripe'
+import { redactPaymentsClientSecrets } from './payments-client-secrets.ts'
+import {
+  paymentsClientSchema,
+  paymentsRequestHeadersSchema,
+  stripeEventIdSchema,
+  stripeSignatureHeaderName,
+  type HandleStripeWebhookOptions,
+  type HandleStripeWebhookResult,
+  type PaymentsClient,
+} from './payments-contract.ts'
+import {
+  paymentsInputInvalidFailure,
+  paymentsRequestFailedFailure,
+  paymentsWebhookSignatureInvalidFailure,
+} from './payments-failure-results.ts'
+import { recordStripeCheckoutSessionDelivery } from './stripe-checkout-session-event.ts'
+import { recordStripeSubscriptionDelivery } from './stripe-subscription-event.ts'
+import {
+  paymentsWebhookIgnoredResult,
+  type StripeWebhookDeliveryIdentity,
+} from './stripe-webhook-delivery-results.ts'
+import {
+  readThrownPaymentsErrorDetails,
+  stripeSignatureVerificationErrorTypeName,
+} from './thrown-payments-error-details.ts'
+import { thrownPaymentsErrorToFailure } from './thrown-payments-error-failure.ts'
+
+/**
+ * Verifies a delivery and then records what Stripe reported. It contacts Stripe over the network
+ * never: verification is a local HMAC, and every handled event carries everything the write needs on
+ * the payload itself, so this whole surface runs with no Stripe key.
+ *
+ * rawRequestBody must be the exact bytes Stripe sent. In a Next.js route handler that means
+ * `await request.text()`, never `await request.json()`, and never a body some framework middleware
+ * has already parsed and re-serialised — re-serialising changes the bytes the HMAC covers and
+ * surfaces as a signature mismatch rather than as the body-handling mistake it is.
+ */
+
+function verifyStripeWebhookDelivery(
+  paymentsClient: PaymentsClient,
+  rawRequestBody: string,
+  signatureHeader: string,
+): { kind: 'stripe-event-verified'; stripeEvent: Stripe.Event } | HandleStripeWebhookResult {
+  try {
+    return {
+      kind: 'stripe-event-verified',
+      stripeEvent: paymentsClient.stripeClient.webhooks.constructEvent(
+        rawRequestBody,
+        signatureHeader,
+        String(paymentsClient.stripeWebhookSecret),
+      ),
+    }
+  } catch (thrownValue) {
+    const details = readThrownPaymentsErrorDetails(thrownValue)
+    if (details.stripeErrorTypeName !== stripeSignatureVerificationErrorTypeName) {
+      return thrownPaymentsErrorToFailure(thrownValue, paymentsClient)
+    }
+    // The SDK error also carries `.payload`, which is the raw webhook body and therefore whatever
+    // customer data the event held. Only the message is ever quoted.
+    return paymentsWebhookSignatureInvalidFailure(
+      'signature-verification-failed',
+      redactPaymentsClientSecrets(details.paymentsFailureDetail, paymentsClient),
+    )
+  }
+}
+
+async function routeStripeWebhookDelivery(
+  paymentsClient: PaymentsClient,
+  stripeEvent: Stripe.Event,
+  delivery: StripeWebhookDeliveryIdentity,
+): Promise<HandleStripeWebhookResult> {
+  switch (stripeEvent.type) {
+    case 'checkout.session.completed':
+      return recordStripeCheckoutSessionDelivery(paymentsClient, stripeEvent.data.object, delivery)
+    case 'customer.subscription.created':
+    case 'customer.subscription.updated':
+    case 'customer.subscription.deleted':
+      return recordStripeSubscriptionDelivery(paymentsClient, stripeEvent.data.object, delivery)
+    default:
+      // Stripe delivers every event type an endpoint is subscribed to and most of them are none of
+      // this package's business, so this is a result rather than an error.
+      return paymentsWebhookIgnoredResult(delivery, 'event-type-not-handled')
+  }
+}
+
+/** Verifies the stripe-signature header locally and records the delivery; it never calls Stripe and never throws. */
+export async function handleStripeWebhook(
+  options: HandleStripeWebhookOptions,
+): Promise<HandleStripeWebhookResult> {
+  if (!paymentsClientSchema.safeParse(options.paymentsClient).success) {
+    return paymentsInputInvalidFailure('drizzle-client')
+  }
+  if (typeof options.rawRequestBody !== 'string' || options.rawRequestBody.length === 0) {
+    return paymentsInputInvalidFailure('raw-request-body')
+  }
+  if (!paymentsRequestHeadersSchema.safeParse(options.requestHeaders).success) {
+    return paymentsInputInvalidFailure('request-headers')
+  }
+
+  const signatureHeader = options.requestHeaders.get(stripeSignatureHeaderName)
+  if (signatureHeader === null || signatureHeader.length === 0) {
+    return paymentsWebhookSignatureInvalidFailure('signature-header-missing')
+  }
+
+  const verified = verifyStripeWebhookDelivery(
+    options.paymentsClient,
+    options.rawRequestBody,
+    signatureHeader,
+  )
+  if (verified.kind !== 'stripe-event-verified') {
+    return verified
+  }
+
+  const stripeEventId = stripeEventIdSchema.safeParse(verified.stripeEvent.id)
+  if (!stripeEventId.success) {
+    return paymentsRequestFailedFailure({
+      paymentsFailureDetail:
+        'a verified Stripe delivery carried no event id, so nothing can be traced back to it',
+    })
+  }
+  const delivery: StripeWebhookDeliveryIdentity = {
+    stripeEventId: stripeEventId.data,
+    stripeEventType: verified.stripeEvent.type,
+    eventCreatedAt: new Date(verified.stripeEvent.created * 1000),
+  }
+
+  try {
+    return await routeStripeWebhookDelivery(options.paymentsClient, verified.stripeEvent, delivery)
+  } catch (thrownValue) {
+    return thrownPaymentsErrorToFailure(thrownValue, options.paymentsClient)
+  }
+}

package/src/hearthkit-payments-drizzle-schema.test.ts

@@ -0,0 +1,214 @@
+import { getTableConfig, type PgTable } from 'drizzle-orm/pg-core'
+import { describe, expect, it } from 'vitest'
+import { sortedGateNames } from '../test-fixtures/payments-gate-expectations.ts'
+import { loadHearthkitPaymentsEntry } from '../test-fixtures/hearthkit-payments-entry.ts'
+import { hearthkitPaymentsTableNames } from './payments-contract.ts'
+
+/**
+ * The conformance gate for the three tables CONTRACT.md specifies, and it touches no database at all.
+ * Whether those tables were ever created is verifyPaymentsTablesExist's question, not this one: a
+ * schema that conforms perfectly and was never migrated passes here and fails there, which is the
+ * correct division.
+ *
+ * Assertions are on the Drizzle table object's PROPERTY names, not on SQL column names. The app runs
+ * drizzle-kit over this schema and CONTRACT.md leaves the SQL spelling unconstrained, so a package
+ * that names its column `billing_reference_id` underneath is conforming. What must match is the
+ * property a caller reads, plus each column's nullability and uniqueness, which are the constraints
+ * the contract does fix — the unique keys especially, because they are what makes a replayed webhook
+ * delivery an upsert rather than a duplicate row.
+ */
+
+type GateExpectedColumn = {
+  propertyName: string
+  sqlTypeFamily: string
+  notNull: boolean
+  primary?: boolean
+  unique?: boolean
+}
+
+const timestampColumn = (propertyName: string, notNull: boolean): GateExpectedColumn => ({
+  propertyName,
+  sqlTypeFamily: 'timestamp',
+  notNull,
+})
+
+const expectedPaymentsColumns: Record<string, readonly GateExpectedColumn[]> = {
+  payments_customer: [
+    { propertyName: 'id', sqlTypeFamily: 'text', notNull: true, primary: true },
+    {
+      propertyName: 'billingReferenceId',
+      sqlTypeFamily: 'text',
+      notNull: true,
+      // One Stripe customer per reference. Without it, two concurrent checkouts for one user each
+      // create a Stripe customer and the second row silently orphans the first customer's money.
+      unique: true,
+    },
+    { propertyName: 'billingScope', sqlTypeFamily: 'text', notNull: true },
+    { propertyName: 'stripeCustomerId', sqlTypeFamily: 'text', notNull: true, unique: true },
+    { propertyName: 'billingContactEmail', sqlTypeFamily: 'text', notNull: true },
+    timestampColumn('createdAt', true),
+    timestampColumn('updatedAt', true),
+  ],
+  payments_subscription: [
+    { propertyName: 'id', sqlTypeFamily: 'text', notNull: true, primary: true },
+    { propertyName: 'billingReferenceId', sqlTypeFamily: 'text', notNull: true },
+    { propertyName: 'stripeCustomerId', sqlTypeFamily: 'text', notNull: true },
+    // The idempotency key of the whole subscription path: a replayed customer.subscription.* event
+    // writes the same values to the same row and the row count does not move.
+    { propertyName: 'stripeSubscriptionId', sqlTypeFamily: 'text', notNull: true, unique: true },
+    { propertyName: 'priceName', sqlTypeFamily: 'text', notNull: true },
+    { propertyName: 'stripePriceId', sqlTypeFamily: 'text', notNull: true },
+    { propertyName: 'status', sqlTypeFamily: 'text', notNull: true },
+    { propertyName: 'quantity', sqlTypeFamily: 'integer', notNull: true },
+    // Nullable because they come from the subscription ITEM, and a subscription can be reported
+    // before an item exists. stripe@22.6.1's Subscription has no current_period_* field at all.
+    timestampColumn('currentPeriodStart', false),
+    timestampColumn('currentPeriodEnd', false),
+    { propertyName: 'cancelAtPeriodEnd', sqlTypeFamily: 'boolean', notNull: true },
+    timestampColumn('canceledAt', false),
+    timestampColumn('endedAt', false),
+    timestampColumn('trialStart', false),
+    timestampColumn('trialEnd', false),
+    timestampColumn('createdAt', true),
+    timestampColumn('updatedAt', true),
+  ],
+  payments_purchase: [
+    { propertyName: 'id', sqlTypeFamily: 'text', notNull: true, primary: true },
+    { propertyName: 'billingReferenceId', sqlTypeFamily: 'text', notNull: true },
+    { propertyName: 'stripeCustomerId', sqlTypeFamily: 'text', notNull: true },
+    // The idempotency key of the purchase path, for the same reason.
+    {
+      propertyName: 'stripeCheckoutSessionId',
+      sqlTypeFamily: 'text',
+      notNull: true,
+      unique: true,
+    },
+    // Nullable: a fully discounted order has no payment intent at all.
+    { propertyName: 'stripePaymentIntentId', sqlTypeFamily: 'text', notNull: false },
+    { propertyName: 'priceName', sqlTypeFamily: 'text', notNull: true },
+    { propertyName: 'stripePriceId', sqlTypeFamily: 'text', notNull: true },
+    { propertyName: 'currency', sqlTypeFamily: 'text', notNull: true },
+    { propertyName: 'amountTotalMinorUnits', sqlTypeFamily: 'integer', notNull: true },
+    { propertyName: 'quantity', sqlTypeFamily: 'integer', notNull: true },
+    timestampColumn('purchasedAt', true),
+    timestampColumn('createdAt', true),
+    timestampColumn('updatedAt', true),
+  ],
+}
+
+type GateDrizzleColumn = {
+  name: string
+  notNull: boolean
+  primary: boolean
+  isUnique: boolean
+  getSQLType: () => string
+}
+
+/** Every SQL column name the table declares unique, whether on the column or as a table constraint. */
+function uniqueSqlColumnNames(paymentsTable: unknown): Set<string> {
+  const tableConfig = getTableConfig(paymentsTable as PgTable)
+  const uniqueNames = new Set<string>()
+  for (const column of tableConfig.columns) {
+    if (column.isUnique) {
+      uniqueNames.add(column.name)
+    }
+  }
+  for (const uniqueConstraint of tableConfig.uniqueConstraints) {
+    // Destructured rather than indexed after a length check, because a length check narrows nothing
+    // for the type checker. The condition is the same one: exactly one column, so a composite unique
+    // constraint is still not counted — a two-column key would not make either column unique.
+    const [onlyColumn, ...furtherColumns] = uniqueConstraint.columns
+    if (onlyColumn !== undefined && furtherColumns.length === 0) {
+      uniqueNames.add(onlyColumn.name)
+    }
+  }
+  return uniqueNames
+}
+
+describe('hearthkitPaymentsDrizzleSchema', () => {
+  it('always defines all three tables under keys equal to their SQL table names, in both user-scoped and org-scoped mode', async () => {
+    const { hearthkitPaymentsDrizzleSchema } = await loadHearthkitPaymentsEntry()
+    const shippedSchema = hearthkitPaymentsDrizzleSchema as Record<string, unknown>
+
+    // All three exist in every project whatever organizationsEnabled is, because the flag decides
+    // the billingScope written on a customer row and never which tables exist; changing the tables
+    // with the flag later would be a data migration.
+    expect(sortedGateNames(Object.keys(shippedSchema))).toEqual(
+      sortedGateNames(hearthkitPaymentsTableNames),
+    )
+
+    // verifyPaymentsTablesExist looks these same names up in information_schema.tables, so the SQL
+    // table name has to equal the schema key even though the column names underneath are free.
+    const sqlTableNames = Object.values(shippedSchema).map(
+      (paymentsTable) => getTableConfig(paymentsTable as PgTable).name,
+    )
+    expect(sortedGateNames(sqlTableNames)).toEqual(sortedGateNames(hearthkitPaymentsTableNames))
+  })
+
+  it('carries every column CONTRACT.md lists, with the stated nullability and the three unique keys idempotency depends on', async () => {
+    const { hearthkitPaymentsDrizzleSchema } = await loadHearthkitPaymentsEntry()
+    const shippedSchema = hearthkitPaymentsDrizzleSchema as Record<
+      string,
+      Record<string, GateDrizzleColumn>
+    >
+
+    const missingColumns: string[] = []
+    const wrongTypeColumns: string[] = []
+    const wrongNullabilityColumns: string[] = []
+    const missingUniqueColumns: string[] = []
+    const missingPrimaryKeyColumns: string[] = []
+
+    for (const [paymentsTableName, expectedColumns] of Object.entries(expectedPaymentsColumns)) {
+      const shippedTable = shippedSchema[paymentsTableName]
+      if (typeof shippedTable !== 'object' || shippedTable === null) {
+        missingColumns.push(`${paymentsTableName} (whole table)`)
+        continue
+      }
+      const uniqueNames = uniqueSqlColumnNames(shippedTable)
+
+      for (const expectedColumn of expectedColumns) {
+        const column = shippedTable[expectedColumn.propertyName]
+        if (typeof column !== 'object' || column === null) {
+          missingColumns.push(`${paymentsTableName}.${expectedColumn.propertyName}`)
+          continue
+        }
+        if (!column.getSQLType().startsWith(expectedColumn.sqlTypeFamily)) {
+          wrongTypeColumns.push(
+            `${paymentsTableName}.${expectedColumn.propertyName} is ${column.getSQLType()}, expected ${expectedColumn.sqlTypeFamily}`,
+          )
+        }
+        // A primary key column is not-null by definition, and Drizzle reports notNull false on some
+        // primary key declarations, so nullability is only asserted where the contract has a choice.
+        if (expectedColumn.primary !== true && column.notNull !== expectedColumn.notNull) {
+          wrongNullabilityColumns.push(
+            `${paymentsTableName}.${expectedColumn.propertyName} notNull is ${column.notNull}, expected ${expectedColumn.notNull}`,
+          )
+        }
+        if (expectedColumn.primary === true && !column.primary) {
+          missingPrimaryKeyColumns.push(`${paymentsTableName}.${expectedColumn.propertyName}`)
+        }
+        if (expectedColumn.unique === true && !uniqueNames.has(column.name)) {
+          missingUniqueColumns.push(`${paymentsTableName}.${expectedColumn.propertyName}`)
+        }
+      }
+    }
+
+    expect(
+      missingColumns,
+      'CONTRACT.md lists these columns and the shipped schema has none',
+    ).toEqual([])
+    expect(
+      wrongTypeColumns,
+      'these columns are a different type family than CONTRACT.md states',
+    ).toEqual([])
+    expect(
+      wrongNullabilityColumns,
+      'CONTRACT.md fixes each column as nullable or not, and these disagree',
+    ).toEqual([])
+    expect(missingPrimaryKeyColumns, 'each table needs its id as the primary key').toEqual([])
+    expect(
+      missingUniqueColumns,
+      'idempotency here is structural rather than a bookkeeping table, so these unique keys are what stops a replayed delivery writing a second row',
+    ).toEqual([])
+  })
+})

package/src/hearthkit-payments-drizzle-schema.ts

@@ -0,0 +1,80 @@
+import { boolean, integer, pgTable, text, timestamp } from 'drizzle-orm/pg-core'
+import type { HearthkitPaymentsDrizzleSchema } from './payments-contract.ts'
+
+/**
+ * The three payments tables, defined once for every project. The organizations scaffold flag decides
+ * the `billingScope` written on a customer row and never which tables exist, for the same reason
+ * `@hearthkit/auth` defines its organization tables in both modes: changing the flag later re-homes
+ * existing rows, which is a data migration rather than a schema change.
+ *
+ * Every SQL table name equals the Drizzle schema key, because `verifyPaymentsTablesExist` looks these
+ * same strings up in `information_schema.tables`. The SQL column names underneath are Drizzle's
+ * business and are left equal to the property keys, which is the spelling a caller reads.
+ *
+ * There are deliberately no foreign keys to the auth tables. `billingReferenceId` points at `user` in
+ * user-scoped mode and at `organization` in org-scoped mode, so one foreign key cannot express it and
+ * adding one would couple this package's migrations to auth's table objects.
+ */
+
+/** The join between a hearthkit billing reference and a Stripe customer; one row per reference, and nothing else. */
+export const paymentsCustomerTable = pgTable('payments_customer', {
+  id: text().primaryKey(),
+  billingReferenceId: text().notNull().unique(),
+  billingScope: text().notNull(),
+  stripeCustomerId: text().notNull().unique(),
+  billingContactEmail: text().notNull(),
+  createdAt: timestamp().notNull(),
+  updatedAt: timestamp().notNull(),
+})
+
+// stripeSubscriptionId is unique because idempotency here is structural rather than a bookkeeping
+// table: a replayed customer.subscription.* delivery writes the same values to the same row and the
+// row count does not move. currentPeriodStart and currentPeriodEnd are nullable because they come
+// from the subscription ITEM — stripe@22.6.1's Subscription object carries neither — and a
+// subscription can be reported before an item that names a catalog price exists.
+/** What Stripe last said about one subscription; `status` is a plain text column so a status Stripe adds later cannot break a write. */
+export const paymentsSubscriptionTable = pgTable('payments_subscription', {
+  id: text().primaryKey(),
+  billingReferenceId: text().notNull(),
+  stripeCustomerId: text().notNull(),
+  stripeSubscriptionId: text().notNull().unique(),
+  priceName: text().notNull(),
+  stripePriceId: text().notNull(),
+  status: text().notNull(),
+  quantity: integer().notNull(),
+  currentPeriodStart: timestamp(),
+  currentPeriodEnd: timestamp(),
+  cancelAtPeriodEnd: boolean().notNull().default(false),
+  canceledAt: timestamp(),
+  endedAt: timestamp(),
+  trialStart: timestamp(),
+  trialEnd: timestamp(),
+  createdAt: timestamp().notNull(),
+  updatedAt: timestamp().notNull(),
+})
+
+// stripeCheckoutSessionId is the idempotency key of the purchase path, for the same reason.
+// stripePaymentIntentId is nullable because a fully discounted order has no payment intent at all.
+/** One completed one-time checkout, recorded from the session's own fields and the metadata this package wrote. */
+export const paymentsPurchaseTable = pgTable('payments_purchase', {
+  id: text().primaryKey(),
+  billingReferenceId: text().notNull(),
+  stripeCustomerId: text().notNull(),
+  stripeCheckoutSessionId: text().notNull().unique(),
+  stripePaymentIntentId: text(),
+  priceName: text().notNull(),
+  stripePriceId: text().notNull(),
+  currency: text().notNull(),
+  amountTotalMinorUnits: integer().notNull(),
+  quantity: integer().notNull(),
+  purchasedAt: timestamp().notNull(),
+  createdAt: timestamp().notNull(),
+  updatedAt: timestamp().notNull(),
+})
+
+/** The Drizzle table map this package ships; spread it into the app's schema so one drizzle-kit run covers every table. */
+export const hearthkitPaymentsDrizzleSchema = {
+  payments_customer: paymentsCustomerTable,
+  payments_subscription: paymentsSubscriptionTable,
+  payments_purchase: paymentsPurchaseTable,
+} satisfies HearthkitPaymentsDrizzleSchema