@hearthkit/payments 0.1.0

package/src/stripe-catalog-price-sync.ts

@@ -0,0 +1,101 @@
+import type Stripe from 'stripe'
+import {
+  stripeOneTimePriceType,
+  stripeRecurringPriceType,
+  type PaymentsCatalogPrice,
+  type PaymentsPriceSyncAction,
+} from './payments-contract.ts'
+import { readStripeReferenceId } from './stripe-event-payload-fields.ts'
+import { findActiveStripePriceByLookupKey } from './stripe-price-lookup-key.ts'
+
+/**
+ * Pushing one catalog price to Stripe, keyed on the price name, which is also the Stripe lookup key.
+ *
+ * Stripe prices are immutable in amount and currency, so a catalog price whose terms changed cannot be
+ * an update: a new price is created with transfer_lookup_key, which atomically moves the key off the
+ * old one, and the superseded price is archived. Existing subscriptions stay on the old price. That is
+ * Stripe's behaviour and this package does not migrate them.
+ */
+
+/** Interval count Stripe applies when a subscription price does not name one; the catalog default matches it. */
+const defaultRecurringIntervalCount = 1
+
+// Note the underscore in Stripe's one_time, and that Stripe's word for the same idea changes between
+// the price object and the checkout session. Neither spelling is this package's priceKind.
+function stripeRecurringParams(
+  catalogPrice: PaymentsCatalogPrice,
+): Pick<Stripe.PriceCreateParams, 'recurring'> {
+  if (catalogPrice.priceKind !== 'subscription') {
+    return {}
+  }
+  return {
+    recurring: {
+      interval: catalogPrice.recurringInterval,
+      interval_count: catalogPrice.recurringIntervalCount ?? defaultRecurringIntervalCount,
+    },
+  }
+}
+
+function stripePriceMatchesCatalogPrice(
+  stripePrice: Stripe.Price,
+  stripeProductId: string,
+  catalogPrice: PaymentsCatalogPrice,
+): boolean {
+  if (
+    readStripeReferenceId(stripePrice.product) !== stripeProductId ||
+    stripePrice.currency !== String(catalogPrice.currency) ||
+    stripePrice.unit_amount !== catalogPrice.unitAmountMinorUnits
+  ) {
+    return false
+  }
+  if (catalogPrice.priceKind !== 'subscription') {
+    return stripePrice.type === stripeOneTimePriceType && stripePrice.recurring === null
+  }
+  return (
+    stripePrice.type === stripeRecurringPriceType &&
+    stripePrice.recurring?.interval === catalogPrice.recurringInterval &&
+    stripePrice.recurring.interval_count ===
+      (catalogPrice.recurringIntervalCount ?? defaultRecurringIntervalCount)
+  )
+}
+
+/** What sync did to one price, and the Stripe price it now maps to; the id changes whenever the action is replaced. */
+export type StripeCatalogPriceSyncOutcome = {
+  stripePrice: Stripe.Price
+  syncAction: PaymentsPriceSyncAction
+}
+
+/** Creates, reuses or replaces the Stripe price carrying this catalog price's name as its lookup key. */
+export async function syncStripeCatalogPrice(
+  stripeClient: Stripe,
+  stripeProductId: string,
+  catalogPrice: PaymentsCatalogPrice,
+): Promise<StripeCatalogPriceSyncOutcome> {
+  const priceLookupKey = String(catalogPrice.priceName)
+  const existingPrice = await findActiveStripePriceByLookupKey(stripeClient, priceLookupKey)
+
+  if (existingPrice !== undefined) {
+    if (stripePriceMatchesCatalogPrice(existingPrice, stripeProductId, catalogPrice)) {
+      return { stripePrice: existingPrice, syncAction: 'unchanged' }
+    }
+    const replacementPrice = await stripeClient.prices.create({
+      product: stripeProductId,
+      currency: String(catalogPrice.currency),
+      unit_amount: catalogPrice.unitAmountMinorUnits,
+      lookup_key: priceLookupKey,
+      transfer_lookup_key: true,
+      ...stripeRecurringParams(catalogPrice),
+    })
+    await stripeClient.prices.update(existingPrice.id, { active: false })
+    return { stripePrice: replacementPrice, syncAction: 'replaced' }
+  }
+
+  const createdPrice = await stripeClient.prices.create({
+    product: stripeProductId,
+    currency: String(catalogPrice.currency),
+    unit_amount: catalogPrice.unitAmountMinorUnits,
+    lookup_key: priceLookupKey,
+    ...stripeRecurringParams(catalogPrice),
+  })
+  return { stripePrice: createdPrice, syncAction: 'created' }
+}

