@riverbankcms/sdk 0.130.0 → 0.132.0

package/dist/_dts/commerce/src/purchase/orderInstalmentAdminSettlement.d.ts

@@ -0,0 +1,43 @@
+import { type NonNegativeCents, type PositiveCents } from "../../../core/src/index";
+import type { OrderInstalmentPhaseKind, OrderInstalmentPlanStatus, OrderInstalmentStatus } from "./orderInstalmentPlan";
+type InstalmentPlanSnapshot = Readonly<{
+    status: OrderInstalmentPlanStatus;
+    remainingBalanceCents: NonNegativeCents;
+}>;
+type InstalmentRowSnapshot = Readonly<{
+    id: string;
+    sequence: number;
+    phaseKind: OrderInstalmentPhaseKind;
+    amountCents: NonNegativeCents;
+    status: OrderInstalmentStatus;
+}>;
+type InstalmentStatusUpdate = Readonly<{
+    instalmentId: string;
+    nextStatus: "paid" | "waived";
+}>;
+export type OrderInstalmentManualPaymentPlan = Readonly<{
+    kind: "already_applied";
+}> | Readonly<{
+    kind: "apply";
+    nextPlanStatus: Extract<OrderInstalmentPlanStatus, "active" | "completed">;
+    nextRemainingBalanceCents: NonNegativeCents;
+    instalmentUpdates: readonly InstalmentStatusUpdate[];
+}>;
+export type OrderInstalmentWaiverPlan = Readonly<{
+    kind: "already_applied";
+}> | Readonly<{
+    kind: "apply";
+    nextPlanStatus: "completed";
+    nextRemainingBalanceCents: NonNegativeCents;
+    instalmentUpdates: readonly InstalmentStatusUpdate[];
+}>;
+export declare function planOrderInstalmentManualPayment(input: Readonly<{
+    paymentPlan: InstalmentPlanSnapshot;
+    instalments: readonly InstalmentRowSnapshot[];
+    amountPaidCents: PositiveCents;
+}>): OrderInstalmentManualPaymentPlan;
+export declare function planOrderInstalmentWaiver(input: Readonly<{
+    paymentPlan: InstalmentPlanSnapshot;
+    instalments: readonly InstalmentRowSnapshot[];
+}>): OrderInstalmentWaiverPlan;
+export {};

package/dist/_dts/commerce/src/purchase/orderInstalmentClosure.d.ts

@@ -0,0 +1,29 @@
+import { type NonNegativeCents } from '../../../core/src/index';
+import type { OrderInstalmentPlanStatus, OrderInstalmentStatus } from './orderInstalmentPlan';
+type InstalmentClosureReason = 'cancelled' | 'refunded';
+type InstalmentClosurePlanSnapshot = Readonly<{
+    status: OrderInstalmentPlanStatus;
+    remainingBalanceCents: NonNegativeCents;
+}>;
+type InstalmentClosureRowSnapshot = Readonly<{
+    id: string;
+    status: OrderInstalmentStatus;
+}>;
+type InstalmentStatusUpdate = Readonly<{
+    instalmentId: string;
+    nextStatus: OrderInstalmentStatus;
+}>;
+export type OrderInstalmentClosurePlan = Readonly<{
+    kind: 'already_applied';
+}> | Readonly<{
+    kind: 'apply';
+    nextPlanStatus: Extract<OrderInstalmentPlanStatus, 'cancelled' | 'refunded'>;
+    nextRemainingBalanceCents: NonNegativeCents;
+    instalmentUpdates: readonly InstalmentStatusUpdate[];
+}>;
+export declare function planOrderInstalmentClosure(input: Readonly<{
+    paymentPlan: InstalmentClosurePlanSnapshot;
+    instalments: readonly InstalmentClosureRowSnapshot[];
+    reason: InstalmentClosureReason;
+}>): OrderInstalmentClosurePlan;
+export {};

package/dist/_dts/commerce/src/purchase/orderInstalmentLifecycle.d.ts

