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

package/src/consumer/withdrawal.ts

@@ -0,0 +1,302 @@
+import type Stripe from 'stripe'
+import {
+  consumerText, oneTimeWithdrawalRefund, PurchaseKind, subscriptionWithdrawalRefund,
+} from '@owlmeans/payment'
+import type { WithdrawalEstimate } from '@owlmeans/payment'
+import type { Context as ApiContext } from '@owlmeans/server-api'
+import { STRIPE_OWNER_KEY, STRIPE_OWNER_VALUE, STRIPE_PAYGATE_ALIAS } from '../consts.js'
+import { findPlan } from '../plan.js'
+import { compact, errorText, isMissingObject, subscriptions } from '../utils.js'
+import { invoiceEvidenceOf } from './capture.js'
+import { formatDate } from './format.js'
+import { hasEvent, patchPurchase, purchaseRefOf, recordEvent } from './records.js'
+import type {
+  ConsumerDeclarationRecord, PaymentSubscriptionRecord, PurchaseRecord, UsageMeter, UsageReading,
+} from '../types.js'
+
+const DAY_MS = 86_400_000
+
+/** What a withdrawal of one purchase reimburses, as computed at one instant. */
+export interface WithdrawalComputation {
+  reading: UsageReading
+  /** Gross, tax included — what is refunded. */
+  refundMinor: number
+  /** Net of tax — the credit note's line amount. */
+  netMinor: number
+  estimate: WithdrawalEstimate
+  /** The units the deduction counts: used after consent, plus settled debt and earlier claw-backs. */
+  deducted: number
+  /** What the application takes back from the balance: the purchase's units still unused. */
+  unitsReturned: number
+}
+
+/**
+ * The refund of a withdrawal from one purchase, in the consumer's favour (`@owlmeans/payment`
+ * calculators). The meter's deduction is `usedAfter + settled + clawed`: units used after consent
+ * (before it the consumer bears no cost), units that paid an earlier overdraft, units already
+ * refunded by money. A subscription's `time` components count from its start request; without
+ * one nothing is deducted for time.
+ */
+export const computeWithdrawal = async (
+  ctx: ApiContext, meter: UsageMeter, purchase: PurchaseRecord, at: Date,
+): Promise<WithdrawalComputation> => {
+  const reading = await meter.used(ctx, compact({
+    entityId: purchase.entityId, purchase: purchaseRefOf(purchase),
+    after: purchase.consentedAt != null ? new Date(purchase.consentedAt) : undefined, at,
+  }))
+  const deducted = Math.max(0, reading.usedAfter) + Math.max(0, reading.settled ?? 0) + Math.max(0, reading.clawed ?? 0)
+  const unitsReturned = Math.max(0, Math.floor(reading.remaining
+    ?? reading.granted - reading.used - (reading.settled ?? 0) - (reading.clawed ?? 0)))
+  const paid = purchase.amountTotalMinor
+  const refunded = purchase.refundedMinor ?? 0
+  const net = purchase.amountSubtotalMinor
+  // The earlier refunds' net share, so the credit note never credits more than is left.
+  const refundedNet = paid > 0 ? Math.floor(refunded * net / paid) : 0
+
+  if (purchase.kind === PurchaseKind.TopUp) {
+    const gross = oneTimeWithdrawalRefund({ paidMinor: paid, refundedMinor: refunded, unitsGranted: reading.granted, unitsUsed: deducted })
+    const netRefund = oneTimeWithdrawalRefund({ paidMinor: net, refundedMinor: refundedNet, unitsGranted: reading.granted, unitsUsed: deducted })
+    const open = Math.max(0, paid - refunded)
+
+    return {
+      reading, deducted, unitsReturned,
+      refundMinor: gross.refundMinor,
+      netMinor: netRefund.refundMinor,
+      estimate: {
+        refundMinor: gross.refundMinor, currency: purchase.currency, timeDeductionMinor: 0,
+        unitsDeductionMinor: Math.max(0, open - gross.refundMinor),
+        unitsUsed: Math.min(deducted, reading.granted), unitsGranted: reading.granted,
+      },
+    }
+  }
+
+  const subscription = purchase.subscriptionId != null
+    ? await subscriptions(ctx).byExternalId(purchase.subscriptionId, STRIPE_PAYGATE_ALIAS) : null
+  const plan = purchase.planSku != null ? await findPlan(ctx, purchase.planSku) : null
+  const purchasedAt = new Date(purchase.purchasedAt)
+  const periodStart = subscription?.periodStart != null ? new Date(subscription.periodStart) : purchasedAt
+  const periodEnd = subscription?.periodEnd != null ? new Date(subscription.periodEnd)
+    : new Date(periodStart.getTime() + (plan?.recurring?.interval === 'year' ? 365 : 30) * DAY_MS)
+  const result = subscriptionWithdrawalRefund({
+    paidMinor: paid, refundedMinor: refunded, netMinor: net,
+    components: plan?.withdrawal?.components,
+    periodStart, periodEnd,
+    servicesRequestedAt: purchase.servicesStartedAt != null ? new Date(purchase.servicesStartedAt) : null,
+    withdrawnAt: at,
+    units: { granted: reading.granted, used: deducted },
+  })
+
+  return {
+    reading, deducted, unitsReturned,
+    refundMinor: result.refundMinor,
+    netMinor: result.refundNetMinor,
+    estimate: compact({
+      refundMinor: result.refundMinor, currency: purchase.currency, timeDeductionMinor: result.timeDeductionMinor,
+      unitsDeductionMinor: result.unitsDeductionMinor, elapsedDays: result.elapsedDays, periodDays: result.periodDays,
+      unitsUsed: result.unitsUsed, unitsGranted: result.unitsGranted,
+    }) as WithdrawalEstimate,
+  }
+}
+
+export interface WithdrawalExecution {
+  /** Every paygate step succeeded (or had nothing to do). */
+  ok: boolean
+  refundId?: string
+  creditNoteId?: string
+  refundedMinor: number
+  subscriptionCanceled: boolean
+  /** A step can never succeed without an operator (no payment to refund). */
+  needsReview: boolean
+}
+
+/** A Stripe error that says the subscription is already gone. */
+const alreadyCanceled = (error: unknown): boolean => isMissingObject(error)
+  || /canceled subscription|already (been )?cancel/i.test((error as { message?: string } | null)?.message ?? '')
+
+/** A refund this withdrawal already made (found by its metadata) — what a retry adopts. */
+const existingRefund = async (stripe: Stripe, paymentIntentId: string, withdrawalId: string): Promise<Stripe.Refund | null> => {
+  const { data } = await stripe.refunds.list({ payment_intent: paymentIntentId, limit: 100 })
+
+  return data.find(refund => refund.metadata?.withdrawalId === withdrawalId && refund.status !== 'failed'
+    && refund.status !== 'canceled') ?? null
+}
+
+/** A credit note this withdrawal already made — what a retry adopts. */
+const existingCreditNote = async (stripe: Stripe, invoiceId: string, withdrawalId: string): Promise<Stripe.CreditNote | null> => {
+  const { data } = await stripe.creditNotes.list({ invoice: invoiceId, limit: 100 })
+
+  return data.find(note => note.metadata?.withdrawalId === withdrawalId && note.status !== 'void') ?? null
+}
+
+/**
+ * Stripe replays the stored answer of an idempotency key — a failure too — for a day: a retry
+ * uses a fresh key (`…:<attempt>`) and first adopts what an earlier attempt may have made.
+ */
+const keyOf = (withdrawalId: string, step: string, attempt: number): Stripe.RequestOptions => ({
+  idempotencyKey: attempt > 0 ? `withdrawal:${withdrawalId}:${step}:${attempt}` : `withdrawal:${withdrawalId}:${step}`,
+})
+
+/**
+ * Execute a withdrawal at the paygate, the first attempt of every call under the idempotency key
+ * `withdrawal:<id>:<step>` (a retry by `reconcile` adopts what an earlier attempt made):
+ *
+ * 1. a subscription purchase: `subscriptions.cancel` at once, without proration or a final invoice;
+ * 2. an invoice-backed purchase: `creditNotes.preview` of the invoice line at the net refund, then
+ *    OUR `refunds.create` for the previewed total (metadata `withdrawalId` — the refund webhook then
+ *    tells observers not to claw back), then `creditNotes.create` linking that refund — the
+ *    corrective tax document; a failed credit note keeps the plain refund and is recorded;
+ * 3. no invoice: a plain proportional refund on the payment intent.
+ *
+ * Steps that already succeeded (a recorded `ok` event) are skipped. Every step is an event.
+ */
+export const executeWithdrawal = async (
+  ctx: ApiContext, stripe: Stripe, declaration: ConsumerDeclarationRecord, purchase: PurchaseRecord,
+  computation: { refundMinor: number, netMinor: number }, opts: { attempt?: number } = {},
+): Promise<WithdrawalExecution> => {
+  const withdrawalId = declaration.id as string
+  const attempt = opts.attempt ?? 0
+  const key = (step: string): Stripe.RequestOptions => keyOf(withdrawalId, step, attempt)
+  const event = (action: 'refund' | 'credit-note' | 'subscription-cancel', fields: Record<string, unknown>) =>
+    recordEvent(ctx, {
+      recordId: withdrawalId, recordKind: 'declaration', entityId: purchase.entityId, action, ok: false, ...fields,
+    } as Parameters<typeof recordEvent>[1])
+  const outcome: WithdrawalExecution = { ok: true, refundedMinor: 0, subscriptionCanceled: false, needsReview: false }
+
+  if (purchase.kind === PurchaseKind.Subscription && purchase.subscriptionId != null) {
+    if (await hasEvent(ctx, withdrawalId, 'subscription-cancel', undefined, true)) {
+      outcome.subscriptionCanceled = true
+    } else {
+      try {
+        await stripe.subscriptions.cancel(purchase.subscriptionId, {
+          prorate: false, invoice_now: false, cancellation_details: { comment: `withdrawal:${withdrawalId}` },
+        }, key('subscription-cancel'))
+        outcome.subscriptionCanceled = true
+        await event('subscription-cancel', { ok: true, externalId: purchase.subscriptionId })
+      } catch (error) {
+        if (alreadyCanceled(error)) {
+          outcome.subscriptionCanceled = true
+          await event('subscription-cancel', { ok: true, externalId: purchase.subscriptionId, detail: '{"already":true}' })
+        } else {
+          outcome.ok = false
+          await event('subscription-cancel', { externalId: purchase.subscriptionId, error: errorText(error) })
+        }
+      }
+      if (outcome.subscriptionCanceled) {
+        const row: PaymentSubscriptionRecord | null = await subscriptions(ctx).byExternalId(purchase.subscriptionId, STRIPE_PAYGATE_ALIAS)
+        if (row != null && row.withdrawnAt == null) {
+          await subscriptions(ctx).update({ ...row, withdrawnAt: new Date(declaration.receivedAt) })
+        }
+      }
+    }
+  }
+
+  if (await hasEvent(ctx, withdrawalId, 'refund', undefined, true)) {
+    return { ...outcome, refundedMinor: declaration.refundMinor ?? computation.refundMinor }
+  }
+  if (computation.refundMinor <= 0) {
+    return outcome
+  }
+
+  let paymentIntentId = purchase.paymentIntentId
+  let invoiceLineId = purchase.invoiceLineId
+  if (purchase.invoiceId != null && (paymentIntentId == null || invoiceLineId == null)) {
+    const invoice = await invoiceEvidenceOf(stripe, purchase.invoiceId)
+    paymentIntentId = paymentIntentId ?? invoice.paymentIntentId
+    invoiceLineId = invoiceLineId ?? invoice.invoiceLineId
+    await patchPurchase(ctx, purchase.purchaseId, compact({
+      paymentIntentId, invoiceLineId, invoiceNumber: purchase.invoiceNumber ?? invoice.invoiceNumber,
+    }))
+  }
+  if (paymentIntentId == null) {
+    await event('refund', { error: 'no-payment-intent', amountMinor: computation.refundMinor, currency: purchase.currency })
+    return { ...outcome, ok: false, needsReview: true }
+  }
+
+  const open = Math.max(0, purchase.amountTotalMinor - (purchase.refundedMinor ?? 0))
+  let amount = Math.min(open, computation.refundMinor)
+  let lines: Stripe.CreditNoteCreateParams.Line[] | null = null
+  if (purchase.invoiceId != null && invoiceLineId != null && computation.netMinor > 0) {
+    lines = [{ type: 'invoice_line_item', invoice_line_item: invoiceLineId, amount: computation.netMinor }]
+    try {
+      const preview = await stripe.creditNotes.preview({ invoice: purchase.invoiceId, lines })
+      amount = Math.min(open, preview.total)
+    } catch (error) {
+      lines = null
+      await event('credit-note', { step: 'preview', error: errorText(error) })
+    }
+  }
+  if (amount <= 0) {
+    return outcome
+  }
+
+  let refund: Stripe.Refund
+  try {
+    refund = (attempt > 0 ? await existingRefund(stripe, paymentIntentId, withdrawalId) : null)
+      ?? await stripe.refunds.create({
+        payment_intent: paymentIntentId, amount, reason: 'requested_by_customer',
+        metadata: { [STRIPE_OWNER_KEY]: STRIPE_OWNER_VALUE, withdrawalId, purchaseId: purchase.purchaseId },
+      }, key('refund'))
+  } catch (error) {
+    await event('refund', { error: errorText(error), amountMinor: amount, currency: purchase.currency })
+    return { ...outcome, ok: false }
+  }
+  await event('refund', { ok: true, externalId: refund.id, amountMinor: refund.amount, currency: refund.currency })
+  outcome.refundId = refund.id
+  outcome.refundedMinor = refund.amount
+
+  if (lines != null && purchase.invoiceId != null) {
+    try {
+      const note = await stripe.creditNotes.create({
+        invoice: purchase.invoiceId, lines, refund: refund.id,
+        memo: consumerText(declaration.language, 'credit-note.memo', {
+          contractRef: purchase.contractRef, date: formatDate(new Date(declaration.receivedAt), declaration.language),
+        }),
+        metadata: { withdrawalId, purchaseId: purchase.purchaseId },
+      }, key('credit-note'))
+      outcome.creditNoteId = note.id
+      await event('credit-note', { ok: true, externalId: note.id, amountMinor: note.total, currency: note.currency })
+    } catch (error) {
+      // The refund stands; the corrective document is retried by reconcile.
+      await event('credit-note', { error: errorText(error), detail: JSON.stringify({ refundId: refund.id }) })
+    }
+  }
+
+  return outcome
+}
+
+/** Retry a credit note that failed after its refund succeeded. */
+export const retryCreditNote = async (
+  ctx: ApiContext, stripe: Stripe, declaration: ConsumerDeclarationRecord, purchase: PurchaseRecord,
+  netMinor: number, refundId: string, attempt: number,
+): Promise<boolean> => {
+  const withdrawalId = declaration.id as string
+  let invoiceLineId = purchase.invoiceLineId
+  if (invoiceLineId == null && purchase.invoiceId != null) {
+    invoiceLineId = (await invoiceEvidenceOf(stripe, purchase.invoiceId)).invoiceLineId
+  }
+  if (purchase.invoiceId == null || invoiceLineId == null || netMinor <= 0) {
+    return false
+  }
+  try {
+    const note = await existingCreditNote(stripe, purchase.invoiceId, withdrawalId) ?? await stripe.creditNotes.create({
+      invoice: purchase.invoiceId,
+      lines: [{ type: 'invoice_line_item', invoice_line_item: invoiceLineId, amount: netMinor }],
+      refund: refundId,
+      memo: consumerText(declaration.language, 'credit-note.memo', {
+        contractRef: purchase.contractRef, date: formatDate(new Date(declaration.receivedAt), declaration.language),
+      }),
+      metadata: { withdrawalId, purchaseId: purchase.purchaseId },
+    }, keyOf(withdrawalId, 'credit-note', attempt))
+    await recordEvent(ctx, {
+      recordId: withdrawalId, recordKind: 'declaration', entityId: purchase.entityId, action: 'credit-note', ok: true,
+      externalId: note.id, amountMinor: note.total, currency: note.currency,
+    })
+    return true
+  } catch (error) {
+    await recordEvent(ctx, {
+      recordId: withdrawalId, recordKind: 'declaration', entityId: purchase.entityId, action: 'credit-note', ok: false,
+      error: errorText(error), detail: JSON.stringify({ refundId }),
+    })
+    return false
+  }
+}

