@owlmeans/server-payment 0.1.18-rc.2 → 0.1.18-rc.21

package/src/model.ts

@@ -1,37 +1,256 @@
 import type { JSONSchemaType } from 'ajv'
-import { PermissionSetSchema } from '@owlmeans/auth'
-import { LimitConfigSchema } from '@owlmeans/payment'
-import type { FingerprintRecord, PaygateCustomerRecord, PaymentSubscriptionRecord } from './types.js'
+import { DateSchema } from '@owlmeans/auth'
+import {
+  CancellationKindSchema, CheckoutPricingModeSchema, ConsentKindSchema, ConsumerRegionSchema,
+  DeclarationChannelSchema, DeclarationKindSchema, PurchaseKindSchema, SubscriptionStatusSchema,
+} from '@owlmeans/payment'
+import type {
+  BillingProfileRecord, ConsumerConsentRecord, ConsumerDeclarationRecord, ConsumerEventRecord, FingerprintRecord,
+  PaygateCustomerRecord, PaymentFulfillmentRecord, PaymentSubscriptionRecord, PaymentUsageCounterRecord,
+  PaymentUsageRecord, PaymentWebhookRecord, PurchaseRecord,
+} from './types.js'
+
+/**
+ * Record schemas. Every stored property is declared: the resource coerces a write through its
+ * schema, and a property the schema does not know is written as a string. Dates follow the record
+ * convention (`DateSchema`). None of these records declares an ObjectId reference — `entityId`
+ * is an organization key and every other id is the paygate's.
+ */
+
+const str = { type: 'string' } as const
+const optStr = { type: 'string', nullable: true } as const
+const num = { type: 'number' } as const
+const optNum = { type: 'number', nullable: true } as const
+const optBool = { type: 'boolean', nullable: true } as const
+const date = DateSchema
+const optDate = { ...DateSchema, nullable: true }
+const id = { type: 'string', nullable: true } as const
 
 export const PaygateCustomerSchema = {
   type: 'object',
   properties: {
-    id: { type: 'string', nullable: true }, paygate: { type: 'string' }, externalId: { type: 'string' },
-    entityId: { type: 'string', nullable: true }, profileId: { type: 'string', nullable: true },
-    email: { type: 'string', nullable: true }, name: { type: 'string', nullable: true },
-    taxId: { type: 'string', nullable: true },
+    id, paygate: str, externalId: str, entityId: optStr, profileId: optStr, email: optStr, name: optStr,
+    taxId: optStr, country: optStr, currency: optStr, deletedAt: optDate,
   },
-  required: ['paygate', 'externalId'], additionalProperties: true,
+  required: ['paygate', 'externalId'],
+  additionalProperties: false,
 } as unknown as JSONSchemaType<PaygateCustomerRecord>
 
 export const PaymentSubscriptionSchema = {
   type: 'object',
   properties: {
-    id: { type: 'string', nullable: true }, sku: { type: 'string' }, productSku: { type: 'string' },
-    entityId: { type: 'string' }, service: { type: 'string' }, paygate: { type: 'string' },
-    externalId: { type: 'string' }, status: { type: 'string' }, kind: { type: 'string' },
-    capabilities: { type: 'array', items: PermissionSetSchema as never, nullable: true },
-    limits: { type: 'object', nullable: true, additionalProperties: LimitConfigSchema as never, required: [] },
+    id, entityId: str, planSku: str, productSku: str, service: str, paygate: str, externalId: str,
+    itemId: optStr, priceId: optStr, status: SubscriptionStatusSchema, externalStatus: optStr, rank: num,
+    periodStart: optDate, periodEnd: optDate, cancelAtPeriodEnd: optBool, canceledAt: optDate,
+    endedAt: optDate, pausedAt: optDate, trialEnd: optDate, latestInvoiceId: optStr, customerId: optStr,
+    disputedAt: optDate, disputeStatus: optStr, createdAt: date, updatedAt: optDate, syncedAt: optDate,
+    lastEventId: optStr, initialPropagatedAt: optDate, currency: optStr,
+    checkoutSessionId: optStr, purchaseId: optStr, firstInvoiceId: optStr, country: optStr, email: optStr,
+    amountTotalMinor: optNum, amountTaxMinor: optNum, termsAccepted: optBool, startRequestId: optStr,
+    withdrawnAt: optDate,
+    propagated: {
+      type: 'object',
+      nullable: true,
+      properties: {
+        planSku: str, rank: num, status: SubscriptionStatusSchema, cancelAtPeriodEnd: optBool,
+        pausedAt: optDate, renewedInvoiceId: optStr,
+      },
+      required: ['planSku', 'rank', 'status'],
+      additionalProperties: false,
+    },
   },
-  required: ['sku', 'productSku', 'entityId', 'service', 'paygate', 'externalId', 'status', 'kind'],
-  additionalProperties: true,
+  required: [
+    'entityId', 'planSku', 'productSku', 'service', 'paygate', 'externalId', 'status', 'rank', 'createdAt',
+  ],
+  additionalProperties: false,
 } as unknown as JSONSchemaType<PaymentSubscriptionRecord>
 