@@ -0,0 +1,44 @@
+import { type NonNegativeCents } from '../../../core/src/index';
+import type { OrderInstalmentPhaseKind, OrderInstalmentPlanStatus, OrderInstalmentStatus } from './orderInstalmentPlan';
+type InstalmentLifecyclePlanSnapshot = Readonly<{
+    status: OrderInstalmentPlanStatus;
+    remainingBalanceCents: NonNegativeCents;
+}>;
+type InstalmentLifecycleRowSnapshot = Readonly<{
+    id: string;
+    sequence: number;
+    phaseKind: OrderInstalmentPhaseKind;
+    amountCents: NonNegativeCents;
+    status: OrderInstalmentStatus;
+    stripeInvoiceId: string | null;
+}>;
+export type ApplyRecurringInstalmentPaymentPlan = Readonly<{
+    kind: 'already_applied';
+    instalmentId: string;
+}> | Readonly<{
+    kind: 'apply_payment';
+    instalmentId: string;
+    nextInstalmentStatus: 'paid';
+    nextPlanStatus: Extract<OrderInstalmentPlanStatus, 'active' | 'completed'>;
+    nextRemainingBalanceCents: NonNegativeCents;
+}>;
+export type ApplyRecurringInstalmentFailurePlan = Readonly<{
+    kind: 'already_applied';
+    instalmentId: string;
+}> | Readonly<{
+    kind: 'apply_failure';
+    instalmentId: string;
+    nextInstalmentStatus: 'failed';
+    nextPlanStatus: 'payment_failed';
+}>;
+export declare function planRecurringInstalmentInvoicePaid(input: Readonly<{
+    paymentPlan: InstalmentLifecyclePlanSnapshot;
+    instalments: readonly InstalmentLifecycleRowSnapshot[];
+    stripeInvoiceId: string;
+    amountPaidCents: NonNegativeCents;
+}>): ApplyRecurringInstalmentPaymentPlan;
+export declare function planRecurringInstalmentInvoiceFailed(input: Readonly<{
+    instalments: readonly InstalmentLifecycleRowSnapshot[];
+    stripeInvoiceId: string;
+}>): ApplyRecurringInstalmentFailurePlan;
+export {};

package/dist/_dts/commerce/src/purchase/orderInstalmentPayoff.d.ts

@@ -0,0 +1,24 @@
+import { type NonNegativeCents } from '../../../core/src/index';
+import type { OrderInstalmentPhaseKind, OrderInstalmentPlanStatus, OrderInstalmentStatus } from './orderInstalmentPlan';
+type InstalmentPayoffPlanSnapshot = Readonly<{
+    status: OrderInstalmentPlanStatus;
+    remainingBalanceCents: NonNegativeCents;
+}>;
+type InstalmentPayoffRowSnapshot = Readonly<{
+    id: string;
+    phaseKind: OrderInstalmentPhaseKind;
+    status: OrderInstalmentStatus;
+}>;
+export type OrderInstalmentPayoffPlan = Readonly<{
+    kind: 'already_applied';
+}> | Readonly<{
+    kind: 'apply';
+    nextPlanStatus: 'cancelled_as_paid_early';
+    nextRemainingBalanceCents: NonNegativeCents;
+    instalmentIdsToCancel: readonly string[];
+}>;
+export declare function planOrderInstalmentPayoff(input: Readonly<{
+    paymentPlan: InstalmentPayoffPlanSnapshot;
+    instalments: readonly InstalmentPayoffRowSnapshot[];
+}>): OrderInstalmentPayoffPlan;
+export {};

package/dist/_dts/commerce/src/purchase/orderInstalmentPlan.d.ts