package/src/stripe-catalog-product-sync.ts

@@ -0,0 +1,75 @@
+import type Stripe from 'stripe'
+import type { PaymentsCatalogProduct } from './payments-contract.ts'
+import { readThrownPaymentsErrorDetails } from './thrown-payments-error-details.ts'
+
+/**
+ * Pushing one catalog product to Stripe. The catalog product name IS the Stripe product id, because
+ * products.create accepts a caller-supplied id, and that is what makes sync idempotent without a
+ * search call: a second run retrieves the same id rather than hunting for a product by name.
+ *
+ * The retrieve-then-create shape is used rather than create-then-catch on purpose. Catching would
+ * mean depending on `resource_already_exists`, an API-level string this repo cannot measure offline
+ * whose near miss `resource_missing` sits in the same generated union. The HTTP status is measurable:
+ * stripe@22.6.1's generateV1Error maps 400 OR 404 to StripeInvalidRequestError, so a missing resource
+ * is not a distinct error class and only `statusCode` says which happened.
+ */
+
+/** HTTP status Stripe answers a retrieve of an id no object carries; read off generateV1Error's own mapping. */
+const stripeNotFoundHttpStatus = 404
+
+function readThrownStripeStatus(thrownValue: unknown): number | undefined {
+  return readThrownPaymentsErrorDetails(thrownValue).stripeErrorStatus
+}
+
+// Only the two fields a buyer sees are kept in step. The product's `active` flag is deliberately left
+// alone: an operator who archived a product in the Stripe dashboard meant it, and a sync that quietly
+// republished it would undo a decision nothing here can see the reason for.
+function stripeProductNeedsUpdate(
+  stripeProduct: Stripe.Product,
+  catalogProduct: PaymentsCatalogProduct,
+): boolean {
+  if (stripeProduct.name !== catalogProduct.displayName) {
+    return true
+  }
+  return (
+    catalogProduct.description !== undefined &&
+    stripeProduct.description !== catalogProduct.description
+  )
+}
+
+/** The Stripe product for one catalog entry, created on a first run and reused on every run after it. */
+export async function ensureStripeCatalogProduct(
+  stripeClient: Stripe,
+  catalogProduct: PaymentsCatalogProduct,
+): Promise<Stripe.Product> {
+  const stripeProductId = String(catalogProduct.productName)
+
+  let existingProduct: Stripe.Product | undefined
+  try {
+    existingProduct = await stripeClient.products.retrieve(stripeProductId)
+  } catch (thrownValue) {
+    if (readThrownStripeStatus(thrownValue) !== stripeNotFoundHttpStatus) {
+      throw thrownValue
+    }
+  }
+
+  if (existingProduct === undefined) {
+    return stripeClient.products.create({
+      id: stripeProductId,
+      name: catalogProduct.displayName,
+      ...(catalogProduct.description === undefined
+        ? {}
+        : { description: catalogProduct.description }),
+    })
+  }
+
+  if (!stripeProductNeedsUpdate(existingProduct, catalogProduct)) {
+    return existingProduct
+  }
+  return stripeClient.products.update(stripeProductId, {
+    name: catalogProduct.displayName,
+    ...(catalogProduct.description === undefined
+      ? {}
+      : { description: catalogProduct.description }),
+  })
+}

package/src/stripe-checkout-session-event.ts

