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

package/src/consts.ts

@@ -1,21 +1,114 @@
-import { contract, protocol, protocols, schema, typed } from '@owlmeans/entrypoint'
+import { contract, protocol, schema, typed } from '@owlmeans/entrypoint'
 import { backend, route, RouteMethod } from '@owlmeans/route'
 import { GUARD_ED25519 } from '@owlmeans/server-app'
+import { INTERNAL_PAYGATE, LIMIT_GATE } from '@owlmeans/payment'
 import type { JSONSchemaType } from 'ajv'
 
+export { INTERNAL_PAYGATE, LIMIT_GATE }
+
 export const STRIPE_PAYGATE_ALIAS = 'stripe'
 export const STRIPE_PLUGIN_CONFIG = '_external:stripe'
+export const STRIPE_PORTAL_PLUGIN_CONFIG = '_external:stripe-portal'
+/** Stripe-only pricing settings (FX Quotes API version, the unspecified-price migration switch) — never advertised to the browser, unlike the `PricingPolicy` record itself. */
+export const STRIPE_PRICING_PLUGIN_CONFIG = '_external:stripe-pricing'
 export const STRIPE_SIGNATURE = 'Stripe-Signature'
+
+/**
+ * The FX Quotes API is a Stripe PREVIEW endpoint as of this writing: it answers only a
+ * `Stripe-Version` header naming a preview version, never the SDK's pinned stable one. Verify this
+ * string against https://docs.stripe.com/api/fx_quotes/create before relying on it, and override it
+ * with `declarePaymentPricing({ stripe: { fxApiVersion } })` once Stripe moves the API or renames
+ * the preview.
+ */
+export const STRIPE_FX_QUOTES_API_VERSION = '2025-07-30.preview'
 export const GATEWAY_SERVICE = 'payment-gateway'
 export const PAYMENT_OBSERVER = 'payment-observer'
+export const ENTITLEMENT_SERVICE = 'payment-entitlement'
+
 export const RES_PAYGATE_CUSTOMER = 'payment-paygate-customer'
 export const RES_PAYMENT_SUBSCRIPTION = 'payment-subscription'
+export const RES_PAYMENT_FULFILLMENT = 'payment-fulfillment'
+export const RES_PAYMENT_WEBHOOK = 'payment-webhook'
+export const RES_PAYMENT_USAGE = 'payment-usage'
+export const RES_PAYMENT_USAGE_COUNTER = 'payment-usage-counter'
 export const RES_PAYMENT_FINGERPRINT = 'payment-fingerprint'