@@ -0,0 +1,40 @@
+import type { BookingInstalmentPlanConfig, NonNegativeCents, OrderInstalmentPhaseKind, OrderInstalmentPlanStatus, OrderInstalmentStatus } from '../../../core/src/index';
+export type { OrderInstalmentPhaseKind, OrderInstalmentPlanStatus, OrderInstalmentStatus, } from '../../../core/src/index';
+export type OrderInstalmentScheduleRowDraft = Readonly<{
+    sequence: number;
+    phaseKind: OrderInstalmentPhaseKind;
+    dueAt: string;
+    amountCents: NonNegativeCents;
+    status: OrderInstalmentStatus;
+}>;
+export type OrderInstalmentPlanDraft = Readonly<{
+    kind: 'instalment_plan';
+    status: OrderInstalmentPlanStatus;
+    planDefinition: BookingInstalmentPlanConfig;
+    totalCents: NonNegativeCents;
+    initialPaymentCents: NonNegativeCents;
+    remainingBalanceCents: NonNegativeCents;
+    instalments: readonly [
+        OrderInstalmentScheduleRowDraft,
+        ...OrderInstalmentScheduleRowDraft[]
+    ];
+}>;
+export type OrderInstalmentStripeSchedulePhaseDraft = Readonly<{
+    startDateEpoch: number;
+    amountCents: NonNegativeCents;
+    durationInterval: 'day' | 'week' | 'month';
+    durationIntervalCount: number;
+    recurringInterval: 'day' | 'week' | 'month';
+    recurringIntervalCount: number;
+    sequenceStart: number;
+    sequenceEnd: number;
+}>;
+export declare function buildOrderInstalmentPlanDraft(input: Readonly<{
+    anchorAt: string;
+    totalCents: NonNegativeCents;
+    planDefinition: BookingInstalmentPlanConfig;
+}>): OrderInstalmentPlanDraft;
+export declare function buildOrderInstalmentStripeSchedulePhases(input: Readonly<{
+    planDefinition: BookingInstalmentPlanConfig;
+    instalments: readonly OrderInstalmentScheduleRowDraft[];
+}>): readonly [OrderInstalmentStripeSchedulePhaseDraft, ...OrderInstalmentStripeSchedulePhaseDraft[]];

package/dist/_dts/commerce/src/purchase/orderItemMetadata.d.ts