@@ -0,0 +1,204 @@
+import type Stripe from 'stripe'
+import {
+  billingContactEmailSchema,
+  billingScopeSchema,
+  hearthkitBillingReferenceMetadataKey,
+  hearthkitBillingScopeMetadataKey,
+  hearthkitPriceNameMetadataKey,
+  hearthkitQuantityMetadataKey,
+  hearthkitStripePriceIdMetadataKey,
+  paymentsCurrencyCodeSchema,
+  paymentsPriceNameSchema,
+  paymentsQuantitySchema,
+  stripeOneTimeCheckoutMode,
+  stripePriceIdSchema,
+  stripeSubscriptionCheckoutMode,
+  type HandleStripeWebhookResult,
+  type PaymentsClient,
+} from './payments-contract.ts'
+import {
+  readPaymentsCustomerRow,
+  upsertPaymentsCustomerFromWebhook,
+} from './payments-customer-record.ts'
+import { paymentsRequestFailedFailure } from './payments-failure-results.ts'
+import { upsertPaymentsPurchaseRow } from './payments-purchase-record.ts'
+import { readStripeMetadataValue, readStripeReferenceId } from './stripe-event-payload-fields.ts'
+import {
+  paymentsWebhookIgnoredResult,
+  paymentsWebhookProcessedResult,
+  type StripeWebhookDeliveryIdentity,
+} from './stripe-webhook-delivery-results.ts'
+
+/**
+ * What this package does with a `checkout.session.completed` delivery. A subscription-mode session
+ * links the customer; a paid payment-mode session records a purchase; anything else is ignored, which
+ * is a result and not a failure.
+ *
+ * The purchase path reads what was sold from the session's own metadata and never from line_items,
+ * because a delivery does not carry them: Checkout.Session.line_items is declared optional and the SDK
+ * calls it "includable" on a retrieve, and nothing expands it on a delivery. Doing it any other way
+ * would need a retrieve call, which would put every webhook gate behind a live Stripe key.
+ *
+ * It also does not consult the catalog at all, deliberately: a purchase is a historical fact, so
+ * deleting a price from payments-catalog.ts must not make a completed order unrecordable.
+ */
+
+// Stripe metadata values are strings, so the quantity written by createCheckoutSession is read back
+// from a decimal string. A value that is not a positive integer counts as MISSING rather than
+// defaulting to one, because silently billing one unit for an order of five is worse than declining
+// to record it. That is not in tension with the subscription item default: absence has a defined
+// meaning on Stripe's own object and none in a string this package wrote and read back.
+const decimalDigitsPattern = /^\d+$/
+
+function readCheckoutQuantityMetadata(metadata: Stripe.Metadata | null): number | undefined {
+  const rawQuantity = readStripeMetadataValue(metadata, hearthkitQuantityMetadataKey)
+  if (rawQuantity === undefined || !decimalDigitsPattern.test(rawQuantity)) {
+    return undefined
+  }
+  const parsedQuantity = paymentsQuantitySchema.safeParse(Number(rawQuantity))
+  return parsedQuantity.success ? parsedQuantity.data : undefined
+}
+
+// Both fields are read, in that order, and neither alone is enough. customer_email is a PREFILL field
+// and is null on every session created with a customer id, which is every session this package
+// creates after the first; customer_details.email is the one documented as populated after
+// completion, but its own second sentence widens it to a promotional-consent address typed on the
+// Checkout form, which is why it may only ever seed a row that did not exist.
+function readCheckoutContactEmail(session: Stripe.Checkout.Session): string | undefined {
+  const parsed = billingContactEmailSchema.safeParse(
+    session.customer_details?.email ?? session.customer_email ?? undefined,
+  )
+  return parsed.success ? String(parsed.data) : undefined
+}
+
+async function linkCheckoutCustomer(
+  paymentsClient: PaymentsClient,
+  session: Stripe.Checkout.Session,
+  delivery: StripeWebhookDeliveryIdentity,
+): Promise<HandleStripeWebhookResult> {
+  const billingReferenceId = readStripeMetadataValue(
+    session.metadata,
+    hearthkitBillingReferenceMetadataKey,
+  )
+  if (billingReferenceId === undefined) {
+    return paymentsWebhookIgnoredResult(delivery, 'billing-reference-missing')
+  }
+
+  const stripeCustomerId = readStripeReferenceId(session.customer)
+  if (stripeCustomerId === undefined) {
+    return paymentsRequestFailedFailure({
+      paymentsFailureDetail:
+        'a completed subscription checkout carried no customer, so there is nothing to link the billing reference to',
+    })
+  }
+
+  const existingCustomerRow = await readPaymentsCustomerRow(
+    paymentsClient.drizzleClient,
+    billingReferenceId,
+  )
+  // Only the insert branch needs an address, because billingContactEmail is text NOT NULL and nothing
+  // else can supply one for a session this package did not create. On an existing row the address
+  // stays exactly as createCheckoutSession wrote it, and this value never reaches the update clause.
+  const billingContactEmail =
+    readCheckoutContactEmail(session) ?? existingCustomerRow?.billingContactEmail
+  if (billingContactEmail === undefined) {
+    return paymentsRequestFailedFailure({
+      paymentsFailureDetail:
+        'a completed subscription checkout for an unknown billing reference carried no usable email on customer_details or customer_email, so no customer row could be inserted',
+    })
+  }
+
+  const billingScope =
+    billingScopeSchema.safeParse(
+      readStripeMetadataValue(session.metadata, hearthkitBillingScopeMetadataKey),
+    ).data ?? paymentsClient.billingScope
+
+  await upsertPaymentsCustomerFromWebhook(paymentsClient.drizzleClient, {
+    billingReferenceId,
+    billingScope,
+    stripeCustomerId,
+    billingContactEmail,
+    writtenAt: delivery.eventCreatedAt,
+  })
+  return paymentsWebhookProcessedResult(delivery, 'customer-linked')
+}
+
+async function recordCheckoutPurchase(
+  paymentsClient: PaymentsClient,
+  session: Stripe.Checkout.Session,
+  delivery: StripeWebhookDeliveryIdentity,
+): Promise<HandleStripeWebhookResult> {
+  // A purchase is recorded for `paid` and for `no_payment_required`, which is what a fully discounted
+  // order reports; `unpaid` is the third member of that union and the one that records nothing.
+  if (session.payment_status === 'unpaid') {
+    return paymentsWebhookIgnoredResult(delivery, 'checkout-session-unpaid')
+  }
+
+  const billingReferenceId = readStripeMetadataValue(
+    session.metadata,
+    hearthkitBillingReferenceMetadataKey,
+  )
+  if (billingReferenceId === undefined) {
+    return paymentsWebhookIgnoredResult(delivery, 'billing-reference-missing')
+  }
+
+  const priceName = paymentsPriceNameSchema.safeParse(
+    readStripeMetadataValue(session.metadata, hearthkitPriceNameMetadataKey),
+  )
+  const stripePriceId = stripePriceIdSchema.safeParse(
+    readStripeMetadataValue(session.metadata, hearthkitStripePriceIdMetadataKey),
+  )
+  const quantity = readCheckoutQuantityMetadata(session.metadata)
+  if (!priceName.success || !stripePriceId.success || quantity === undefined) {
+    return paymentsWebhookIgnoredResult(delivery, 'checkout-price-metadata-missing')
+  }
+
+  const stripeCustomerId = readStripeReferenceId(session.customer)
+  // currency and amount_total are plain nullable fields rather than expandable ones, so a paid
+  // payment-mode session has both and a null here is not a contract state.
+  const currency = paymentsCurrencyCodeSchema.safeParse(session.currency)
+  const amountTotalMinorUnits = session.amount_total
+  if (
+    stripeCustomerId === undefined ||
+    !currency.success ||
+    typeof amountTotalMinorUnits !== 'number' ||
+    !Number.isInteger(amountTotalMinorUnits) ||
+    amountTotalMinorUnits < 0
+  ) {
+    return paymentsRequestFailedFailure({
+      paymentsFailureDetail:
+        'a completed one-time checkout carried no customer, no currency or no amount total, none of which is a state this package models',
+    })
+  }
+
+  await upsertPaymentsPurchaseRow(paymentsClient.drizzleClient, {
+    billingReferenceId,
+    stripeCustomerId,
+    stripeCheckoutSessionId: session.id,
+    stripePaymentIntentId: readStripeReferenceId(session.payment_intent) ?? null,
+    priceName: String(priceName.data),
+    stripePriceId: String(stripePriceId.data),
+    currency: String(currency.data),
+    amountTotalMinorUnits,
+    quantity,
+    // The event's own `created`, seconds since the epoch, not the moment this row was written.
+    purchasedAt: delivery.eventCreatedAt,
+    writtenAt: new Date(),
+  })
+  return paymentsWebhookProcessedResult(delivery, 'purchase-recorded')
+}
+
+/** Routes one completed Checkout Session by its mode; a setup-mode session came from somewhere else and is ignored. */
+export async function recordStripeCheckoutSessionDelivery(
+  paymentsClient: PaymentsClient,
+  session: Stripe.Checkout.Session,
+  delivery: StripeWebhookDeliveryIdentity,
+): Promise<HandleStripeWebhookResult> {
+  if (session.mode === stripeSubscriptionCheckoutMode) {
+    return linkCheckoutCustomer(paymentsClient, session, delivery)
+  }
+  if (session.mode === stripeOneTimeCheckoutMode) {
+    return recordCheckoutPurchase(paymentsClient, session, delivery)
+  }
+  return paymentsWebhookIgnoredResult(delivery, 'checkout-mode-not-handled')
+}