-export const COMPLETION_TOP_UP = 'top-up'
-export const COMPLETION_SUBSCRIPTION = 'subscription'
+
+/** One per organization: the billing country fixed at the first purchase. */
+export const RES_BILLING_PROFILE = 'payment-billing-profile'
+/** One per paid checkout (a top-up, a subscription's first invoice): the contract and its window. */
+export const RES_PAYMENT_PURCHASE = 'payment-purchase'
+/** Append-only: express consents to early performance and subscription start requests. */
+export const RES_CONSUMER_CONSENT = 'payment-consumer-consent'
+/** Append-only: withdrawal and cancellation declarations. */
+export const RES_CONSUMER_DECLARATION = 'payment-consumer-declaration'
+/** Append-only: every execution and audit step of the consumer-rights flows. */
+export const RES_CONSUMER_EVENT = 'payment-consumer-event'
+
+export const CONSUMER_RIGHTS_SERVICE = 'payment-consumer-rights'
+/** The consumer-rights mail options (trader, sender, archive copies) — never advertised. */
+export const CONSUMER_RIGHTS_MAIL_PLUGIN_CONFIG = '_external:payment-consumer-mail'
+
+/** Stripe's own bounds of a Checkout Session's `expires_at`, from now. */
+export const STRIPE_SESSION_TTL_MIN_SECONDS = 30 * 60
+export const STRIPE_SESSION_TTL_MAX_SECONDS = 24 * 60 * 60
+
+/** How far back `reconcile` looks for completed sessions that have no purchase row. */
+export const PURCHASE_BACKFILL_DAYS = 16
+
+/** Top-level domains that never receive mail (RFC 2606 / 6761) — e2e addresses are recorded as skipped. */
+export const RESERVED_MAIL_TLDS: readonly string[] = Object.freeze(['test', 'example', 'invalid', 'localhost'])
+
+/** The purchase id prefix of a Stripe purchase: `stripe:<session id>` or `stripe:<subscription id>`. */
+export const PURCHASE_ID_PREFIX = 'stripe'
+
+/**
+ * The contract reference alphabet: digits and capitals without the look-alikes 0/O, 1/I/L, so a
+ * reference read aloud or typed from paper is never ambiguous.
+ */
+export const CONTRACT_REF_ALPHABET = '23456789ABCDEFGHJKMNPQRSTUVWXYZ'
+
+/** Fingerprint sku prefix of a portal configuration: `portal:<service>`. */
+export const FINGERPRINT_PORTAL = 'portal'
+
+/**
+ * The metadata every Stripe object this package creates carries (`{ owlmeans: 'payment', service }`).
+ * It labels the object for an operator; several deployments of one service share it, so it never
+ * decides on its own that an object belongs to this deployment.
+ */
+export const STRIPE_OWNER_KEY = 'owlmeans'
+export const STRIPE_OWNER_VALUE = 'payment'
+
+/**
+ * The metadata key naming the ONE deployment a portal configuration belongs to, valued with that
+ * deployment's webhook URL (`webhookUrlOf`). Only an exact match lets a deployment adopt a
+ * configuration it holds no fingerprint row for.
+ */
+export const STRIPE_DEPLOYMENT_KEY = 'deployment'
+
+/**
+ * Every Stripe event the managed webhook endpoint subscribes to.
+ *
+ * `invoice.upcoming` is enabled although nothing handles it (it carries no invoice id and nothing
+ * is due), so an application can observe it without a Stripe dashboard change.
+ */
+export const WEBHOOK_EVENTS: readonly string[] = Object.freeze([
+  'checkout.session.completed', 'checkout.session.async_payment_succeeded',
+  'checkout.session.async_payment_failed', 'checkout.session.expired',
+  'customer.created', 'customer.updated', 'customer.deleted',
+  'customer.subscription.created', 'customer.subscription.updated', 'customer.subscription.deleted',
+  'customer.subscription.paused', 'customer.subscription.resumed', 'customer.subscription.trial_will_end',
+  'customer.subscription.pending_update_applied', 'customer.subscription.pending_update_expired',
+  'invoice.paid', 'invoice.payment_failed', 'invoice.payment_action_required', 'invoice.upcoming',
+  'invoice.marked_uncollectible', 'invoice.voided',
+  'charge.refunded', 'refund.created', 'refund.updated', 'refund.failed',
+  'charge.dispute.created', 'charge.dispute.closed', 'charge.dispute.funds_withdrawn',
+  'charge.dispute.funds_reinstated',
+])
 
 export interface PaygateParams { paygate: string }
 export interface ResyncResult { ok: boolean }