@@ -0,0 +1,151 @@
+import { type BrandedIdParseError, type CheckoutLineId, type CourseId, type CustomerId, type DatedOfferingCapacityHoldAuditRef, type DatedOfferingCapacityHoldId, type EventSeriesId, type EventInstanceId, type OccurrenceId, type PassId, type PricingOptionId, type TicketTypeId, type Result } from '../../../core/src/index';
+import type { OrderItemKind } from './orderTypes';
+export type CheckoutLineMetadata = Readonly<{
+    checkoutLineId?: CheckoutLineId;
+    displayName?: string;
+}>;
+export type StripeBookingCommissionOrderItemMetadata = Readonly<{
+    stripeBookingCommission?: Readonly<{
+        kind: 'application_fee_amount';
+        amountCents: number;
+        percent: number;
+    }>;
+}>;
+export type SlidingScaleOrderItemPricingSnapshot = Readonly<{
+    kind: 'sliding_scale';
+    version: 1;
+    currency: string;
+    minAmount: number;
+    maxAmount: number;
+    suggestedAmount: number | null;
+    chosenAmount: number;
+}>;
+export type BookableOrderItemPricingMetadata = Readonly<{
+    pricing?: SlidingScaleOrderItemPricingSnapshot;
+}>;
+export declare const DATED_OFFERING_ORDER_ITEM_ENGINE_METADATA_KEYS: {
+    readonly contractVersion: "datedOfferingEngineContractVersion";
+    readonly routeKind: "datedOfferingEngineRouteKind";
+    readonly capacityHoldId: "datedOfferingCapacityHoldId";
+    readonly capacityHoldAuditRef: "datedOfferingCapacityHoldAuditRef";
+    readonly courseId: "courseId";
+    readonly customerId: "customerId";
+    readonly eventSeriesId: "eventSeriesId";
+    readonly nonCashProjectionIdempotencyKey: "datedOfferingNonCashProjectionIdempotencyKey";
+};
+export type DatedOfferingOrderItemEngineMetadata = Readonly<{
+    datedOfferingEngineContractVersion: 'shared_v1';
+    datedOfferingEngineRouteKind: 'shared_whole_series_registration';
+    datedOfferingCapacityHoldId: DatedOfferingCapacityHoldId;
+    datedOfferingCapacityHoldAuditRef: DatedOfferingCapacityHoldAuditRef;
+    customerId: CustomerId;
+    eventSeriesId: EventSeriesId;
+}>;
+export type DatedOfferingNonCashOrderItemEngineMetadata = Readonly<{
+    datedOfferingEngineContractVersion: 'shared_v1';
+    datedOfferingEngineRouteKind: 'shared_whole_series_registration';
+    datedOfferingNonCashProjectionIdempotencyKey: string;
+    customerId: CustomerId;
+    eventSeriesId: EventSeriesId;
+}>;
+export type DatedOfferingOrderItemEngineMetadataParseError = Readonly<{
+    kind: 'invalid_engine_contract';
+}> | Readonly<{
+    kind: 'invalid_capacity_hold_id';
+    error: DatedOfferingMetadataRefParseError;
+}> | Readonly<{
+    kind: 'invalid_capacity_hold_audit_ref';
+    error: DatedOfferingMetadataRefParseError;
+}> | Readonly<{
+    kind: 'invalid_customer_id';
+    error: BrandedIdParseError;
+}> | Readonly<{
+    kind: 'invalid_event_series_id';
+    error: BrandedIdParseError;
+}>;
+export type DatedOfferingMetadataRefParseError = Readonly<{
+    kind: 'not_string';
+}> | Readonly<{
+    kind: 'empty_string';
+}> | Readonly<{
+    kind: 'invalid_uuid';
+}>;
+type LegacyDatedOfferingOrderItemEngineMetadata = Readonly<{
+    [TKey in keyof DatedOfferingOrderItemEngineMetadata]?: never;
+}>;
+export type CourseEnrollmentEngineMetadata = (LegacyDatedOfferingOrderItemEngineMetadata & Readonly<{
+    courseId: CourseId;
+}>) | DatedOfferingOrderItemEngineMetadata | DatedOfferingNonCashOrderItemEngineMetadata;
+export type EventTicketOrderItemMetadata = CheckoutLineMetadata & StripeBookingCommissionOrderItemMetadata & BookableOrderItemPricingMetadata & Readonly<{
+    eventSeriesId: string;
+    occurrenceId: OccurrenceId;
+    ticketTypeId?: TicketTypeId;
+    ticketCount: number;
+    attendeeEmail: string;
+    attendeeName: string;
+}>;
+export type ProductOrderItemMetadata = CheckoutLineMetadata & Readonly<{
+    productType?: 'physical' | 'digital';
+    requiresShipping?: boolean;
+}>;
+export type PassBundleFulfillmentMetadata = Readonly<{
+    occurrenceId: OccurrenceId;
+    eventInstanceId: EventInstanceId | null;
+    ticketsCount: number;
+    attendeeEmail: string;
+    attendeeName: string;
+    passName: string;
+}>;
+export type CreditProductUseCase = 'event_pass' | 'appointment_package';
+export declare function normalizeOrderCreditProductUseCase(value: unknown): Result<CreditProductUseCase, string>;
+export type PassOrderItemMetadata = CheckoutLineMetadata & Readonly<{
+    passId: PassId;
+    productUseCase?: CreditProductUseCase;
+    creditsTotal: number;
+    validDays: number | null;
+    bundleFulfillment?: PassBundleFulfillmentMetadata;
+}>;
+export type CourseEnrollmentOrderItemMetadata = CheckoutLineMetadata & StripeBookingCommissionOrderItemMetadata & BookableOrderItemPricingMetadata & CourseEnrollmentEngineMetadata & Readonly<{
+    pricingOptionId?: PricingOptionId;
+    attendeeEmail: string;
+    attendeeName: string;
+}>;
+export declare function parseDatedOfferingOrderItemEngineMetadata(raw: Record<string, unknown>): Result<DatedOfferingOrderItemEngineMetadata, DatedOfferingOrderItemEngineMetadataParseError>;
+export declare function parseDatedOfferingNonCashOrderItemEngineMetadata(raw: Record<string, unknown>): Result<DatedOfferingNonCashOrderItemEngineMetadata, DatedOfferingOrderItemEngineMetadataParseError>;
+export type AppointmentOrderItemMetadata = CheckoutLineMetadata & StripeBookingCommissionOrderItemMetadata & BookableOrderItemPricingMetadata & Readonly<{
+    serviceId: string;
+    resourceId: string;
+    startAt: string;
+    endAt: string;
+    timezone: string;
+    customerEmail: string;
+    customerName: string;
+}>;
+export type MembershipBundleFulfillmentMetadata = Readonly<{
+    occurrenceId: OccurrenceId;
+    ticketsCount: number;
+    attendeeEmail: string;
+    attendeeName: string;
+    membershipName: string;
+}>;
+export type MembershipOrderItemMetadata = CheckoutLineMetadata & Readonly<{
+    bundleFulfillment?: MembershipBundleFulfillmentMetadata;
+}>;
+export type OrderItemMetadataByKind = {
+    event_ticket: EventTicketOrderItemMetadata;
+    product: ProductOrderItemMetadata;
+    pass: PassOrderItemMetadata;
+    course_enrollment: CourseEnrollmentOrderItemMetadata;
+    appointment: AppointmentOrderItemMetadata;
+    membership: MembershipOrderItemMetadata;
+};
+export type OrderItemMetadata = OrderItemMetadataByKind[OrderItemKind];
+export declare function parseStripeBookingCommissionMetadata(raw: Record<string, unknown>): Result<StripeBookingCommissionOrderItemMetadata, string>;
+export declare function parseBookableOrderItemPricingMetadata(raw: Record<string, unknown>): Result<BookableOrderItemPricingMetadata, string>;
+export declare function parseOrderItemMetadata(kind: 'event_ticket', raw: unknown): Result<EventTicketOrderItemMetadata, string>;
+export declare function parseOrderItemMetadata(kind: 'product', raw: unknown): Result<ProductOrderItemMetadata, string>;
+export declare function parseOrderItemMetadata(kind: 'pass', raw: unknown): Result<PassOrderItemMetadata, string>;
+export declare function parseOrderItemMetadata(kind: 'course_enrollment', raw: unknown): Result<CourseEnrollmentOrderItemMetadata, string>;
+export declare function parseOrderItemMetadata(kind: 'appointment', raw: unknown): Result<AppointmentOrderItemMetadata, string>;
+export declare function parseOrderItemMetadata(kind: 'membership', raw: unknown): Result<MembershipOrderItemMetadata, string>;
+export {};