package/src/stripe-event-payload-fields.ts

@@ -0,0 +1,39 @@
+/**
+ * The three readers every webhook path needs, written once because each one has an obvious spelling
+ * beside it that answers wrongly rather than throwing.
+ *
+ * An expandable Stripe field is a string id in a delivery and an object only after a retrieve, and
+ * the SDK types it as the union of both; reading `.id` off a string yields undefined and reading a
+ * string off an object yields "[object Object]". Every Stripe timestamp is seconds since the epoch,
+ * so `new Date(value)` without the multiplication lands in January 1970 and nothing complains.
+ */
+
+/** One metadata value, or nothing when the key is absent or empty; Stripe metadata values are always strings. */
+export function readStripeMetadataValue(
+  metadata: Record<string, string> | null | undefined,
+  metadataKey: string,
+): string | undefined {
+  const value = metadata?.[metadataKey]
+  return typeof value === 'string' && value.length > 0 ? value : undefined
+}
+
+/** The id of an expandable Stripe reference, whether the payload carried the string or the whole object. */
+export function readStripeReferenceId(
+  reference: string | { id?: string } | null | undefined,
+): string | undefined {
+  if (typeof reference === 'string') {
+    return reference.length > 0 ? reference : undefined
+  }
+  if (typeof reference === 'object' && reference !== null && typeof reference.id === 'string') {
+    return reference.id.length > 0 ? reference.id : undefined
+  }
+  return undefined
+}
+
+/** A Stripe timestamp as a Date; Stripe counts seconds since the epoch and JavaScript counts milliseconds. */
+export function readStripeSecondsAsDate(secondsSinceEpoch: number | null | undefined): Date | null {
+  if (typeof secondsSinceEpoch !== 'number' || !Number.isFinite(secondsSinceEpoch)) {
+    return null
+  }
+  return new Date(secondsSinceEpoch * 1000)
+}