+export const PaymentFulfillmentSchema = {
+  type: 'object',
+  properties: {
+    id, entityId: str, productSku: str, planSku: optStr, service: str, paygate: str, externalId: str,
+    paymentIntentId: optStr, chargeId: optStr, invoiceId: optStr, mode: CheckoutPricingModeSchema,
+    units: optNum, amountMinor: optNum, sourceChargeAmountMinor: optNum, amountCurrency: optStr,
+    chargeAmountMinor: optNum, currency: optStr, createdAt: date,
+    fulfilledAt: optDate, failedAt: optDate, refundedMinor: optNum, refundedAt: optDate,
+    disputedAt: optDate, disputeStatus: optStr,
+    country: optStr, email: optStr, profileId: optStr, amountTotalMinor: optNum, amountTaxMinor: optNum,
+    termsAccepted: optBool, purchaseId: optStr,
+  },
+  required: ['entityId', 'productSku', 'service', 'paygate', 'externalId', 'mode', 'createdAt'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<PaymentFulfillmentRecord>
+
+export const PaymentWebhookSchema = {
+  type: 'object',
+  properties: {
+    id, paygate: str, service: str, url: str, externalId: str,
+    /** The signing secret: field-encrypted when the database is configured with a key. */
+    secret: { type: 'string', secure: true },
+    apiVersion: str, events: { type: 'array', items: str }, hash: str, createdAt: date, updatedAt: optDate,
+  },
+  required: ['paygate', 'service', 'url', 'externalId', 'secret', 'apiVersion', 'events', 'hash', 'createdAt'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<PaymentWebhookRecord>
+
+export const PaymentUsageSchema = {
+  type: 'object',
+  properties: {
+    id, entityId: str, limitKey: str, window: str, delta: num, eventKey: str, ref: optStr, reason: optStr,
+    planSku: optStr, createdAt: date, releasedAt: optDate,
+  },
+  required: ['entityId', 'limitKey', 'window', 'delta', 'eventKey', 'createdAt'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<PaymentUsageRecord>
+
+export const PaymentUsageCounterSchema = {
+  type: 'object',
+  properties: {
+    id, entityId: str, limitKey: str, window: str, used: num, limit: num, planSku: optStr,
+    overSince: optDate, updatedAt: date, reconciledAt: optDate,
+  },
+  required: ['entityId', 'limitKey', 'window', 'used', 'limit', 'updatedAt'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<PaymentUsageCounterRecord>
+
 export const FingerprintSchema = {
   type: 'object',
   properties: {
-    id: { type: 'string', nullable: true }, sku: { type: 'string' }, hash: { type: 'string' },
-    productId: { type: 'string', nullable: true },
+    id, sku: str, hash: str, productId: optStr, externalId: optStr,
+    prices: {
+      type: 'array',
+      nullable: true,
+      items: {
+        type: 'object',
+        properties: {
+          planSku: str, priceId: str, lookupKey: str, currency: str, unitAmount: num,
+          // An array, never a currency-keyed map: the resource coerces a map's values to strings.
+          options: {
+            type: 'array',
+            items: {
+              type: 'object', properties: { currency: str, unitAmount: num },
+              required: ['currency', 'unitAmount'], additionalProperties: false,
+            },
+          },
+          taxBehavior: optStr, interval: optStr, sourceUnitAmount: num, sourceCurrency: str, syncedAt: date,
+        },
+        required: [
+          'planSku', 'priceId', 'lookupKey', 'currency', 'unitAmount', 'options', 'sourceUnitAmount',
+          'sourceCurrency', 'syncedAt',
+        ],
+        additionalProperties: false,
+      },
+    },
+    updatedAt: date,
   },
-  required: ['sku', 'hash'], additionalProperties: true,
+  required: ['sku', 'hash', 'updatedAt'],
+  additionalProperties: false,
 } as unknown as JSONSchemaType<FingerprintRecord>
+
+/** An optional enum: `null` must be listed for a validator to accept it. */
+const nullableEnum = (values: readonly unknown[]) => ({ type: 'string', enum: [...values, null], nullable: true })
+
+/** The request evidence every consumer act carries (`RequestOrigin`). */
+const origin = {
+  ip: optStr, forwardedFor: optStr, userAgent: optStr, ipCountry: optStr, acceptLanguage: optStr, via: optStr,
+} as const
+
+const links = {
+  type: 'object',
+  properties: {
+    billingTerms: str, withdrawalInformation: optStr, withdrawalForm: optStr, withdrawalFunction: optStr,
+    cancellation: optStr,
+  },
+  required: ['billingTerms'],
+  additionalProperties: false,
+} as const
+
+export const BillingProfileSchema = {
+  type: 'object',
+  properties: {
+    id, entityId: str, country: str, region: ConsumerRegionSchema, currency: str, language: str,
+    source: { type: 'string', enum: ['checkout', 'customer', 'manual'] }, paygate: str, customerId: optStr,
+    sessionId: optStr, ipCountry: optStr, email: optStr, name: optStr, business: optBool, lockedAt: date,
+    createdAt: date, updatedAt: optDate,
+  },
+  required: ['entityId', 'country', 'region', 'currency', 'language', 'source', 'paygate', 'lockedAt', 'createdAt'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<BillingProfileRecord>
+
+export const PurchaseSchema = {
+  type: 'object',
+  properties: {
+    id, purchaseId: str, contractRef: str, entityId: str, kind: PurchaseKindSchema, paygate: str,
+    sessionId: optStr, subscriptionId: optStr, paymentIntentId: optStr, invoiceId: optStr, invoiceNumber: optStr,
+    invoiceLineId: optStr, productSku: str, planSku: optStr, profileId: optStr, country: optStr,
+    region: nullableEnum(ConsumerRegionSchema.enum), ipCountry: optStr, inScope: { type: 'boolean' },
+    language: str, email: optStr, name: optStr, business: optBool, currency: str, amountSubtotalMinor: num,
+    amountTaxMinor: num, amountTotalMinor: num, presentmentCurrency: optStr, presentmentAmountMinor: optNum,
+    netAmountMinor: optNum, amountCurrency: optStr, units: optNum, taxBehavior: optStr, termsAccepted: optBool,
+    textVersion: optStr, copyVersion: optStr, startRequestId: optStr, servicesStartedAt: optDate,
+    confirmationMailAt: optDate, purchasedAt: date, deadline: optDate, consentId: optStr, consentedAt: optDate,
+    withdrawalId: optStr, withdrawnAt: optDate, refundedMinor: optNum, refundedAt: optDate, cancellationId: optStr,
+    cancelEffectiveAt: optDate, createdAt: date, updatedAt: optDate,
+  },
+  required: [
+    'purchaseId', 'contractRef', 'entityId', 'kind', 'paygate', 'productSku', 'inScope', 'language', 'currency',
+    'amountSubtotalMinor', 'amountTaxMinor', 'amountTotalMinor', 'purchasedAt', 'createdAt',
+  ],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<PurchaseRecord>
+
+export const ConsumerConsentSchema = {
+  type: 'object',
+  properties: {
+    id, kind: ConsentKindSchema, entityId: str, profileId: optStr, name: optStr, email: optStr,
+    purchaseIds: { type: 'array', items: str },
+    planSku: optStr, planName: optStr, textVersion: str, copyVersion: str, language: str, uiLanguage: optStr, trader: str,
+    text: {
+      type: 'object',
+      properties: { request: str, acknowledgement: str, checkbox: str },
+      required: ['request', 'acknowledgement', 'checkbox'],
+      additionalProperties: false,
+    },
+    links, deadline: optDate, decidedAt: date, expiresAt: optDate, ...origin,
+  },
+  required: [
+    'kind', 'entityId', 'purchaseIds', 'textVersion', 'copyVersion', 'language', 'trader', 'text', 'links',
+    'decidedAt',
+  ],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ConsumerConsentRecord>
+
+export const ConsumerDeclarationSchema = {
+  type: 'object',
+  properties: {
+    id, kind: DeclarationKindSchema, channel: DeclarationChannelSchema, entityId: optStr, purchaseId: optStr,
+    subscriptionId: optStr, contractRef: optStr, name: str, email: str,
+    cancellationKind: nullableEnum(CancellationKindSchema.enum), reason: optStr,
+    effective: nullableEnum(['earliest', 'date']), requestedDate: optStr,
+    language: str, textVersion: optStr, copyVersion: str, receivedAt: date, matched: { type: 'boolean' },
+    profileId: optStr, duplicateOf: optStr, status: str, refundMinor: optNum, currency: optStr,
+    effectiveAt: optDate, ...origin,
+  },
+  required: ['kind', 'channel', 'name', 'email', 'language', 'copyVersion', 'receivedAt', 'matched', 'status'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ConsumerDeclarationRecord>
+
+export const ConsumerEventSchema = {
+  type: 'object',
+  properties: {
+    id, recordId: str,
+    recordKind: { type: 'string', enum: ['purchase', 'consent', 'declaration', 'profile', 'checkout'] },
+    entityId: optStr,
+    action: {
+      type: 'string',
+      enum: [
+        'mail', 'computed', 'meter', 'refund', 'credit-note', 'subscription-cancel', 'cancel-scheduled', 'observers',
+        'lock', 'lock-mismatch', 'relock', 'unlock', 'duplicate', 'checkout-terms-fallback',
+      ],
+    },
+    step: optStr, ok: { type: 'boolean' }, skipped: optBool, externalId: optStr, amountMinor: optNum,
+    currency: optStr, detail: optStr, error: optStr, at: date,
+  },
+  required: ['recordId', 'recordKind', 'action', 'ok', 'at'],
+  additionalProperties: false,
+} as unknown as JSONSchemaType<ConsumerEventRecord>

package/src/observer.ts

@@ -1,21 +1,54 @@
 import { createLazyService } from '@owlmeans/context'
 import { PAYMENT_OBSERVER } from './consts.js'
-import type { CompletionObserver, Config, Context, SubscriptionCallback, TopUpCallback } from './types.js'
+import type {
+  CancellationCallback, CompletionObserver, Config, ConsentCallback, Context, DisputeCallback,
+  PaymentFailedCallback, RefundCallback, SubscriptionCallback, TopUpCallback, WithdrawalCallback,
+} from './types.js'
 
+/**
+ * The application's side of payment completion. Callbacks run sequentially and are awaited; a
+ * throw escapes to the webhook so the paygate delivers the event again — every callback must be
+ * idempotent by the `eventKey` (`externalId` for a top-up) it is handed.
+ *
+ * The consumer-rights callbacks (`onConsent`, `onWithdrawal`, `onCancellation`) run after the
+ * records and the paygate steps of their act; a throw is recorded as an `observers` event and
+ * retried by the consumer-rights `reconcile()` — they, too, are idempotent by `eventKey`.
+ */
 export const makeCompletionObserverService = (
   alias: string = PAYMENT_OBSERVER,
 ): CompletionObserver => {
-  const topUpCallbacks: TopUpCallback[] = []
-  const subscriptionCallbacks: SubscriptionCallback[] = []
+  const topUp: TopUpCallback[] = []
+  const subscription: SubscriptionCallback[] = []
+  const refund: RefundCallback[] = []
+  const dispute: DisputeCallback[] = []
+  const paymentFailed: PaymentFailedCallback[] = []
+  const consent: ConsentCallback[] = []
+  const withdrawal: WithdrawalCallback[] = []
+  const cancellation: CancellationCallback[] = []
+
+  const run = async <E>(callbacks: Array<(event: E, ctx: never) => Promise<void>>, event: E, ctx: unknown) => {
+    for (const callback of callbacks) {
+      await callback(event, ctx as never)
+    }
+  }
+
   return createLazyService<CompletionObserver>(alias, {
-    onTopUp: cb => { topUpCallbacks.push(cb) },
-    onSubscription: cb => { subscriptionCallbacks.push(cb) },
-    propagateTopUp: async (completion, ctx) => {
-      for (const callback of topUpCallbacks) await callback(completion, ctx)
-    },
-    propagateSubscription: async (completion, ctx) => {
-      for (const callback of subscriptionCallbacks) await callback(completion, ctx)
-    },
+    onTopUp: cb => { topUp.push(cb) },
+    onSubscription: cb => { subscription.push(cb) },
+    onRefund: cb => { refund.push(cb) },
+    onDispute: cb => { dispute.push(cb) },
+    onPaymentFailed: cb => { paymentFailed.push(cb) },
+    onConsent: cb => { consent.push(cb) },
+    onWithdrawal: cb => { withdrawal.push(cb) },
+    onCancellation: cb => { cancellation.push(cb) },
+    propagateTopUp: async (completion, ctx) => { await run(topUp, completion, ctx) },
+    propagateSubscription: async (event, ctx) => { await run(subscription, event, ctx) },
+    propagateRefund: async (event, ctx) => { await run(refund, event, ctx) },
+    propagateDispute: async (event, ctx) => { await run(dispute, event, ctx) },
+    propagatePaymentFailed: async (event, ctx) => { await run(paymentFailed, event, ctx) },
+    propagateConsent: async (event, ctx) => { await run(consent, event, ctx) },
+    propagateWithdrawal: async (event, ctx) => { await run(withdrawal, event, ctx) },
+    propagateCancellation: async (event, ctx) => { await run(cancellation, event, ctx) },
   }, service => async () => { service.initialized = true })
 }
 

package/src/plan.ts

@@ -0,0 +1,89 @@
+import { ENTITLING_STATUSES, INTERNAL_PAYGATE, PlanRequired } from '@owlmeans/payment'
+import type { ProductPlan } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { payment, subscriptions } from './utils.js'
+import type { EffectivePlan, PaymentPlan, PaymentProduct, PaymentSubscriptionRecord } from './types.js'
+
+/** A plan's rank; an absent rank reads as `0`. */
+export const planRank = (plan: Pick<ProductPlan, 'rank'>): number => plan.rank ?? 0
+
+/** A plan by sku, or `null` when the catalogue no longer declares it. */
+export const findPlan = async (ctx: ApiContext, planSku: string): Promise<PaymentPlan | null> => {
+  try {
+    return await payment(ctx).plan(planSku) as PaymentPlan
+  } catch {
+    return null
+  }
+}
+
+/** A product by sku, or `null`. */
+export const findProduct = async (ctx: ApiContext, productSku: string): Promise<PaymentProduct | null> => {
+  try {
+    return await payment(ctx).product(productSku) as PaymentProduct
+  } catch {
+    return null
+  }
+}
+
+/** Every plan of every declared product. */
+export const catalogPlans = async (ctx: ApiContext): Promise<PaymentPlan[]> => {
+  const products = await payment(ctx).products()
+  const plans: PaymentPlan[] = []
+  for (const product of products) {
+    plans.push(...await payment(ctx).allPlans(product.sku) as PaymentPlan[])
+  }
+
+  return plans
+}
+
+/** The declared free plan an entity falls back to: the lowest rank, then the sku. */
+export const freePlanOf = async (ctx: ApiContext): Promise<PaymentPlan | null> =>
+  (await catalogPlans(ctx))
+    .filter(plan => plan.free === true)
+    .sort((a, b) => planRank(a) - planRank(b) || a.sku.localeCompare(b.sku))[0] ?? null
+
+/** An internal grant with a period end stops entitling at that instant; a paygate row never does. */
+const stillEntitles = (row: PaymentSubscriptionRecord, at: Date): boolean =>
+  row.paygate !== INTERNAL_PAYGATE || row.periodEnd == null || new Date(row.periodEnd).getTime() > at.getTime()
+
+const unknownPlans = new Set<string>()
+
+/**
+ * The plan an entity holds: its highest-ranked subscription in an entitling status (the catalogue
+ * rank, the stored one for a plan the catalogue no longer declares; the newest first on a tie),
+ * else the declared free plan.
+ *
+ * @throws PlanRequired when there is neither.
+ */
+export const resolveEffectivePlan = async (
+  ctx: ApiContext, entityId: string, at: Date = new Date(),
+): Promise<EffectivePlan> => {
+  const fallback = await freePlanOf(ctx)
+  const { items } = await subscriptions(ctx).list(
+    { entityId, status: [...ENTITLING_STATUSES] }, { size: 0 },
+  )
+  const candidates: Array<{ plan: PaymentPlan, row: PaymentSubscriptionRecord, rank: number }> = []
+  for (const row of items.filter(item => stillEntitles(item, at))) {
+    const plan = await findPlan(ctx, row.planSku)
+    if (plan == null) {
+      if (!unknownPlans.has(row.planSku)) {
+        unknownPlans.add(row.planSku)
+        console.warn(`[payment] subscription "${row.externalId}" names unknown plan "${row.planSku}"; ignored`)
+      }
+      continue
+    }
+    candidates.push({ plan, row, rank: planRank(plan) })
+  }
+  candidates.sort((a, b) => b.rank - a.rank
+    || new Date(b.row.createdAt).getTime() - new Date(a.row.createdAt).getTime())
+
+  const best = candidates[0]
+  if (best != null) {
+    return { plan: best.plan, subscription: best.row, fallback }
+  }
+  if (fallback != null) {
+    return { plan: fallback, subscription: null, fallback }
+  }
+
+  throw new PlanRequired(entityId)
+}

package/src/plugins/checkout-plugins.ts

@@ -0,0 +1,155 @@
+import { CheckoutLimitExceeded, narrowAmountPolicy } from '@owlmeans/payment'
+import type { AmountNarrowing, AmountPolicyView } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_SESSION_TTL_MAX_SECONDS, STRIPE_SESSION_TTL_MIN_SECONDS } from '../consts.js'
+import type {
+  CheckoutAttempt, CheckoutNarrowInput, CheckoutPlugin, CheckoutSettled,
+} from '../types.js'
+
+export interface CheckoutPluginRegistry {
+  use: (plugin: CheckoutPlugin) => void
+  list: () => readonly CheckoutPlugin[]
+}
+
+/**
+ * The gateway's checkout plugins, the way `ExecutionService.use` seats its own: a plugin with an
+ * alias already registered replaces it in place (a layer wired twice must not answer twice), one
+ * without an alias is appended.
+ */
+export const makeCheckoutPluginRegistry = (): CheckoutPluginRegistry => {
+  const plugins: CheckoutPlugin[] = []
+
+  return {
+    use: plugin => {
+      const at = plugin.alias != null ? plugins.findIndex(entry => entry.alias === plugin.alias) : -1
+      if (at < 0) {
+        plugins.push(plugin)
+      } else {
+        plugins[at] = plugin
+      }
+    },
+    list: () => [...plugins],
+  }
+}
+
+/**
+ * An entity's amount policy as every plugin narrows it now — the ONE computation both
+ * `gateway.amountPolicy` and checkout enforcement use, so a control and a refusal cannot disagree.
+ * A plugin's error propagates: a narrowing that cannot be computed fails closed.
+ */
+export const narrowAmountFor = async (
+  ctx: ApiContext, plugins: readonly CheckoutPlugin[], input: CheckoutNarrowInput,
+): Promise<AmountPolicyView> => {
+  const narrowings: AmountNarrowing[] = []
+  for (const plugin of plugins) {
+    if (plugin.narrow == null) {
+      continue
+    }
+    const narrowing = await plugin.narrow(ctx, input)
+    if (narrowing != null) {
+      narrowings.push(narrowing)
+    }
+  }
+
+  return narrowAmountPolicy(input.base, narrowings, {
+    productSku: input.productSku, ...(input.planSku != null ? { planSku: input.planSku } : {}),
+  })
+}
+
+/**
+ * Refuse an amount the narrowed view does not allow: any amount while `blocked`, else one above
+ * the narrowed maximum.
+ *
+ * @throws CheckoutLimitExceeded (409)
+ */
+export const assertAmountAllowed = (view: AmountPolicyView, amountMinor: number): void => {
+  const limit = view.limit
+  if (limit == null || (!limit.blocked && amountMinor <= limit.maximumMinor)) {
+    return
+  }
+  throw new CheckoutLimitExceeded({
+    reason: limit.reason ?? 'limit', maximumMinor: limit.maximumMinor, currency: limit.currency,
+    ...(limit.resetsAt != null ? { resetsAt: limit.resetsAt } : {}),
+  })
+}
+
+/**
+ * The session lifetime: the smallest `sessionTtlSeconds` any plugin declares, clamped to Stripe's
+ * 30 minutes – 24 hours; `undefined` when none declares one (Stripe's own default).
+ */
+export const sessionTtlOf = (plugins: readonly CheckoutPlugin[]): number | undefined => {
+  const declared = plugins
+    .map(plugin => plugin.sessionTtlSeconds)
+    .filter((ttl): ttl is number => typeof ttl === 'number' && Number.isFinite(ttl))
+  if (declared.length === 0) {
+    return undefined
+  }
+
+  return Math.min(STRIPE_SESSION_TTL_MAX_SECONDS, Math.max(STRIPE_SESSION_TTL_MIN_SECONDS, Math.floor(Math.min(...declared))))
+}
+
+/** A plugin that admitted an attempt, with the reservation it holds. */
+export interface Admitted {
+  plugin: CheckoutPlugin
+  reservationId?: string
+}
+
+/**
+ * Tell plugins how a checkout ended. A plugin's error is logged, never raised: a hold carries its
+ * own TTL, and the webhook that reports the outcome must not be redelivered for it.
+ */
+export const settleCheckout = async (
+  ctx: ApiContext, plugins: readonly CheckoutPlugin[], settled: CheckoutSettled,
+): Promise<void> => {
+  for (const plugin of plugins) {
+    if (plugin.settled == null) {
+      continue
+    }
+    try {
+      await plugin.settled(ctx, settled)
+    } catch (error) {
+      console.error(`[payment] checkout plugin "${plugin.alias ?? 'anonymous'}" failed to settle`, error)
+    }
+  }
+}
+
+/** Release what admitted plugins hold for a checkout that never became usable. */
+export const releaseAdmitted = async (
+  ctx: ApiContext, admitted: readonly Admitted[], attempt: CheckoutAttempt, sessionId?: string,
+): Promise<void> => {
+  for (const { plugin, reservationId } of admitted) {
+    await settleCheckout(ctx, [plugin], {
+      entityId: attempt.entityId, productSku: attempt.productSku,
+      ...(attempt.planSku != null ? { planSku: attempt.planSku } : {}),
+      ...(sessionId != null ? { sessionId } : {}),
+      ...(reservationId != null ? { reservationId } : {}),
+      ...(attempt.amountMinor != null ? { amountMinor: attempt.amountMinor } : {}),
+      outcome: 'failed', at: new Date(),
+    })
+  }
+}
+
+/**
+ * Ask every plugin to admit the attempt, in order. A veto releases what the earlier plugins
+ * admitted and propagates.
+ */
+export const admitCheckout = async (
+  ctx: ApiContext, plugins: readonly CheckoutPlugin[], attempt: CheckoutAttempt,
+): Promise<Admitted[]> => {
+  const admitted: Admitted[] = []
+  for (const plugin of plugins) {
+    if (plugin.admit == null) {
+      admitted.push({ plugin })
+      continue
+    }
+    try {
+      const admission = await plugin.admit(ctx, attempt)
+      admitted.push({ plugin, ...(admission?.reservationId != null ? { reservationId: admission.reservationId } : {}) })
+    } catch (error) {
+      await releaseAdmitted(ctx, admitted.filter(entry => entry.plugin.admit != null), attempt)
+      throw error
+    }
+  }
+
+  return admitted
+}