package/src/index.ts

@@ -15,8 +15,10 @@ export {
   classifySubscriptionChange, commitSubscription, propagatedStateOf, subscriptionEventKey,
 } from './subscription.js'
 export type { CommitOptions, CommitResult } from './subscription.js'
-export { planLookupKey, syncPaymentProducts, syncStripeProducts } from './sync.js'
+export { planLookupKey, syncedPlanPrices, syncPaymentProducts, syncStripeProducts } from './sync.js'
 export { amountCheckoutLineItem, quantityCheckoutLineItem } from './plugins/stripe.js'
+export { assertAmountAllowed, narrowAmountFor, sessionTtlOf } from './plugins/checkout-plugins.js'
+export * from './consumer/index.js'
 export { makeEstimateCache, estimateStripePrice } from './plugins/estimate.js'
 export type { EstimateCache } from './plugins/estimate.js'
 export { applySubscription, createEventHandler, mapStatus } from './plugins/events.js'
@@ -26,7 +28,7 @@ export {
 } from './plugins/webhook-manager.js'
 export { ensurePortalConfiguration } from './plugins/portal.js'
 export {
-  activeSubscription, apiVersionOf, entitlements, fingerprints, fulfillments, gateway, observer,
-  paygateCustomers, payment, paymentWebhooks, stripeClient, stripeConfig, subscriptions, usageCounters,
-  usageEvents,
+  activeSubscription, apiVersionOf, billingProfiles, consumerConsents, consumerDeclarations, consumerEvents,
+  consumerRights, consumerRightsOf, entitlements, fingerprints, fulfillments, gateway, observer, paygateCustomers,
+  payment, paymentWebhooks, purchases, stripeClient, stripeConfig, subscriptions, usageCounters, usageEvents,
 } from './utils.js'

