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

package/build/types.d.ts

@@ -1,10 +1,13 @@
+import type Stripe from 'stripe';
 import type { InitializedService, LazyService } from '@owlmeans/context';
 import type { ResourceRecord } from '@owlmeans/resource';
 import type { MongoResource } from '@owlmeans/mongo-resource';
 import type { PluginConfig } from '@owlmeans/config';
 import type { PermissionSet } from '@owlmeans/auth';
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { MailMessage } from '@owlmeans/mailer';
 import type { Config as ApiConfig, Context as ApiContext } from '@owlmeans/server-api';
-import type { AmountCheckoutPolicy, CheckoutPricingMode, EntitlementView, LimitDeclaration, LimitView, PlanCapability, PlanDuration, PortalFlow, PriceEstimate, PricingPolicy, Product, ProductPlan, ProductType, QuantityCheckoutPolicy, SubscriptionStatus } from '@owlmeans/payment';
+import type { AmountCheckoutPolicy, AmountNarrowing, AmountPolicyView, BillingProfileView, CancellationBody, CancellationKind, CancellationReceipt, CancellationStatus, CheckoutPricingMode, ConsentKind, ConsumerRegion, ConsumerRightsDeclaration, ConsumerRightsLinks, ConsumerRightsPolicy, DeclarationChannel, DeclarationKind, EntitlementView, LimitDeclaration, LimitView, PerformanceConsentBody, PerformanceConsentResponse, PerformanceConsentView, PlanCapability, PlanDuration, PlanPriceView, PlanWithdrawalComponent, PortalFlow, PriceEstimate, PricingPolicy, Product, ProductPlan, ProductType, PurchaseKind, PurchaseView, QuantityCheckoutPolicy, SubscriptionStartBody, SubscriptionStartResponse, SubscriptionStartView, SubscriptionStatus, WithdrawalBody, WithdrawalCandidateList, WithdrawalReceipt, WithdrawalStatus } from '@owlmeans/payment';
 export interface Config extends ApiConfig {
 }
 export interface Context<C extends Config = Config> extends ApiContext<C> {
@@ -23,6 +26,11 @@ export interface PaymentPlan extends ProductPlan {
     pricingMode?: CheckoutPricingMode;
     amountPolicy?: AmountCheckoutPolicy;
     quantityPolicy?: QuantityCheckoutPolicy;
+    /**
+     * Exact prices in further currencies, major units by lowercase ISO 4217 code (`{ usd: 20 }`).
+     * Synced as the reusable Price's `currency_options`, never converted.
+     */
+    currencyPrices?: Record<string, number>;
 }
 export interface PaymentProductDef {
     sku: string;
@@ -65,6 +73,19 @@ export interface PaymentPlanDef {
     minQuantity?: number;
     maxQuantity?: number;
     defaultQuantity?: number;
+    /**
+     * Exact prices in further currencies, major units by ISO 4217 code (`{ usd: 20 }`): a recurring
+     * or quantity plan's synced Price carries each as a `currency_options` entry at exactly this
+     * amount, while its default currency (the settlement currency) is converted as before.
+     */
+    currencyPrices?: Record<string, number>;
+    /**
+     * The separately priced parts of a subscription for a withdrawal (CJEU C-641/19): their
+     * `shareMinor` sum to `round(price × 100)`. Absent: the whole price is one `time` component.
+     */
+    withdrawal?: {
+        components: PlanWithdrawalComponent[];
+    };
 }
 /** File paths (or values) of the Stripe secrets. The webhook secret is an optional override. */
 export interface StripeSecretsDef {
@@ -100,6 +121,36 @@ export interface StripePricingPluginConfig extends PluginConfig, StripePricingDe
 export interface PricingDef extends PricingPolicy {
     stripe?: StripePricingDef;
 }
+/**
+ * The business the consumer contracts with — backend only, never advertised. `name` is what the
+ * express statements say (`{{trader}}` in a consent or start request); the mails' identity line,
+ * the withdrawal information and the model form ("To: …") say `legalName`, `address` and `email`.
+ */
+export type TraderDef = {
+    name: string;
+    legalName: string;
+    /** Postal address; without it (or `email`) the mails render without it and the boot warns. */
+    address?: string;
+    email?: string;
+    website?: string;
+};
+/** The consumer-rights mail options — backend only, never advertised. */
+export interface ConsumerMailDef {
+    /** The mailer service alias. Default `MAILER_SERVICE`. */
+    alias?: string;
+    from?: string;
+    replyTo?: string;
+    /** Evidence archive addresses: each receives its own copy of every consumer-rights mail. */
+    bcc?: string[];
+}
+export interface ConsumerMailPluginConfig extends PluginConfig, ConsumerMailDef {
+    trader?: TraderDef;
+}
+/** `declareConsumerRights`'s argument: the advertised policy plus the backend-only trader and mail options. */
+export type ConsumerRightsDef = ConsumerRightsDeclaration & {
+    trader?: TraderDef;
+    mail?: ConsumerMailDef;
+};
 /** What the managed customer portal configuration shows. */
 export interface PortalBrandingDef {
     headline?: string;
@@ -120,10 +171,104 @@ export interface CreateLinkParams {
     amountMinor?: number;
     /** Stripe Checkout and future paid-invoice language. Caller supplies a Stripe-supported locale. */
     locale?: string;
-    /** Trusted application copy shown beside the Checkout confirmation button. */
-    submitText?: string;
+    /**
+     * Trusted application copy shown beside the Checkout confirmation button — never caller-provided
+     * text. A function receives the charge currency and the price the session charges.
+     */
+    submitText?: string | ((context: CheckoutTextContext) => string);
     successUrl?: string;
     cancelUrl?: string;
+    /** The billing country the buyer declared (ISO 3166-1 alpha-2). A locked profile overrides it. */
+    country?: string;
+    /** The subscription start request recorded right before a subscription checkout. */
+    startRequestId?: string;
+    /** The language the buyer is shown legal copy in; default: the billing country's. */
+    consumerLanguage?: string;
+    /** The request's geolocated country (`cf-ipcountry`) — second location evidence, stored at lock. */
+    ipCountry?: string;
+}
+/** What a submit-text function is told about the session it labels. */
+export interface CheckoutTextContext {
+    language: string;
+    /** The charge currency, lowercase. */
+    currency: string;
+    /** A subscription's unit price in the charge currency; an amount checkout's pre-tax charge. */
+    unitAmountMinor?: number;
+    interval?: 'month' | 'year';
+    region: ConsumerRegion | null;
+    country?: string;
+}
+/** What a plugin narrows: one entity's amount checkout of one plan, at one instant. */
+export interface CheckoutNarrowInput {
+    entityId: string;
+    productSku: string;
+    planSku?: string;
+    /** The plan's own amount policy — the same for everyone. */
+    base: AmountCheckoutPolicy;
+    at: Date;
+}
+/** A checkout about to be created — what `admit` may veto. */
+export interface CheckoutAttempt {
+    entityId: string;
+    productSku: string;
+    planSku?: string;
+    mode: 'amount' | 'quantity' | 'subscription';
+    /** Amount mode: the net value bought, in the amount policy's currency. */
+    amountMinor?: number;
+    /** The amount policy's currency (amount mode), else the charge currency. */
+    amountCurrency?: string;
+    /** Amount mode: the pre-tax charge in `currency`. */
+    chargeMinor?: number;
+    currency: string;
+    /** The session lifetime the gateway will set; absent: Stripe's default (24 h). */
+    sessionTtlSeconds?: number;
+    expiresAt?: Date;
+    at: Date;
+}
+/** A plugin's admission: an optional reservation it binds to the session in `created`. */
+export interface CheckoutAdmission {
+    reservationId?: string;
+}
+/** The session a checkout became. */
+export interface CheckoutCreated extends CheckoutAttempt {
+    sessionId: string;
+    url: string;
+    /** What this plugin's own `admit` answered. */
+    reservationId?: string;
+}
+export type CheckoutOutcome = 'paid' | 'expired' | 'failed';
+/**
+ * How a checkout ended: `paid` (completed and paid), `expired`, or `failed` — an asynchronous
+ * payment failure, or a session that never became usable (a later plugin vetoed, Stripe refused,
+ * a `created` threw; then `sessionId` may be absent and `reservationId` names the hold to release).
+ */
+export interface CheckoutSettled {
+    entityId: string;
+    productSku?: string;
+    planSku?: string;
+    sessionId?: string;
+    reservationId?: string;
+    outcome: CheckoutOutcome;
+    amountMinor?: number;
+    at: Date;
+}
+/**
+ * A seam around amount and subscription checkout, registered with `gateway(ctx).use(plugin)` (a
+ * plugin with an `alias` registered twice replaces the first). Errors from `narrow` and `admit`
+ * propagate — a plugin fails closed; `settled` errors are logged, since holds carry their own TTL.
+ */
+export interface CheckoutPlugin {
+    alias?: string;
+    /** Lower what this entity may buy now; `null` for no opinion. */
+    narrow?: (ctx: ApiContext, input: CheckoutNarrowInput) => Promise<AmountNarrowing | null>;
+    /** Veto (throw, e.g. `CheckoutLimitExceeded`) or hold a reservation for the session. */
+    admit?: (ctx: ApiContext, attempt: CheckoutAttempt) => Promise<CheckoutAdmission | void>;
+    /** The session exists — bind the reservation. A throw expires the session and rethrows. */
+    created?: (ctx: ApiContext, created: CheckoutCreated) => Promise<void>;
+    /** From the webhook (paid, expired, failed) or from a checkout that never became usable. */
+    settled?: (ctx: ApiContext, settled: CheckoutSettled) => Promise<void>;
+    /** The longest a session may stay open; the gateway uses the smallest, clamped to 30 min–24 h. */
+    sessionTtlSeconds?: number;
 }
 export interface PortalLinkOptions {
     flow: PortalFlow;
@@ -165,6 +310,17 @@ export interface GatewayService extends InitializedService {
         scanned: number;
         updated: number;
     }>;
+    /** Register a checkout plugin; one with an `alias` already registered replaces it. */
+    use: (plugin: CheckoutPlugin) => void;
+    /** The registered checkout plugins, in registration order. */
+    checkoutPlugins: () => readonly CheckoutPlugin[];
+    /**
+     * The entity's amount policy of an amount plan as narrowed NOW — the very computation
+     * `createLink` enforces. Mongo and plugins only; works unmanaged.
+     */
+    amountPolicy: (ctx: ApiContext, entityId: string, productSku: string, planSku?: string) => Promise<AmountPolicyView>;
+    /** The synced prices of a product's plans, per currency — stored rows, no Stripe call. */
+    planPrices: (ctx: ApiContext, productSku: string) => Promise<PlanPriceView[]>;
 }
 export interface PaymentGatewayOptions {
     dbAlias?: string;
@@ -175,6 +331,8 @@ export interface PaymentGatewayOptions {
      */
     manage?: boolean;
 }
+/** A Stripe client for one context — the default reads the configured secret. */
+export type StripeFactory = (ctx: ApiContext) => Promise<Stripe>;
 /** @deprecated use `PaymentGatewayOptions` */
 export type PaymentResourceOptions = PaymentGatewayOptions;
 interface TopUpBase {
@@ -262,6 +420,14 @@ export interface RefundEvent {
     netAmountMinor?: number;
     /** Fulfillment targets: the pre-tax subtotal charged at checkout. */
     chargeAmountMinor?: number;
+    /** The refund's own metadata. */
+    metadata?: Record<string, string>;
+    /**
+     * Set when the refund executes a withdrawal (`refund.metadata.withdrawalId`): the `onWithdrawal`
+     * observer takes back exactly the unused units — an `onRefund` observer must skip its own
+     * claw-back for such a refund, or the units are taken back twice.
+     */
+    withdrawalId?: string;
 }
 export type DisputePhase = 'opened' | 'funds-withdrawn' | 'funds-reinstated' | 'closed';
 export interface DisputeEvent {
@@ -292,6 +458,64 @@ export interface PaymentFailedEvent {
     nextAttemptAt?: Date;
     eventKey: string;
 }
+/** A consumer's express request was recorded (performance consent or subscription start). */
+export interface ConsentEvent {
+    kind: ConsentKind;
+    consentId: string;
+    entityId: string;
+    profileId?: string;
+    /** The purchases the consent covers (none for a start request, which precedes its purchase). */
+    purchaseIds: string[];
+    planSku?: string;
+    textVersion: string;
+    language: string;
+    decidedAt: Date;
+    expiresAt?: Date;
+    /** `consent:<consentId>`. */
+    eventKey: string;
+}
+/** A withdrawal executed (`refunded`) or left to an operator (`review`). */
+export interface WithdrawalEvent {
+    withdrawalId: string;
+    /** `withdrawal:<withdrawalId>`. */
+    eventKey: string;
+    entityId: string;
+    channel: DeclarationChannel;
+    purchase: PurchaseRef;
+    declaredAt: Date;
+    status: WithdrawalStatus;
+    refund: {
+        amountMinor: number;
+        currency: string;
+        netMinor?: number;
+        refundId?: string;
+        creditNoteId?: string;
+    };
+    /**
+     * The purchase's units as the usage meter read them: `returned` is what the application takes
+     * back (`granted − used`), `null` without a meter.
+     */
+    units: {
+        granted: number;
+        used: number;
+        returned: number;
+    } | null;
+    subscriptionCanceled: boolean;
+}
+/** A cancellation was declared (matched to a subscription or not). */
+export interface CancellationEvent {
+    cancellationId: string;
+    /** `cancellation:<cancellationId>`. */
+    eventKey: string;
+    entityId?: string;
+    matched: boolean;
+    channel: DeclarationChannel;
+    kind: CancellationKind;
+    status: CancellationStatus;
+    subscriptionId?: string;
+    effectiveAt?: Date;
+    declaredAt: Date;
+}
 export interface TopUpCallback {
     (completion: TopUpCompletion, ctx: ApiContext): Promise<void>;
 }
@@ -307,18 +531,37 @@ export interface DisputeCallback {
 export interface PaymentFailedCallback {
     (event: PaymentFailedEvent, ctx: ApiContext): Promise<void>;
 }
-/** Callbacks run sequentially and are awaited; a throw escapes so the paygate retries. */
+export interface ConsentCallback {
+    (event: ConsentEvent, ctx: ApiContext): Promise<void>;
+}
+export interface WithdrawalCallback {
+    (event: WithdrawalEvent, ctx: ApiContext): Promise<void>;
+}
+export interface CancellationCallback {
+    (event: CancellationEvent, ctx: ApiContext): Promise<void>;
+}
+/**
+ * Callbacks run sequentially and are awaited. A paygate callback's throw escapes so the paygate
+ * retries; a consumer-rights callback (`onConsent`, `onWithdrawal`, `onCancellation`) runs AFTER
+ * the records and the paygate steps, and its throw is recorded and retried by `reconcile()`.
+ */
 export interface CompletionObserver extends LazyService {
     onTopUp: (cb: TopUpCallback) => void;
     onSubscription: (cb: SubscriptionCallback) => void;
     onRefund: (cb: RefundCallback) => void;
     onDispute: (cb: DisputeCallback) => void;
     onPaymentFailed: (cb: PaymentFailedCallback) => void;
+    onConsent: (cb: ConsentCallback) => void;
+    onWithdrawal: (cb: WithdrawalCallback) => void;
+    onCancellation: (cb: CancellationCallback) => void;
     propagateTopUp: (completion: TopUpCompletion, ctx: ApiContext) => Promise<void>;
     propagateSubscription: (event: SubscriptionEvent, ctx: ApiContext) => Promise<void>;
     propagateRefund: (event: RefundEvent, ctx: ApiContext) => Promise<void>;
     propagateDispute: (event: DisputeEvent, ctx: ApiContext) => Promise<void>;
     propagatePaymentFailed: (event: PaymentFailedEvent, ctx: ApiContext) => Promise<void>;
+    propagateConsent: (event: ConsentEvent, ctx: ApiContext) => Promise<void>;
+    propagateWithdrawal: (event: WithdrawalEvent, ctx: ApiContext) => Promise<void>;
+    propagateCancellation: (event: CancellationEvent, ctx: ApiContext) => Promise<void>;
 }
 export interface PaygateCustomerRecord extends ResourceRecord {
     paygate: string;
@@ -328,6 +571,10 @@ export interface PaygateCustomerRecord extends ResourceRecord {
     email?: string;
     name?: string;
     taxId?: string;
+    /** The paygate customer's billing address country, as its last webhook stated it. */
+    country?: string;
+    /** The paygate customer's own currency (set by its first subscription or invoice). */
+    currency?: string;
     deletedAt?: Date;
 }
 export interface PaygateCustomerResource extends MongoResource<PaygateCustomerRecord> {
@@ -375,6 +622,18 @@ export interface PaymentSubscriptionRecord extends ResourceRecord {
     lastEventId?: string;
     initialPropagatedAt?: Date;
     propagated?: PropagatedState;
+    /** The subscription's currency (lowercase). */
+    currency?: string;
+    checkoutSessionId?: string;
+    purchaseId?: string;
+    firstInvoiceId?: string;
+    country?: string;
+    email?: string;
+    amountTotalMinor?: number;
+    amountTaxMinor?: number;
+    termsAccepted?: boolean;
+    startRequestId?: string;
+    withdrawnAt?: Date;
 }
 export interface PaymentSubscriptionResource extends MongoResource<PaymentSubscriptionRecord> {
     byExternalId: (externalId: string, paygate: string) => Promise<PaymentSubscriptionRecord | null>;
@@ -405,6 +664,13 @@ export interface PaymentFulfillmentRecord extends ResourceRecord {
     refundedAt?: Date;
     disputedAt?: Date;
     disputeStatus?: string;
+    country?: string;
+    email?: string;
+    profileId?: string;
+    amountTotalMinor?: number;
+    amountTaxMinor?: number;
+    termsAccepted?: boolean;
+    purchaseId?: string;
 }
 export interface PaymentFulfillmentResource extends MongoResource<PaymentFulfillmentRecord> {
     byExternalId: (externalId: string, paygate: string) => Promise<PaymentFulfillmentRecord | null>;
@@ -455,12 +721,35 @@ export interface PaymentUsageCounterRecord extends ResourceRecord {
 }
 export interface PaymentUsageCounterResource extends MongoResource<PaymentUsageCounterRecord> {
 }
+/** One currency option of a synced price. */
+export interface SyncedPriceOption {
+    currency: string;
+    unitAmount: number;
+}
+/** A reusable price as the last sync left it — what `planPrices` and checkout read without Stripe. */
+export interface SyncedPrice {
+    planSku: string;
+    priceId: string;
+    lookupKey: string;
+    /** The default currency and its amount. */
+    currency: string;
+    unitAmount: number;
+    /** `currency_options` besides the default currency. */
+    options: SyncedPriceOption[];
+    taxBehavior?: string;
+    interval?: 'month' | 'year';
+    sourceUnitAmount: number;
+    sourceCurrency: string;
+    syncedAt: Date;
+}
 export interface FingerprintRecord extends ResourceRecord {
     sku: string;
     hash: string;
     productId?: string;
     /** The paygate object the fingerprint describes (a portal configuration id). */
     externalId?: string;
+    /** A product's synced reusable prices. */
+    prices?: SyncedPrice[];
     updatedAt: Date;
 }
 export interface FingerprintResource extends MongoResource<FingerprintRecord> {
@@ -561,5 +850,419 @@ export interface ReconcileAllResult {
     repaired: number;
     failed: number;
 }
+/** Where a billing profile's country came from. */
+export type BillingProfileSource = 'checkout' | 'customer' | 'manual';
+/** One per organization: the billing country fixed at the first purchase (first write wins). */
+export interface BillingProfileRecord extends ResourceRecord {
+    entityId: string;
+    country: string;
+    region: ConsumerRegion;
+    /** The charge currency, fixed with the country. */
+    currency: string;
+    /** The language of the legal copy. */
+    language: string;
+    source: BillingProfileSource;
+    paygate: string;
+    customerId?: string;
+    sessionId?: string;
+    /** The geolocated country of the request that started the locking checkout — VAT evidence. */
+    ipCountry?: string;
+    email?: string;
+    name?: string;
+    /** A business tax id was given at the locking checkout. */
+    business?: boolean;
+    lockedAt: Date;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+export interface BillingProfileResource extends MongoResource<BillingProfileRecord> {
+    byEntity: (entityId: string) => Promise<BillingProfileRecord | null>;
+}
+/**
+ * One purchase — a contract and its withdrawal window: a paid one-time checkout (`top-up`) or a
+ * subscription's first invoice (`subscription`). Renewals are not purchases.
+ */
+export interface PurchaseRecord extends ResourceRecord {
+    /** `stripe:<session id>` (one-time) or `stripe:<subscription id>`. */
+    purchaseId: string;
+    /** `CR-YYMMDD-XXXXXX` — what a consumer quotes. */
+    contractRef: string;
+    entityId: string;
+    kind: PurchaseKind;
+    paygate: string;
+    sessionId?: string;
+    subscriptionId?: string;
+    paymentIntentId?: string;
+    invoiceId?: string;
+    invoiceNumber?: string;
+    invoiceLineId?: string;
+    productSku: string;
+    planSku?: string;
+    profileId?: string;
+    country?: string;
+    region?: ConsumerRegion;
+    ipCountry?: string;
+    inScope: boolean;
+    language: string;
+    email?: string;
+    name?: string;
+    business?: boolean;
+    /** The charge currency. */
+    currency: string;
+    amountSubtotalMinor: number;
+    amountTaxMinor: number;
+    amountTotalMinor: number;
+    presentmentCurrency?: string;
+    presentmentAmountMinor?: number;
+    /** Amount checkout: the net value credited, in `amountCurrency`. */
+    netAmountMinor?: number;
+    amountCurrency?: string;
+    /** Quantity checkout: the units bought. */
+    units?: number;
+    taxBehavior?: string;
+    /**
+     * Stripe's own `consent.terms_of_service` of the checkout — absent when the session did not
+     * collect it (the policy's `checkoutTerms` off, or the fallback of a Dashboard without a terms URL).
+     */
+    termsAccepted?: boolean;
+    textVersion?: string;
+    copyVersion?: string;
+    startRequestId?: string;
+    /** When the consumer expressly requested the services (the start request) — time deductions count from here. */
+    servicesStartedAt?: Date;
+    /** When the confirmation mail was claimed — one claim per purchase, whatever the outcome of the send. */
+    confirmationMailAt?: Date;
+    purchasedAt: Date;
+    /** Exclusive end of the withdrawal window; absent outside the consumer-rights territories. */
+    deadline?: Date;
+    consentId?: string;
+    consentedAt?: Date;
+    withdrawalId?: string;
+    withdrawnAt?: Date;
+    /** Refunded so far on this purchase's payment, tax included. */
+    refundedMinor?: number;
+    /** Set once the whole payment is refunded — the window closes. */
+    refundedAt?: Date;
+    cancellationId?: string;
+    cancelEffectiveAt?: Date;
+    createdAt: Date;
+    updatedAt?: Date;
+}
+export interface PurchaseResource extends MongoResource<PurchaseRecord> {
+    byPurchaseId: (purchaseId: string) => Promise<PurchaseRecord | null>;
+}
+/** The request evidence a consumer act is recorded with (`requestOriginOf`). */
+export interface RequestOrigin {
+    /** `cf-connecting-ip`, else the LAST `x-forwarded-for` entry, else `x-real-ip`, else the socket. */
+    ip?: string;
+    /** The raw `x-forwarded-for` header. */
+    forwardedFor?: string;
+    /** `user-agent`, at most 512 characters. */
+    userAgent?: string;
+    /** `cf-ipcountry`. */
+    ipCountry?: string;
+    acceptLanguage?: string;
+    /** The channel the request came through (`http`, `mcp`, …), when the application knows. */
+    via?: string;
+}
+/** Append-only: one express request — a performance consent or a subscription start request. */
+export interface ConsumerConsentRecord extends ResourceRecord, RequestOrigin {
+    kind: ConsentKind;
+    entityId: string;
+    profileId?: string;
+    /** The person who gave it — the confirmation is mailed here. */
+    name?: string;
+    email?: string;
+    purchaseIds: string[];
+    planSku?: string;
+    /** The plan's name as the statement said it (`{{plan}}`). */
+    planName?: string;
+    textVersion: string;
+    copyVersion: string;
+    /** The language the statement was shown in. */
+    language: string;
+    uiLanguage?: string;
+    trader: string;
+    /** The statement exactly as rendered and recorded. */
+    text: {
+        request: string;
+        acknowledgement: string;
+        checkbox: string;
+    };
+    links: ConsumerRightsLinks;
+    /** The latest deadline among the covered purchases. */
+    deadline?: Date;
+    decidedAt: Date;
+    /** A start request stops being usable at this instant. */
+    expiresAt?: Date;
+}
+export interface ConsumerConsentResource extends MongoResource<ConsumerConsentRecord> {
+}
+/** Append-only: one withdrawal or cancellation declaration, matched to a contract or not. */
+export interface ConsumerDeclarationRecord extends ResourceRecord, RequestOrigin {
+    kind: DeclarationKind;
+    channel: DeclarationChannel;
+    entityId?: string;
+    purchaseId?: string;
+    subscriptionId?: string;
+    /** The contract as the consumer named it. */
+    contractRef?: string;
+    name: string;
+    email: string;
+    cancellationKind?: CancellationKind;
+    reason?: string;
+    effective?: 'earliest' | 'date';
+    requestedDate?: string;
+    language: string;
+    textVersion?: string;
+    copyVersion: string;
+    receivedAt: Date;
+    matched: boolean;
+    profileId?: string;
+    /** A repeated declaration of a contract already withdrawn from: the original's id. */
+    duplicateOf?: string;
+    /** The status decided on receipt (`WithdrawalStatus` / `CancellationStatus`); execution steps are events. */
+    status: string;
+    refundMinor?: number;
+    currency?: string;
+    effectiveAt?: Date;
+}
+export interface ConsumerDeclarationResource extends MongoResource<ConsumerDeclarationRecord> {
+}
+export type ConsumerEventAction = 'mail' | 'computed' | 'meter' | 'refund' | 'credit-note' | 'subscription-cancel' | 'cancel-scheduled' | 'observers' | 'lock' | 'lock-mismatch' | 'relock' | 'unlock' | 'duplicate' | 'checkout-terms-fallback';
+export type ConsumerRecordKind = 'purchase' | 'consent' | 'declaration' | 'profile' | 'checkout';
+/** Append-only: one execution or audit step. */
+export interface ConsumerEventRecord extends ResourceRecord {
+    /** The purchase id, consent id, declaration id, or the entity id of a profile or a checkout. */
+    recordId: string;
+    recordKind: ConsumerRecordKind;
+    entityId?: string;
+    action: ConsumerEventAction;
+    /** The mail kind of a `mail` event; the observer family of an `observers` one. */
+    step?: string;
+    ok: boolean;
+    /** A mail deliberately not sent (a reserved domain, a renderer that suppressed it). */
+    skipped?: boolean;
+    externalId?: string;
+    amountMinor?: number;
+    currency?: string;
+    /** JSON. */
+    detail?: string;
+    error?: string;
+    at: Date;
+}
+export interface ConsumerEventResource extends MongoResource<ConsumerEventRecord> {
+}
+/** What a usage meter is told about the purchase it reads. */
+export interface PurchaseRef {
+    purchaseId: string;
+    kind: PurchaseKind;
+    entityId: string;
+    contractRef: string;
+    productSku: string;
+    planSku?: string;
+    /** One-time purchases: the checkout session id. */
+    sessionId?: string;
+    /** Subscription purchases: the paygate subscription id. */
+    subscriptionId?: string;
+    invoiceId?: string;
+    purchasedAt: Date;
+}
+export interface UsageQuery {
+    entityId: string;
+    purchase: PurchaseRef;
+    /** The purchase's consent — before it the consumer bears no cost; absent: nothing is deductible. */
+    after?: Date;
+    at: Date;
+}
+export interface UsageReading {
+    /** Units the purchase granted. */
+    granted: number;
+    /** Units of it used so far. */
+    used: number;
+    /** Units of it used strictly after `after` (0 without `after`). */
+    usedAfter: number;
+    /** Units of it that paid off an earlier overdraft when it was granted. */
+    settled?: number;
+    /** Units of it already taken back by an earlier (money) refund. */
+    clawed?: number;
+    remaining?: number;
+}
+/**
+ * The application's reading of how much of one purchase was used — for a withdrawal's refund.
+ * The deduction is `usedAfter + settled + clawed`.
+ */
+export interface UsageMeter {
+    used: (ctx: ApiContext, query: UsageQuery) => Promise<UsageReading>;
+}
+/** Who acts: the organization, and the person's prefill. */
+export interface ConsumerSubject {
+    entityId: string;
+    profileId?: string;
+    name?: string;
+    email?: string;
+    /** `public` when an application matched a public declaration to this organization itself. */
+    channel?: DeclarationChannel;
+}
+export type ConsumerMailKind = 'purchase' | 'consent' | 'start' | 'withdrawal' | 'cancellation';
+/** What a consumer-rights mail is rendered from. */
+export interface ConsumerMailData {
+    kind: ConsumerMailKind;
+    /** The purchase id, consent id or declaration id. */
+    recordId: string;
+    entityId?: string;
+    language: string;
+    to: string;
+    name?: string;
+    trader: TraderDef;
+    links: ConsumerRightsLinks;
+    purchase?: PurchaseRecord;
+    purchases?: PurchaseRecord[];
+    consent?: ConsumerConsentRecord;
+    declaration?: ConsumerDeclarationRecord;
+}
+/**
+ * Replace or suppress a consumer-rights mail: answer a message to send it instead, `null` to send
+ * nothing (recorded as skipped), `undefined` to send the rendered one.
+ */
+export type ConsumerMailRenderer = (kind: ConsumerMailKind, data: ConsumerMailData, rendered: MailMessage) => MailMessage | null | undefined | Promise<MailMessage | null | undefined>;
+export interface LockOptions {
+    customerId?: string;
+    sessionId?: string;
+    ipCountry?: string;
+    email?: string;
+    name?: string;
+    business?: boolean;
+    /** The charge currency; default: an active subscription's, else the region's. */
+    currency?: string;
+    language?: string;
+    /** `manual` only: replace an existing lock (audited as a `relock` event). */
+    force?: boolean;
+    by?: string;
+    reason?: string;
+}
+/** Who removes a lock, and why — kept on the `unlock` event. */
+export interface UnlockOptions {
+    by?: string;
+    reason?: string;
+}
+export interface ConsumerReconcileOptions {
+    /** How far back declarations, mails and observers are retried. Default 30 days. */
+    since?: Date;
+    /** The most items per step. Default 50. */
+    limit?: number;
+}
+export interface ConsumerReconcileResult {
+    retried: number;
+    mailed: number;
+    observed: number;
+    backfilled: number;
+    locked: number;
+    failed: number;
+}
+/**
+ * Lazy: reachable while the application is still being wired (`useMeter`, `useMailRenderer` before
+ * the context initializes); the gateway's initialization initializes it at boot.
+ */
+export interface ConsumerRightsService extends LazyService {
+    /**
+     * `false`: every paygate-calling method (`withdraw`, `cancel`, `reconcile`'s paygate steps) refuses.
+     * An explicit `manage` of `appendConsumerRights` wins over the gateway's, whatever the order.
+     */
+    readonly managed: boolean;
+    policy: () => Promise<ConsumerRightsPolicy | null>;
+    /** The locked billing profile, or `null`. */
+    profile: (entityId: string) => Promise<BillingProfileView | null>;
+    /** Lock the billing country; the first write wins unless a `manual` lock is `force`d. */
+    lock: (entityId: string, country: string, source: BillingProfileSource, opts?: LockOptions) => Promise<BillingProfileView>;
+    /**
+     * An operator removes the lock: the profile is deleted and an `unlock` event keeps it. No lazy lock
+     * from the paygate customer follows (checkout, reconcile); the next completed purchase locks again.
+     * @returns the profile as it was, or `null` when nothing was locked
+     */
+    unlock: (entityId: string, opts?: UnlockOptions) => Promise<BillingProfileView | null>;
+    purchases: (entityId: string, opts?: {
+        open?: boolean;
+        at?: Date;
+    }) => Promise<PurchaseView[]>;
+    consentView: (entityId: string, at?: Date) => Promise<PerformanceConsentView>;
+    /** @throws PerformanceConsentRequired (428) for a stale text version */
+    recordConsent: (subject: ConsumerSubject, body: PerformanceConsentBody, origin?: RequestOrigin) => Promise<PerformanceConsentResponse>;
+    /** @throws PerformanceConsentRequired while an open in-scope window has no consent */
+    assertConsent: (entityId: string, at?: Date) => Promise<void>;
+    startView: (entityId: string, planSku: string, opts?: {
+        language?: string;
+    }) => Promise<SubscriptionStartView>;
+    /** @throws SubscriptionStartRequired (428) for a stale text version */
+    /** `plan`: the plan's short name the statement says (default: its localized catalogue title). */
+    recordStartRequest: (subject: ConsumerSubject, body: SubscriptionStartBody, origin?: RequestOrigin, opts?: {
+        plan?: string;
+    }) => Promise<SubscriptionStartResponse>;
+    /**
+     * The fresh start request bound to this entity and plan, or `null` when none is required.
+     * @throws SubscriptionStartRequired
+     */
+    assertStartRequest: (entityId: string, planSku: string, startRequestId?: string) => Promise<ConsumerConsentRecord | null>;
+    withdrawalCandidates: (entityId: string, subject?: Partial<ConsumerSubject>) => Promise<WithdrawalCandidateList>;
+    /** `subject: null` — the public function: matched by contract reference and e-mail, never disclosed. */
+    withdraw: (subject: ConsumerSubject | null, body: WithdrawalBody, origin?: RequestOrigin) => Promise<WithdrawalReceipt>;
+    cancel: (subject: ConsumerSubject | null, body: CancellationBody, origin?: RequestOrigin) => Promise<CancellationReceipt>;
+    useMeter: (meter: UsageMeter | null) => void;
+    useMailRenderer: (renderer: ConsumerMailRenderer | null) => void;
+    usageMeter: () => UsageMeter | null;
+    mailRenderer: () => ConsumerMailRenderer | null;
+    /** Retry refunds, credit notes, cancellations, mails and observers; backfill purchases and legacy locks. */
+    reconcile: (opts?: ConsumerReconcileOptions) => Promise<ConsumerReconcileResult>;
+}
+/**
+ * `appendConsumerRights` options. `manage`, `usage` and `stripe` apply to the service whenever the
+ * call comes — before or after the gateway registered it; the resources' `dbAlias` / `serviceAlias`
+ * are those of the first registration.
+ */
+export interface ConsumerRightsOptions {
+    /**
+     * `false` in a process that never talks to the paygate (reads and consent asserts only). Absent:
+     * the gateway's `manage`, else managed.
+     */
+    manage?: boolean;
+    /** The application's usage meter; without one a withdrawal is left to an operator (`review`). */
+    usage?: UsageMeter;
+    alias?: string;
+    /** The paygate client; default: the configured Stripe secret. */
+    stripe?: StripeFactory;
+    dbAlias?: string;
+    serviceAlias?: string;
+}
+/** What a public declaration is throttled by. */
+export interface ConsumerThrottleKey {
+    action: 'withdrawal' | 'cancellation';
+    email: string;
+    ip?: string;
+}
+/**
+ * The hooks of `consumerRightsEntrypoints`. Every hook gets the request's context last, so an
+ * application keeps its counters and lookups on the context, never in module state.
+ */
+export interface ConsumerRightsHandlerOptions {
+    /** The organization a signed-in request acts for. Default: `req.entity.id`. */
+    resolveEntity?: (req: AbstractRequest, ctx: ApiContext) => string | null | undefined;
+    /** The person's profile id and prefill. */
+    subjectOf?: (req: AbstractRequest, ctx: ApiContext) => Partial<ConsumerSubject> | Promise<Partial<ConsumerSubject>>;
+    /** Refuse a money-moving act (consent, start, withdraw, cancel) — e.g. an API-key request. */
+    guardMoney?: (req: AbstractRequest, action: string, ctx: ApiContext) => void | Promise<void>;
+    /** REQUIRED when the public subtree is bound: throw (e.g. 429) to refuse a public declaration. */
+    throttle?: (req: AbstractRequest, key: ConsumerThrottleKey, ctx: ApiContext) => void | Promise<void>;
+    /** The request evidence; default `requestOriginOf`. */
+    metaOf?: (req: AbstractRequest, ctx: ApiContext) => RequestOrigin;
+    /** The least time a public declaration takes to answer, matched or not. Default 1000 ms. */
+    publicMinMs?: number;
+    /** The plan's short name a start request's statement says (default: its localized catalogue title). */
+    planNameOf?: (planSku: string, language: string, req: AbstractRequest, ctx: ApiContext) => string | undefined | Promise<string | undefined>;
+    serviceAlias?: string;
+}
+export interface CheckoutReadHandlerOptions {
+    resolveEntity?: (req: AbstractRequest, ctx: ApiContext) => string | null | undefined;
+    gatewayAlias?: string;
+}
 export {};
 //# sourceMappingURL=types.d.ts.map