package/dist/_dts/commerce/src/purchase/orderItemSupport.d.ts

@@ -0,0 +1,14 @@
+import type { OrderItemPlanningRecord } from './orderPlanningTypes';
+import type { OrderPaymentMethod } from './orderTypes';
+export type ShopRefundableOrderItem<TItem extends OrderItemPlanningRecord = OrderItemPlanningRecord> = Extract<TItem, {
+    kind: 'product' | 'pass';
+}>;
+export declare function isShopRefundableOrderItem<TItem extends OrderItemPlanningRecord>(item: TItem): item is ShopRefundableOrderItem<TItem>;
+export declare function usesShopRefundFlow<TItem extends OrderItemPlanningRecord>(paymentMethod: OrderPaymentMethod, item: TItem): item is ShopRefundableOrderItem<TItem>;
+export declare function getOrderItemDisplayName(item: Pick<OrderItemPlanningRecord, 'kind' | 'metadata'>): string;
+export declare function effectiveOrderItemNetTotalCents(item: Pick<OrderItemPlanningRecord, 'netTotalCents' | 'totalCents'>): number;
+export declare function isOrderItemShippable(item: OrderItemPlanningRecord): boolean;
+export declare function partitionActiveUnshippedOrderItems<TItem extends OrderItemPlanningRecord>(items: readonly TItem[], shippedQuantityByItemId: ReadonlyMap<string, number>): Readonly<{
+    cancellableItems: readonly TItem[];
+    shippedItems: readonly TItem[];
+}>;

package/dist/_dts/commerce/src/purchase/orderListFilters.d.ts

@@ -0,0 +1,3 @@
+export declare function normalizeOrderListSearchTerm(value: string | null | undefined): string | null;
+export declare function buildOrderListDateFromBoundary(value: string | null | undefined): string | null;
+export declare function buildOrderListDateToBoundary(value: string | null | undefined): string | null;