package/src/stripe-price-lookup-key.ts

@@ -0,0 +1,26 @@
+import type Stripe from 'stripe'
+
+/**
+ * Resolving a catalog price name against Stripe, through the lookup key syncPaymentsCatalog set it
+ * to. An unknown lookup key comes back as an EMPTY LIST — a 200 response with no data rather than an
+ * error — which is why the absent-from-stripe half of payments-price-not-found never depends on an
+ * API-level error code. `resource_missing` sits one union entry away from `resource_already_exists`,
+ * and neither is a string this repo can measure offline.
+ */
+
+// PriceListParams accepts up to ten lookup_keys, and a lookup key is unique among ACTIVE prices in an
+// account, so one key with active: true can match at most one price.
+const activePriceListLimit = 1
+
+/** The active Stripe price carrying this lookup key, or nothing when sync has never run for it. */
+export async function findActiveStripePriceByLookupKey(
+  stripeClient: Stripe,
+  priceLookupKey: string,
+): Promise<Stripe.Price | undefined> {
+  const listedPrices = await stripeClient.prices.list({
+    lookup_keys: [priceLookupKey],
+    active: true,
+    limit: activePriceListLimit,
+  })
+  return listedPrices.data[0]
+}

package/src/stripe-subscription-event.ts

@@ -0,0 +1,112 @@
+import type Stripe from 'stripe'
+import {
+  hearthkitBillingReferenceMetadataKey,
+  type HandleStripeWebhookResult,
+  type PaymentsCatalog,
+  type PaymentsClient,
+} from './payments-contract.ts'
+import { paymentsRequestFailedFailure } from './payments-failure-results.ts'
+import { upsertPaymentsSubscriptionRow } from './payments-subscription-record.ts'
+import {
+  readStripeMetadataValue,
+  readStripeReferenceId,
+  readStripeSecondsAsDate,
+} from './stripe-event-payload-fields.ts'
+import {
+  paymentsWebhookIgnoredResult,
+  paymentsWebhookProcessedResult,
+  type StripeWebhookDeliveryIdentity,
+} from './stripe-webhook-delivery-results.ts'
+
+/**
+ * What this package does with a `customer.subscription.*` delivery: created, updated and deleted all
+ * upsert the same row on the Stripe subscription id and all report subscription-upserted.
+ *
+ * Unlike the checkout path this one must consult the catalog, because priceName is resolved from the
+ * price's lookup_key and there is no metadata to fall back on. That resolution is deliberate: 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. The lookup_key cannot go stale.
+ *
+ * It needs no API call. SubscriptionItem.price is typed Price rather than `string | Price`, so it is
+ * always the full object in a delivery and never an id, which is what makes this path offline rather
+ * than merely usually offline.
+ */
+
+function catalogPriceNames(paymentsCatalog: PaymentsCatalog): Set<string> {
+  const priceNames = new Set<string>()
+  for (const catalogProduct of paymentsCatalog.products) {
+    for (const catalogPrice of catalogProduct.prices) {
+      priceNames.add(String(catalogPrice.priceName))
+    }
+  }
+  return priceNames
+}
+
+// The first item whose price.lookup_key names a catalog price, not simply items.data[0]: a
+// subscription can carry an item this catalog knows nothing about, and reading position zero would
+// then store somebody else's price against our reference.
+function findCatalogSubscriptionItem(
+  subscription: Stripe.Subscription,
+  paymentsCatalog: PaymentsCatalog,
+): Stripe.SubscriptionItem | undefined {
+  const knownPriceNames = catalogPriceNames(paymentsCatalog)
+  return subscription.items.data.find((subscriptionItem) => {
+    const lookupKey = subscriptionItem.price.lookup_key
+    return typeof lookupKey === 'string' && knownPriceNames.has(lookupKey)
+  })
+}
+
+/** Records what Stripe last said about a subscription; a delivery with no reference or no catalog price is ignored. */
+export async function recordStripeSubscriptionDelivery(
+  paymentsClient: PaymentsClient,
+  subscription: Stripe.Subscription,
+  delivery: StripeWebhookDeliveryIdentity,
+): Promise<HandleStripeWebhookResult> {
+  // A subscription created by hand in the Stripe dashboard carries no hearthkit metadata at all, and
+  // inventing a reference for it would attach someone else's money to a hearthkit account.
+  const billingReferenceId = readStripeMetadataValue(
+    subscription.metadata,
+    hearthkitBillingReferenceMetadataKey,
+  )
+  if (billingReferenceId === undefined) {
+    return paymentsWebhookIgnoredResult(delivery, 'billing-reference-missing')
+  }
+
+  const catalogItem = findCatalogSubscriptionItem(subscription, paymentsClient.paymentsCatalog)
+  if (catalogItem === undefined) {
+    return paymentsWebhookIgnoredResult(delivery, 'subscription-price-not-in-catalog')
+  }
+
+  const stripeCustomerId = readStripeReferenceId(subscription.customer)
+  if (stripeCustomerId === undefined) {
+    return paymentsRequestFailedFailure({
+      paymentsFailureDetail:
+        'a subscription delivery carried no customer, so the row would name nobody Stripe bills',
+    })
+  }
+
+  await upsertPaymentsSubscriptionRow(paymentsClient.drizzleClient, {
+    billingReferenceId,
+    stripeCustomerId,
+    stripeSubscriptionId: subscription.id,
+    priceName: String(catalogItem.price.lookup_key),
+    stripePriceId: catalogItem.price.id,
+    status: subscription.status,
+    // SubscriptionItem.quantity is typed optional and Stripe omits it for prices with no explicit
+    // quantity, metered ones among them; absence there means one unit of the thing, which is a
+    // defined meaning and therefore a default this package is allowed to apply.
+    quantity: catalogItem.quantity ?? 1,
+    // Both period dates come from the ITEM. stripe@22.6.1's Subscription object has no
+    // current_period_start or current_period_end at all, so reaching for one finds nothing.
+    currentPeriodStart: readStripeSecondsAsDate(catalogItem.current_period_start),
+    currentPeriodEnd: readStripeSecondsAsDate(catalogItem.current_period_end),
+    // These five are subscription-level fields that really do exist, unlike the period pair.
+    cancelAtPeriodEnd: subscription.cancel_at_period_end,
+    canceledAt: readStripeSecondsAsDate(subscription.canceled_at),
+    endedAt: readStripeSecondsAsDate(subscription.ended_at),
+    trialStart: readStripeSecondsAsDate(subscription.trial_start),
+    trialEnd: readStripeSecondsAsDate(subscription.trial_end),
+    writtenAt: new Date(),
+  })
+  return paymentsWebhookProcessedResult(delivery, 'subscription-upserted')
+}