package/src/model.ts

@@ -1,9 +1,13 @@
 import type { JSONSchemaType } from 'ajv'
 import { DateSchema } from '@owlmeans/auth'
-import { CheckoutPricingModeSchema, SubscriptionStatusSchema } from '@owlmeans/payment'
+import {
+  CancellationKindSchema, CheckoutPricingModeSchema, ConsentKindSchema, ConsumerRegionSchema,
+  DeclarationChannelSchema, DeclarationKindSchema, PurchaseKindSchema, SubscriptionStatusSchema,
+} from '@owlmeans/payment'
 import type {
-  FingerprintRecord, PaygateCustomerRecord, PaymentFulfillmentRecord, PaymentSubscriptionRecord,
-  PaymentUsageCounterRecord, PaymentUsageRecord, PaymentWebhookRecord,
+  BillingProfileRecord, ConsumerConsentRecord, ConsumerDeclarationRecord, ConsumerEventRecord, FingerprintRecord,
+  PaygateCustomerRecord, PaymentFulfillmentRecord, PaymentSubscriptionRecord, PaymentUsageCounterRecord,
+  PaymentUsageRecord, PaymentWebhookRecord, PurchaseRecord,
 } from './types.js'
 
 /**
@@ -26,7 +30,7 @@ export const PaygateCustomerSchema = {
   type: 'object',
   properties: {
     id, paygate: str, externalId: str, entityId: optStr, profileId: optStr, email: optStr, name: optStr,
-    taxId: optStr, deletedAt: optDate,
+    taxId: optStr, country: optStr, currency: optStr, deletedAt: optDate,
   },
   required: ['paygate', 'externalId'],
   additionalProperties: false,
@@ -40,7 +44,10 @@ export const PaymentSubscriptionSchema = {
     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,
+    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,
@@ -67,6 +74,8 @@ export const PaymentFulfillmentSchema = {
     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,
@@ -107,8 +116,141 @@ export const PaymentUsageCounterSchema = {
 export const FingerprintSchema = {
   type: 'object',
   properties: {
-    id, sku: str, hash: str, productId: optStr, externalId: optStr, updatedAt: date,
+    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', '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,14 +1,18 @@
 import { createLazyService } from '@owlmeans/context'
 import { PAYMENT_OBSERVER } from './consts.js'
 import type {
-  CompletionObserver, Config, Context, DisputeCallback, PaymentFailedCallback, RefundCallback,
-  SubscriptionCallback, TopUpCallback,
+  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,
@@ -18,6 +22,9 @@ export const makeCompletionObserverService = (
   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) {
@@ -31,11 +38,17 @@ export const makeCompletionObserverService = (
     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 })
 }