package/dist/_dts/commerce/src/purchase/orderPaymentLinkPlanning.d.ts

@@ -0,0 +1,60 @@
+import type { BookingFlexibleBalanceContractStatus, NonNegativeCents, OrderFlexibleBalanceContractId, OrderInstalmentPlanStatus, OrderPaymentPlanId } from '../../../core/src/index';
+import type { Result } from '../../../core/src/index';
+import type { OrderHistorySource } from './orderHistorySource';
+import { type OrderPaymentPosition, type OrderPaymentPositionInconsistency } from './orderPaymentState';
+import type { CheckoutCommitState, OrderPaymentMethod, OrderStatus } from './orderTypes';
+export type OrderPaymentLinkUnavailableReason = 'archived_order' | 'order_not_pending' | 'order_not_committed' | 'no_balance_due' | 'payment_path_unavailable' | 'stripe_not_connected' | 'checkout_in_progress';
+export type OrderPaymentReminderUnavailableReason = OrderPaymentLinkUnavailableReason | 'missing_customer_email';
+export type OrderPaymentLinkAvailability = Readonly<{
+    kind: 'available';
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: OrderPaymentLinkUnavailableReason;
+    publicMessage: string;
+    httpStatus: 409 | 422;
+}>;
+export type OrderPaymentReminderAvailability = Readonly<{
+    kind: 'available';
+    recipientEmail: string;
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: OrderPaymentReminderUnavailableReason;
+    publicMessage: string;
+    httpStatus: 409 | 422;
+}>;
+export type OrderPaymentAdminFlexibleBalance = Readonly<{
+    contractId: OrderFlexibleBalanceContractId;
+    status: BookingFlexibleBalanceContractStatus;
+    remainingBalanceCents: NonNegativeCents;
+    dueAt?: string | null;
+    upfrontAmountCents?: NonNegativeCents | null;
+}>;
+export type OrderPaymentAdminInstalmentPlan = Readonly<{
+    paymentPlanId: OrderPaymentPlanId;
+    status: OrderInstalmentPlanStatus;
+    remainingBalanceCents: NonNegativeCents;
+    nextDueAt?: string | null;
+    nextDueAmountCents?: NonNegativeCents | null;
+}>;
+export type OrderPaymentAdminFacts = Readonly<{
+    historySource: OrderHistorySource;
+    status: OrderStatus;
+    commitState: CheckoutCommitState;
+    paymentMethod: OrderPaymentMethod;
+    grandTotalCents: NonNegativeCents;
+    paidCents: NonNegativeCents;
+    waivedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    flexibleBalance: OrderPaymentAdminFlexibleBalance | null;
+    instalmentPlan: OrderPaymentAdminInstalmentPlan | null;
+    stripeCheckoutSessionId: string | null;
+    stripeConnected: boolean;
+    customerEmail: string | null;
+}>;
+export type OrderPaymentAdminProjection = Readonly<{
+    paymentState: OrderPaymentPosition;
+    balanceDueCents: NonNegativeCents;
+    paymentLinkAvailability: OrderPaymentLinkAvailability;
+    paymentReminderAvailability: OrderPaymentReminderAvailability;
+}>;
+export declare function buildOrderPaymentAdminProjection(facts: OrderPaymentAdminFacts): Result<OrderPaymentAdminProjection, OrderPaymentPositionInconsistency>;

package/dist/_dts/commerce/src/purchase/orderPaymentReceipt.d.ts