package/src/stripe-webhook-delivery-results.ts

@@ -0,0 +1,46 @@
+import type {
+  HandleStripeWebhookResult,
+  PaymentsWebhookIgnoredReason,
+  PaymentsWebhookOutcome,
+  StripeEventId,
+} from './payments-contract.ts'
+
+/**
+ * The two answers a verified delivery can end in, built in one place so both carry the event id and
+ * the event type. An ignored delivery is a RESULT and not a failure: Stripe sends every event type an
+ * endpoint is subscribed to and most of them are none of this package's business, so modelling that
+ * as an error would make a webhook route log a stack trace on an ordinary Tuesday.
+ */
+
+/** What a verified delivery is, before this package decides what to do with it; the event's own clock, not ours. */
+export type StripeWebhookDeliveryIdentity = {
+  stripeEventId: StripeEventId
+  stripeEventType: string
+  eventCreatedAt: Date
+}
+
+/** Result when the delivery was acted on; a replay writes the same row and moves no count. */
+export function paymentsWebhookProcessedResult(
+  delivery: StripeWebhookDeliveryIdentity,
+  webhookOutcome: PaymentsWebhookOutcome,
+): HandleStripeWebhookResult {
+  return {
+    kind: 'payments-webhook-processed',
+    stripeEventId: delivery.stripeEventId,
+    stripeEventType: delivery.stripeEventType,
+    webhookOutcome,
+  }
+}
+
+/** Result when the delivery was verified but not acted on; every reason here is a normal state, not a mistake by anyone. */
+export function paymentsWebhookIgnoredResult(
+  delivery: StripeWebhookDeliveryIdentity,
+  ignoredReason: PaymentsWebhookIgnoredReason,
+): HandleStripeWebhookResult {
+  return {
+    kind: 'payments-webhook-ignored',
+    stripeEventId: delivery.stripeEventId,
+    stripeEventType: delivery.stripeEventType,
+    ignoredReason,
+  }
+}