+export interface ResyncSubscriptionsResult { scanned: number; updated: number }
+
 const PaygateParamsSchema = schema<PaygateParams>({
   type: 'object', properties: { paygate: { type: 'string' } }, required: ['paygate'],
   additionalProperties: false,
@@ -24,24 +117,39 @@ const ResyncResultSchema = schema<ResyncResult>({
   type: 'object', properties: { ok: { type: 'boolean' } }, required: ['ok'],
   additionalProperties: false,
 } as JSONSchemaType<ResyncResult>)
+const ResyncSubscriptionsResultSchema = schema<ResyncSubscriptionsResult>({
+  type: 'object',
+  properties: { scanned: { type: 'number' }, updated: { type: 'number' } },
+  required: ['scanned', 'updated'],
+  additionalProperties: false,
+} as JSONSchemaType<ResyncSubscriptionsResult>)
 
 const aliases = {
-  base: 'payment-gate', webhook: 'payment-gate:webhook', resync: 'payment-gate:resync',
+  base: 'payment-gate',
+  webhook: 'payment-gate:webhook',
+  resync: 'payment-gate:resync',
+  resyncSubscriptions: 'payment-gate:resync-subscriptions',
 } as const
 const base = protocol(route(aliases.base, '/payment-gate', backend()), contract())
 
 /** Embedded gateway protocol tree; the alias strings are private adapter details. */
 export const paymentGate = {
   base,
+  /** Public: Stripe signs the raw body, so no application guard may sit in front of it. */
   webhook: protocol(
     route(aliases.webhook, '/webhook/:paygate', backend({ parent: base, method: RouteMethod.POST })),
     contract.request({ params: PaygateParamsSchema }, typed<undefined>()),
   ),
+  /** Re-sync products, prices, the portal configuration and the webhook endpoint. */
   resync: protocol(
     route(aliases.resync, '/resync', backend({ parent: base, method: RouteMethod.POST })),
     contract(ResyncResultSchema),
     { guards: GUARD_ED25519 },
   ),
+  /** Re-read every live paygate subscription and apply it as a webhook would. */
+  resyncSubscriptions: protocol(
+    route(aliases.resyncSubscriptions, '/resync-subscriptions', backend({ parent: base, method: RouteMethod.POST })),
+    contract(ResyncSubscriptionsResultSchema),
+    { guards: GUARD_ED25519 },
+  ),
 } as const
-
-export const paymentGateProtocols = protocols(paymentGate)

package/src/consumer/capture.ts

@@ -0,0 +1,362 @@
+import type Stripe from 'stripe'
+import {
+  billingLanguageOf, ConsentKind, CONSUMER_RIGHTS_COPY_VERSION, inScope, PurchaseKind, regionOf,
+  withdrawalDeadlineOf,
+} from '@owlmeans/payment'
+import type { ConsumerRightsPolicy } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_PAYGATE_ALIAS } from '../consts.js'
+import {
+  billingProfiles, compact, conditionalSet, consumerConsents, dateOf, idOf, isMissingObject, payment, purchases,
+} from '../utils.js'
+import { sendConsumerMail } from './mail.js'
+import {
+  createPurchase, hasEvent, lockProfile, patchPurchase, purchaseIdOf,
+} from './records.js'
+import type { PurchaseDraft } from './records.js'
+import type { BillingProfileRecord, PaymentSubscriptionRecord, PurchaseRecord } from '../types.js'
+
+/** What a completed Checkout Session says about its buyer and totals. */
+export interface SessionEvidence {
+  country?: string
+  email?: string
+  name?: string
+  business?: boolean
+  currency: string
+  subtotalMinor: number
+  taxMinor: number
+  totalMinor: number
+  presentmentCurrency?: string
+  presentmentAmountMinor?: number
+  termsAccepted?: boolean
+}
+
+/**
+ * The buyer and totals of a Checkout Session. `presentment_details` (Adaptive Pricing) is not typed
+ * by the pinned SDK, hence the narrow accessor.
+ */
+export const sessionEvidenceOf = (session: Stripe.Checkout.Session): SessionEvidence => {
+  const details = session.customer_details
+  const presentment = (session as unknown as {
+    presentment_details?: { presentment_amount?: number, presentment_currency?: string } | null
+  }).presentment_details
+  const subtotal = session.amount_subtotal ?? 0
+  const tax = session.total_details?.amount_tax ?? 0
+
+  return compact({
+    country: details?.address?.country?.toUpperCase() ?? undefined,
+    email: details?.email ?? undefined,
+    name: details?.name ?? undefined,
+    business: (details?.tax_ids?.length ?? 0) > 0 || details?.tax_exempt === 'reverse' ? true : undefined,
+    currency: (session.currency ?? '').toLowerCase(),
+    subtotalMinor: subtotal,
+    taxMinor: tax,
+    totalMinor: session.amount_total ?? subtotal + tax,
+    presentmentCurrency: presentment?.presentment_currency?.toLowerCase(),
+    presentmentAmountMinor: presentment?.presentment_amount,
+    termsAccepted: session.consent?.terms_of_service === 'accepted' ? true
+      : session.consent?.terms_of_service != null ? false : undefined,
+  }) as SessionEvidence
+}
+
+/** What an invoice adds to a purchase: its number, its line and the payment behind it. */
+export interface InvoiceEvidence {
+  invoiceNumber?: string
+  invoiceLineId?: string
+  paymentIntentId?: string
+  country?: string
+  subtotalMinor?: number
+  taxMinor?: number
+  totalMinor?: number
+  currency?: string
+}
+
+/**
+ * An invoice's evidence, best effort: an unreachable invoice is logged and yields nothing — the
+ * withdrawal reads it again when it needs it. `invoice.payment_intent` is top-level on the pinned
+ * API version.
+ */
+export const invoiceEvidenceOf = async (stripe: Stripe | null | undefined, invoiceId: string | undefined): Promise<InvoiceEvidence> => {
+  if (stripe == null || invoiceId == null) {
+    return {}
+  }
+  try {
+    const invoice = await stripe.invoices.retrieve(invoiceId)
+    const typed = invoice as unknown as { payment_intent?: string | { id?: string } | null, tax?: number | null }
+
+    return compact({
+      invoiceNumber: invoice.number ?? undefined,
+      invoiceLineId: invoice.lines?.data?.[0]?.id,
+      paymentIntentId: idOf(typed.payment_intent),
+      country: invoice.customer_address?.country?.toUpperCase() ?? undefined,
+      subtotalMinor: invoice.subtotal ?? undefined,
+      taxMinor: typed.tax ?? undefined,
+      totalMinor: invoice.total ?? undefined,
+      currency: invoice.currency ?? undefined,
+    }) as InvoiceEvidence
+  } catch (error) {
+    if (!isMissingObject(error)) {
+      console.warn(`[payment] invoice "${invoiceId}" unreadable for its purchase`, error)
+    }
+    return {}
+  }
+}
+
+const deadlineOf = (policy: ConsumerRightsPolicy, scoped: boolean, purchasedAt: Date): Date | undefined =>
+  scoped ? withdrawalDeadlineOf(purchasedAt, policy) : undefined
+
+/** Lock the entity's billing country from a completed checkout, when the policy locks countries. */
+const lockFromSession = async (
+  ctx: ApiContext, policy: ConsumerRightsPolicy, entityId: string, session: Stripe.Checkout.Session,
+  evidence: SessionEvidence,
+): Promise<BillingProfileRecord | null> => {
+  const metadata = session.metadata ?? {}
+  const country = evidence.country ?? metadata.country
+  if (!policy.mechanisms.countryLock || country == null || country === '') {
+    return null
+  }
+  const { record } = await lockProfile(ctx, policy, {
+    entityId, country, source: 'checkout', customerId: idOf(session.customer), sessionId: session.id,
+    ipCountry: metadata.ipCountry, email: evidence.email, name: evidence.name, business: evidence.business,
+    currency: evidence.currency, language: metadata.language,
+  })
+
+  return record
+}
+
+/**
+ * Mail the purchase confirmation once per purchase: only the delivery that claims the purchase's
+ * `confirmationMailAt` (a conditional write — concurrent deliveries in several processes, a
+ * redelivery, the checkout refining a subscription) sends it; one that failed is retried by
+ * `reconcile`, never here. A purchase mailed before the claim existed is recognised by its event.
+ */
+const confirmPurchase = async (ctx: ApiContext, policy: ConsumerRightsPolicy, purchase: PurchaseRecord): Promise<void> => {
+  if (!policy.mechanisms.purchaseConfirmation || !purchase.inScope) {
+    return
+  }
+  if (await hasEvent(ctx, purchase.purchaseId, 'mail', 'purchase')) {
+    return
+  }
+  const claimed = await conditionalSet(purchases(ctx), { purchaseId: purchase.purchaseId, confirmationMailAt: null }, {
+    confirmationMailAt: new Date(),
+  })
+  if (!claimed) {
+    return
+  }
+  await sendConsumerMail(ctx, policy, 'purchase', purchase.purchaseId)
+}
+
+export interface CapturedPurchase {
+  purchase: PurchaseRecord
+  created: boolean
+}
+
+/**
+ * A completed, paid ONE-TIME checkout as a purchase — the window and the contract registry. Runs
+ * BEFORE the credits are granted: the billing country is locked first (first write wins; another
+ * country is a `lock-mismatch` event), then the purchase row is written, then its confirmation is
+ * mailed. `null` when no consumer-rights policy is declared.
+ */
+export const capturePaymentPurchase = async (
+  ctx: ApiContext, stripe: Stripe | null, session: Stripe.Checkout.Session,
+  extra: { netAmountMinor?: number, amountCurrency?: string, units?: number, taxBehavior?: string, at?: Date } = {},
+  opts: { mail?: boolean } = {},
+): Promise<CapturedPurchase | null> => {
+  const policy = await payment(ctx).consumerRightsPolicy()
+  if (policy == null) {
+    return null
+  }
+  const metadata = session.metadata ?? {}
+  const entityId = metadata.entityId
+  if (entityId == null || metadata.productSku == null) {
+    return null
+  }
+  const evidence = sessionEvidenceOf(session)
+  const profile = await lockFromSession(ctx, policy, entityId, session, evidence)
+  const existing = await purchases(ctx).byPurchaseId(purchaseIdOf(session.id))
+  if (existing != null) {
+    if (opts.mail !== false) await confirmPurchase(ctx, policy, existing)
+    return { purchase: existing, created: false }
+  }
+
+  const country = evidence.country ?? metadata.country ?? profile?.country
+  const region = regionOf(country, policy)
+  // Protected when either the buyer's own address or the organization's locked country is in scope.
+  const scoped = inScope(region, country, policy) || (profile != null && inScope(profile.region, profile.country, policy))
+  const invoice = await invoiceEvidenceOf(stripe, idOf(session.invoice))
+  const purchasedAt = extra.at ?? new Date()
+  const draft = compact({
+    purchaseId: purchaseIdOf(session.id),
+    entityId,
+    kind: PurchaseKind.TopUp,
+    paygate: STRIPE_PAYGATE_ALIAS,
+    sessionId: session.id,
+    paymentIntentId: idOf(session.payment_intent) ?? invoice.paymentIntentId,
+    invoiceId: idOf(session.invoice),
+    invoiceNumber: invoice.invoiceNumber,
+    invoiceLineId: invoice.invoiceLineId,
+    productSku: metadata.productSku,
+    planSku: metadata.planSku,
+    profileId: metadata.profileId,
+    country,
+    region: region ?? undefined,
+    ipCountry: metadata.ipCountry,
+    inScope: scoped,
+    language: profile?.language ?? metadata.language ?? billingLanguageOf(country, policy),
+    email: evidence.email,
+    name: evidence.name,
+    business: evidence.business,
+    currency: evidence.currency,
+    amountSubtotalMinor: evidence.subtotalMinor,
+    amountTaxMinor: evidence.taxMinor,
+    amountTotalMinor: evidence.totalMinor,
+    presentmentCurrency: evidence.presentmentCurrency,
+    presentmentAmountMinor: evidence.presentmentAmountMinor,
+    netAmountMinor: extra.netAmountMinor,
+    amountCurrency: extra.amountCurrency,
+    units: extra.units,
+    taxBehavior: extra.taxBehavior,
+    termsAccepted: evidence.termsAccepted,
+    textVersion: metadata.termsVersion ?? policy.textVersion,
+    copyVersion: metadata.copyVersion ?? CONSUMER_RIGHTS_COPY_VERSION,
+    purchasedAt,
+    deadline: deadlineOf(policy, scoped, purchasedAt),
+  }) as PurchaseDraft
+  const { record, created } = await createPurchase(ctx, draft)
+  if (opts.mail !== false) await confirmPurchase(ctx, policy, record)
+
+  return { purchase: record, created }
+}
+
+/** The start request a subscription's metadata names, when it is a real start request of that entity. */
+const startRequestOf = async (ctx: ApiContext, entityId: string, id: string | undefined) => {
+  if (id == null || id === '') {
+    return null
+  }
+  const consent = await consumerConsents(ctx).load(id).catch(() => null)
+
+  return consent != null && consent.kind === ConsentKind.SubscriptionStart && consent.entityId === entityId ? consent : null
+}
+
+/**
+ * A subscription's FIRST invoice as a purchase — called while the subscription is committed, BEFORE
+ * the `created` observers grant anything, so the window exists before the bundle can be spent. The
+ * buyer's country and totals are refined when the checkout completes. The start request (when the
+ * metadata names one) is the purchase's consent: `servicesStartedAt` and `consentedAt`.
+ */
+export const captureSubscriptionPurchase = async (
+  ctx: ApiContext, stripe: Stripe | null, subscription: Stripe.Subscription, row: PaymentSubscriptionRecord,
+): Promise<CapturedPurchase | null> => {
+  const policy = await payment(ctx).consumerRightsPolicy()
+  if (policy == null) {
+    return null
+  }
+  const purchaseId = purchaseIdOf(subscription.id)
+  const existing = await purchases(ctx).byPurchaseId(purchaseId)
+  if (existing != null) {
+    return { purchase: existing, created: false }
+  }
+  const metadata = subscription.metadata ?? {}
+  const item = subscription.items?.data?.[0]
+  const invoiceId = idOf(subscription.latest_invoice)
+  const invoice = await invoiceEvidenceOf(stripe, invoiceId)
+  const profile = await billingProfiles(ctx).byEntity(row.entityId)
+  const country = invoice.country ?? profile?.country ?? metadata.country
+  const region = regionOf(country, policy)
+  const scoped = inScope(region, country, policy) || (profile != null && inScope(profile.region, profile.country, policy))
+  const start = await startRequestOf(ctx, row.entityId, metadata.startRequestId)
+  const subtotal = invoice.subtotalMinor ?? (item?.price?.unit_amount ?? 0) * (item?.quantity ?? 1)
+  const tax = invoice.taxMinor ?? 0
+  const purchasedAt = dateOf(subscription.created) ?? new Date()
+  const draft = compact({
+    purchaseId,
+    entityId: row.entityId,
+    kind: PurchaseKind.Subscription,
+    paygate: STRIPE_PAYGATE_ALIAS,
+    subscriptionId: subscription.id,
+    paymentIntentId: invoice.paymentIntentId,
+    invoiceId,
+    invoiceNumber: invoice.invoiceNumber,
+    invoiceLineId: invoice.invoiceLineId,
+    productSku: row.productSku,
+    planSku: row.planSku,
+    profileId: metadata.profileId,
+    country,
+    region: region ?? undefined,
+    ipCountry: metadata.ipCountry,
+    inScope: scoped,
+    language: profile?.language ?? metadata.language ?? billingLanguageOf(country, policy),
+    currency: (invoice.currency ?? subscription.currency ?? item?.price?.currency ?? 'usd').toLowerCase(),
+    amountSubtotalMinor: subtotal,
+    amountTaxMinor: tax,
+    amountTotalMinor: invoice.totalMinor ?? subtotal + tax,
+    taxBehavior: item?.price?.tax_behavior ?? undefined,
+    textVersion: metadata.termsVersion ?? policy.textVersion,
+    copyVersion: metadata.copyVersion ?? CONSUMER_RIGHTS_COPY_VERSION,
+    startRequestId: start?.id,
+    servicesStartedAt: start?.decidedAt,
+    consentId: start?.id,
+    consentedAt: start?.decidedAt,
+    purchasedAt,
+    deadline: deadlineOf(policy, scoped, purchasedAt),
+  }) as PurchaseDraft
+  const { record, created } = await createPurchase(ctx, draft)
+
+  return { purchase: record, created }
+}
+
+/**
+ * Refine a subscription purchase with its completed checkout: the buyer's own country (and so the
+ * scope and deadline), e-mail, the charged totals, the terms acceptance and the session id; lock
+ * the billing country; mail the confirmation once.
+ */
+export const completeSubscriptionPurchase = async (
+  ctx: ApiContext, stripe: Stripe | null, session: Stripe.Checkout.Session, purchase: PurchaseRecord,
+  opts: { mail?: boolean } = {},
+): Promise<PurchaseRecord> => {
+  const policy = await payment(ctx).consumerRightsPolicy()
+  if (policy == null) {
+    return purchase
+  }
+  const evidence = sessionEvidenceOf(session)
+  const profile = await lockFromSession(ctx, policy, purchase.entityId, session, evidence)
+  const country = evidence.country ?? purchase.country ?? profile?.country
+  const region = regionOf(country, policy)
+  const scoped = inScope(region, country, policy) || (profile != null && inScope(profile.region, profile.country, policy))
+  const invoice = purchase.invoiceLineId == null || purchase.paymentIntentId == null
+    ? await invoiceEvidenceOf(stripe, purchase.invoiceId ?? idOf(session.invoice)) : {}
+  const purchasedAt = new Date(purchase.purchasedAt)
+  const fields = compact({
+    sessionId: session.id,
+    invoiceId: purchase.invoiceId ?? idOf(session.invoice),
+    invoiceNumber: purchase.invoiceNumber ?? invoice.invoiceNumber,
+    invoiceLineId: purchase.invoiceLineId ?? invoice.invoiceLineId,
+    paymentIntentId: purchase.paymentIntentId ?? invoice.paymentIntentId,
+    country,
+    region: region ?? undefined,
+    inScope: scoped,
+    deadline: scoped ? purchase.deadline ?? withdrawalDeadlineOf(purchasedAt, policy) : undefined,
+    email: evidence.email ?? purchase.email,
+    name: evidence.name ?? purchase.name,
+    business: evidence.business ?? purchase.business,
+    currency: evidence.currency !== '' ? evidence.currency : purchase.currency,
+    amountSubtotalMinor: evidence.subtotalMinor,
+    amountTaxMinor: evidence.taxMinor,
+    amountTotalMinor: evidence.totalMinor,
+    presentmentCurrency: evidence.presentmentCurrency,
+    presentmentAmountMinor: evidence.presentmentAmountMinor,
+    termsAccepted: evidence.termsAccepted,
+    ipCountry: purchase.ipCountry ?? session.metadata?.ipCountry,
+    language: profile?.language ?? purchase.language,
+  }) as Partial<PurchaseRecord>
+  await patchPurchase(ctx, purchase.purchaseId, fields)
+  const updated = { ...purchase, ...fields } as PurchaseRecord
+  if (!scoped && purchase.deadline != null) {
+    // Out of scope after all (the buyer's own country): no window.
+    await patchPurchase(ctx, purchase.purchaseId, { deadline: null as unknown as undefined })
+    delete updated.deadline
+  }
+  if (opts.mail !== false) await confirmPurchase(ctx, policy, updated)
+
+  return updated
+}

package/src/consumer/format.ts

@@ -0,0 +1,90 @@
+import { randomInt } from 'node:crypto'
+import { lastWithdrawalDayOf } from '@owlmeans/payment'
+import { CONTRACT_REF_ALPHABET, RESERVED_MAIL_TLDS } from '../consts.js'
+
+/** `CR-YYMMDD-XXXXXX` — the purchase's UTC date and six characters of an unambiguous alphabet. */
+export const makeContractRef = (at: Date = new Date()): string => {
+  const date = [at.getUTCFullYear() % 100, at.getUTCMonth() + 1, at.getUTCDate()]
+    .map(part => String(part).padStart(2, '0')).join('')
+  const suffix = Array.from({ length: 6 }, () => CONTRACT_REF_ALPHABET[randomInt(CONTRACT_REF_ALPHABET.length)]).join('')
+
+  return `CR-${date}-${suffix}`
+}
+
+/** A contract reference as a person may type it: trimmed, upper-cased, look-alike dashes unified. */
+export const normalizeContractRef = (value: string): string =>
+  value.trim().toUpperCase().replace(/[‐-―−\s]+/g, '-')
+
+export const normalizeEmail = (value: string | null | undefined): string => (value ?? '').trim().toLowerCase()
+
+/**
+ * Whether an address is on a reserved top-level domain (`.test`, `.example`, `.invalid`,
+ * `.localhost` — RFC 2606 / 6761), any subdomain included: `a@shop.test`, `a@mail.shop.test`,
+ * `a@localhost`. Case, surrounding spaces, a display-name form (`Name <a@shop.test>`) and a
+ * trailing root dot are all read through.
+ */
+export const isReservedAddress = (address: string): boolean => {
+  const bare = normalizeEmail(address).replace(/^.*<([^>]*)>.*$/, '$1')
+  const domain = (bare.split('@').pop() ?? '').trim().replace(/\.+$/, '')
+  const tld = domain.split('.').pop() ?? ''
+
+  return RESERVED_MAIL_TLDS.includes(tld)
+}
+
+export const escapeHtml = (value: string): string => value
+  .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  .replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+
+const fractionDigitsOf = (currency: string): number => {
+  try {
+    return new Intl.NumberFormat('en', { style: 'currency', currency: currency.toUpperCase() })
+      .resolvedOptions().maximumFractionDigits ?? 2
+  } catch {
+    return 2
+  }
+}
+
+/** Minor units as a localized amount with its currency (`12,56 €`, `$12.56`). */
+export const formatMoney = (amountMinor: number, currency: string, lng: string): string => {
+  const digits = fractionDigitsOf(currency)
+  const major = amountMinor / 10 ** digits
+  try {
+    return new Intl.NumberFormat(lng, { style: 'currency', currency: currency.toUpperCase() }).format(major)
+  } catch {
+    return `${major.toFixed(digits)} ${currency.toUpperCase()}`
+  }
+}
+
+/** A date and time in UTC, localized (`23 September 2026, 14:05`). */
+export const formatDateTime = (at: Date, lng: string): string => {
+  try {
+    return new Intl.DateTimeFormat(lng, { dateStyle: 'long', timeStyle: 'short', timeZone: 'UTC' }).format(at)
+  } catch {
+    return at.toISOString().replace('T', ' ').slice(0, 16)
+  }
+}
+
+/** A calendar date in UTC, localized. */
+export const formatDate = (at: Date, lng: string): string => {
+  try {
+    return new Intl.DateTimeFormat(lng, { dateStyle: 'long', timeZone: 'UTC' }).format(at)
+  } catch {
+    return at.toISOString().slice(0, 10)
+  }
+}
+
+/**
+ * The last included day of a window whose deadline is EXCLUSIVE (the first instant it is over),
+ * as a UTC date — the copy says "until the end of <date>": 13 October 00:00 UTC is "12 October".
+ */
+export const formatDeadline = (deadline: Date, lng: string): string =>
+  formatDate(lastWithdrawalDayOf(deadline), lng)
+
+/** A country's name in a language, else its code. */
+export const countryName = (country: string, lng: string): string => {
+  try {
+    return new Intl.DisplayNames([lng], { type: 'region' }).of(country.toUpperCase()) ?? country
+  } catch {
+    return country
+  }
+}