@@ -0,0 +1,184 @@
+import { type ManualPaymentOperationId, type NonNegativeCents, type OrderFlexibleBalanceContractId, type OrderId, type OrderItemId, type OrderPaymentPlanId, type OrderPaymentPlanInstalmentId, type OrderPaymentReceiptId, type PositiveCents, type Result, type SiteId, type StripeAccountRef, type StripeCheckoutSessionId, type StripeInvoiceId, type StripePaymentIntentRef, type UserId, type UtcIsoDateTimeString } from '../../../core/src/index';
+import { type CurrencyCode } from './settlement';
+export type StripeCheckoutPaymentRail = Readonly<{
+    kind: 'stripe_checkout';
+    stripeAccountRef: StripeAccountRef;
+    checkoutSessionId: StripeCheckoutSessionId;
+    paymentIntentRef: StripePaymentIntentRef;
+    invoiceId: StripeInvoiceId | null;
+}>;
+export type StripeInvoicePaymentRail = Readonly<{
+    kind: 'stripe_invoice';
+    stripeAccountRef: StripeAccountRef;
+    invoiceId: StripeInvoiceId;
+    paymentIntentRef: StripePaymentIntentRef | null;
+}>;
+export type ManualPaymentRail = Readonly<{
+    kind: 'manual';
+    operationId: ManualPaymentOperationId;
+    recordedByUserId: UserId;
+    externalReference: string | null;
+    note: string | null;
+}>;
+export type OrderPaymentRail = StripeCheckoutPaymentRail | StripeInvoicePaymentRail | ManualPaymentRail;
+export type InitialCheckoutPaymentTarget = Readonly<{
+    kind: 'immediate';
+}> | Readonly<{
+    kind: 'flexible_balance';
+    contractId: OrderFlexibleBalanceContractId;
+}> | Readonly<{
+    kind: 'instalment_plan';
+    paymentPlanId: OrderPaymentPlanId;
+}>;
+export type OrderPaymentPurpose = Readonly<{
+    kind: 'initial_checkout';
+    target: InitialCheckoutPaymentTarget;
+}> | Readonly<{
+    kind: 'flexible_balance_paydown';
+    contractId: OrderFlexibleBalanceContractId;
+}> | Readonly<{
+    kind: 'instalment';
+    paymentPlanId: OrderPaymentPlanId;
+    instalmentId: OrderPaymentPlanInstalmentId;
+}> | Readonly<{
+    kind: 'instalment_payoff';
+    paymentPlanId: OrderPaymentPlanId;
+}> | Readonly<{
+    kind: 'subscription_renewal';
+}>;
+export type OrderPaymentReceiptProvenance = 'live' | 'backfilled_exact';
+type SuccessfulOrderPaymentBase = Readonly<{
+    siteId: SiteId;
+    orderId: OrderId;
+    amountCents: PositiveCents;
+    currency: CurrencyCode;
+    paidAt: UtcIsoDateTimeString;
+}>;
+type SuccessfulOrderPaymentDetails = Readonly<{
+    purpose: OrderPaymentPurpose;
+    rail: ManualPaymentRail;
+}> | Readonly<{
+    purpose: Extract<OrderPaymentPurpose, {
+        kind: 'initial_checkout';
+    }>;
+    rail: StripeCheckoutPaymentRail;
+}> | Readonly<{
+    purpose: Extract<OrderPaymentPurpose, {
+        kind: 'flexible_balance_paydown';
+    }>;
+    rail: StripeCheckoutPaymentRail;
+}> | Readonly<{
+    purpose: Extract<OrderPaymentPurpose, {
+        kind: 'instalment';
+    }>;
+    rail: StripeInvoicePaymentRail;
+}> | Readonly<{
+    purpose: Extract<OrderPaymentPurpose, {
+        kind: 'subscription_renewal';
+    }>;
+    rail: StripeInvoicePaymentRail;
+}> | Readonly<{
+    purpose: Extract<OrderPaymentPurpose, {
+        kind: 'instalment_payoff';
+    }>;
+    rail: StripeCheckoutPaymentRail;
+}>;
+export type ApplySuccessfulOrderPayment = SuccessfulOrderPaymentBase & SuccessfulOrderPaymentDetails;
+export type ProviderSuccessfulOrderPayment = Exclude<ApplySuccessfulOrderPayment, Readonly<{
+    rail: ManualPaymentRail;
+}>>;
+export declare function isProviderSuccessfulOrderPayment(command: ApplySuccessfulOrderPayment): command is ProviderSuccessfulOrderPayment;
+export type OrderPaymentReceipt = Readonly<{
+    id: OrderPaymentReceiptId;
+    provenance: OrderPaymentReceiptProvenance;
+    appliedCents: NonNegativeCents;
+    applicationState: 'applied' | 'reconciliation_needed';
+}> & SuccessfulOrderPaymentBase & SuccessfulOrderPaymentDetails;
+export type AppliedOrderPaymentProjection = Readonly<{
+    orderPaidCents: NonNegativeCents;
+    orderStatus: 'pending' | 'paid';
+    contractPaidCents: NonNegativeCents | null;
+    contractRemainingCents: NonNegativeCents | null;
+    planRemainingCents: NonNegativeCents | null;
+}>;
+export type ApplySuccessfulOrderPaymentResult = Readonly<{
+    kind: 'applied' | 'already_applied';
+    receipt: OrderPaymentReceipt;
+    projection: AppliedOrderPaymentProjection;
+}> | Readonly<{
+    kind: 'reconciliation_needed';
+    receipt: OrderPaymentReceipt;
+}>;
+export type ApplySuccessfulOrderPaymentError = Readonly<{
+    kind: 'order_not_found';
+}> | Readonly<{
+    kind: 'payment_identity_conflict';
+    existingReceiptId: OrderPaymentReceiptId;
+}> | Readonly<{
+    kind: 'currency_mismatch';
+}> | Readonly<{
+    kind: 'amount_exceeds_outstanding';
+}> | Readonly<{
+    kind: 'invalid_order_state';
+}> | Readonly<{
+    kind: 'payment_terms_mismatch';
+}> | Readonly<{
+    kind: 'allocation_invariant_failed';
+}> | Readonly<{
+    kind: 'invalid_payment_fact';
+}> | Readonly<{
+    kind: 'concurrent_payment_application';
+}> | Readonly<{
+    kind: 'persistence_failed';
+    cause: unknown;
+}>;
+export declare function purposeFromSuccessfulOrderPayment(command: ApplySuccessfulOrderPayment): OrderPaymentPurpose;
+export type OrderPaymentReceiptAllocationInput = Readonly<{
+    orderItemId: OrderItemId;
+    allocationBasisCents: NonNegativeCents;
+    remainingCashCollectableCents: NonNegativeCents;
+    remainingRecognisableTaxCents: NonNegativeCents;
+}>;
+export type OrderPaymentReceiptAllocation = Readonly<{
+    orderItemId: OrderItemId;
+    amountCents: PositiveCents;
+    allocatedTaxCents: NonNegativeCents;
+}>;
+/**
+ * A receipt application planned against one observed order projection.
+ * The atomic adapter must compare the expected collected amount after taking
+ * the order lock before it is allowed to persist these allocations.
+ */
+export type PlannedOrderPaymentApplication = Readonly<{
+    command: ApplySuccessfulOrderPayment;
+    expectedOrderPaidCents: NonNegativeCents;
+    allocations: readonly OrderPaymentReceiptAllocation[];
+}>;
+export type PlanOrderPaymentReceiptAllocationsError = Readonly<{
+    kind: 'no_collectable_lines';
+}> | Readonly<{
+    kind: 'duplicate_order_item';
+    orderItemId: OrderItemId;
+}> | Readonly<{
+    kind: 'amount_exceeds_remaining';
+    requestedCents: PositiveCents;
+    remainingCents: NonNegativeCents;
+}> | Readonly<{
+    kind: 'allocation_invariant_failed';
+}>;
+export declare function planOrderPaymentReceiptAllocations(input: Readonly<{
+    lines: readonly OrderPaymentReceiptAllocationInput[];
+    amountCents: PositiveCents;
+}>): Result<readonly OrderPaymentReceiptAllocation[], PlanOrderPaymentReceiptAllocationsError>;
+/**
+ * Attribute provider-proven cash that cannot safely advance the obligation.
+ *
+ * Unlike an application plan, attribution deliberately ignores remaining
+ * obligation caps: the full cash movement must stay visible and refundable.
+ * It recognises no tax until an operator reconciles the excess.
+ */
+export declare function planUnappliedOrderPaymentReceiptAllocations(input: Readonly<{
+    lines: readonly OrderPaymentReceiptAllocationInput[];
+    amountCents: PositiveCents;
+}>): Result<readonly OrderPaymentReceiptAllocation[], PlanOrderPaymentReceiptAllocationsError>;
+export {};