@riverbankcms/sdk 0.130.0 → 0.132.0

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

@@ -0,0 +1,135 @@
+import { type BookingFlexibleBalanceContractStatus, type NonNegativeCents, type OrderFlexibleBalanceContractId, type OrderInstalmentPlanStatus, type OrderPaymentPlanId, type Result } from '../../../core/src/index';
+import type { OrderPaymentMethod, OrderStatus } from './orderTypes';
+export type PaymentTerms = Readonly<{
+    kind: 'immediate';
+}> | Readonly<{
+    kind: 'manual';
+}> | Readonly<{
+    kind: 'flexible_balance';
+    contractId: OrderFlexibleBalanceContractId;
+    status: BookingFlexibleBalanceContractStatus;
+    dueAt: string | null;
+    upfrontAmountCents: NonNegativeCents;
+}> | Readonly<{
+    kind: 'instalment_plan';
+    paymentPlanId: OrderPaymentPlanId;
+    status: OrderInstalmentPlanStatus;
+    nextDueAt: string | null;
+    nextDueAmountCents: NonNegativeCents | null;
+}>;
+export type OrderPaymentPosition = Readonly<{
+    kind: 'not_required';
+    reason: 'free' | 'waived' | 'pass' | 'membership';
+    totalCents: NonNegativeCents;
+    collectedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    outstandingCents: NonNegativeCents;
+}> | Readonly<{
+    kind: 'waived';
+    totalCents: NonNegativeCents;
+    collectedCents: NonNegativeCents;
+    waivedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    outstandingCents: 0 & NonNegativeCents;
+    terms: PaymentTerms;
+}> | Readonly<{
+    kind: 'unpaid';
+    totalCents: NonNegativeCents;
+    collectedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    outstandingCents: NonNegativeCents;
+    terms: PaymentTerms;
+}> | Readonly<{
+    kind: 'partially_paid';
+    totalCents: NonNegativeCents;
+    collectedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    outstandingCents: NonNegativeCents;
+    terms: PaymentTerms;
+}> | Readonly<{
+    kind: 'paid';
+    totalCents: NonNegativeCents;
+    collectedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    outstandingCents: 0 & NonNegativeCents;
+    settledVia: Exclude<OrderPaymentMethod, 'waived'>;
+    terms: PaymentTerms;
+}> | Readonly<{
+    kind: 'collection_failed';
+    totalCents: NonNegativeCents;
+    collectedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    outstandingCents: NonNegativeCents;
+    terms: PaymentTerms;
+}> | Readonly<{
+    kind: 'refunded';
+    totalCents: NonNegativeCents;
+    collectedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    outstandingCents: 0 & NonNegativeCents;
+    terms: PaymentTerms;
+}> | Readonly<{
+    kind: 'cancelled';
+    totalCents: NonNegativeCents;
+    collectedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    outstandingCents: 0 & NonNegativeCents;
+    terms: PaymentTerms;
+}>;
+export type OrderPaymentPositionInconsistency = Readonly<{
+    kind: 'paid_exceeds_collectable';
+}> | Readonly<{
+    kind: 'refunded_exceeds_collected';
+}> | Readonly<{
+    kind: 'projection_receipt_mismatch';
+    projection: 'flexible_balance' | 'instalment_plan';
+}> | Readonly<{
+    kind: 'conflicting_payment_terms';
+}> | Readonly<{
+    kind: 'managed_terms_for_non_monetary_order';
+}>;
+export type OrderPaymentPositionInput = Readonly<{
+    status: OrderStatus;
+    paymentMethod: OrderPaymentMethod;
+    grandTotalCents: NonNegativeCents;
+    paidCents: NonNegativeCents;
+    waivedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    flexibleBalance: Readonly<{
+        contractId: OrderFlexibleBalanceContractId;
+        status: BookingFlexibleBalanceContractStatus;
+        remainingBalanceCents: NonNegativeCents;
+        dueAt: string | null;
+        upfrontAmountCents: NonNegativeCents;
+    }> | null;
+    instalmentPlan: Readonly<{
+        paymentPlanId: OrderPaymentPlanId;
+        status: OrderInstalmentPlanStatus;
+        remainingBalanceCents: NonNegativeCents;
+        nextDueAt: string | null;
+        nextDueAmountCents: NonNegativeCents | null;
+    }> | null;
+    hasCollectionFailure?: boolean;
+}>;
+export declare function calculateOrderBalanceDueCents(input: Readonly<{
+    grandTotalCents: NonNegativeCents;
+    paidCents: NonNegativeCents;
+    waivedCents?: NonNegativeCents;
+}>): Result<NonNegativeCents, Extract<OrderPaymentPositionInconsistency, {
+    kind: 'paid_exceeds_collectable';
+}>>;
+export declare function deriveOrderPaymentPosition(input: OrderPaymentPositionInput): Result<OrderPaymentPosition, OrderPaymentPositionInconsistency>;
+export type PaymentPresentation = Readonly<{
+    tone: 'neutral' | 'positive' | 'warning' | 'critical';
+    label: 'Not required' | 'Waived' | 'Unpaid' | 'Partially paid' | 'Paid' | 'Payment failed' | 'Refunded' | 'Cancelled';
+    collectedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+    outstandingCents: NonNegativeCents;
+    dueAt: string | null;
+    nextDueAt: string | null;
+}>;
+export declare function buildPaymentPresentation(position: OrderPaymentPosition): PaymentPresentation;
+export declare function hasOnlineOrderPaymentPath(input: Readonly<{
+    position: OrderPaymentPosition;
+    paymentMethod: OrderPaymentMethod;
+}>): boolean;

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

@@ -0,0 +1,102 @@
+import type { AttendeeId } from '../../../core/src/index';
+import type { AppointmentOrderItemMetadata, CourseEnrollmentOrderItemMetadata, EventTicketOrderItemMetadata, MembershipOrderItemMetadata, PassOrderItemMetadata, ProductOrderItemMetadata } from './orderItemMetadata';
+import type { OrderItemReconciliationState, OrderItemCommitState } from './orderTypes';
+/**
+ * Structural input records for pure order-planning helpers.
+ *
+ * Dashboard OrderItemRecord rows satisfy this shape, but this package keeps the
+ * boundary structural so commerce planning code does not depend on dashboard DB
+ * helper types. Tests and non-dashboard callers can provide the same domain
+ * facts without pulling in the app's data-access layer.
+ */
+type OrderItemPlanningBase = Readonly<{
+    id: string;
+    orderId: string;
+    siteId: string;
+    quantity: number;
+    subtotalCents: number | null;
+    discountCents: number | null;
+    creditCents: number | null;
+    netTotalCents: number | null;
+    totalCents: number | null;
+    refundedCents: number | null;
+    unitPriceCents: number | null;
+    createdAt: string;
+    fulfilledAt: string | null;
+    fulfillmentClaimedAt: string | null;
+    fulfillmentClaimToken: string | null;
+    commitState: OrderItemCommitState;
+    reconciliationState: OrderItemReconciliationState;
+    cancelledAt: string | null;
+    cancelledReason: string | null;
+    cancellationCategory: string | null;
+    cancellationInternalNote: string | null;
+}>;
+export type EventTicketOrderItemPlanningRecord = OrderItemPlanningBase & Readonly<{
+    kind: 'event_ticket';
+    metadata: EventTicketOrderItemMetadata;
+    eventAttendeeId: AttendeeId | null;
+    productId: null;
+    productVariantId: null;
+    customerPassId: null;
+    courseEnrollmentId: null;
+    appointmentId: null;
+    customerMembershipId: null;
+}>;
+export type ProductOrderItemPlanningRecord = OrderItemPlanningBase & Readonly<{
+    kind: 'product';
+    metadata: ProductOrderItemMetadata;
+    productId: string;
+    productVariantId: string | null;
+    eventAttendeeId: null;
+    customerPassId: null;
+    courseEnrollmentId: null;
+    appointmentId: null;
+    customerMembershipId: null;
+}>;
+export type PassOrderItemPlanningRecord = OrderItemPlanningBase & Readonly<{
+    kind: 'pass';
+    metadata: PassOrderItemMetadata;
+    customerPassId: string | null;
+    eventAttendeeId: AttendeeId | null;
+    productId: null;
+    productVariantId: null;
+    courseEnrollmentId: null;
+    appointmentId: null;
+    customerMembershipId: null;
+}>;
+export type CourseEnrollmentOrderItemPlanningRecord = OrderItemPlanningBase & Readonly<{
+    kind: 'course_enrollment';
+    metadata: CourseEnrollmentOrderItemMetadata;
+    courseEnrollmentId: string | null;
+    eventAttendeeId: null;
+    productId: null;
+    productVariantId: null;
+    customerPassId: null;
+    appointmentId: null;
+    customerMembershipId: null;
+}>;
+export type AppointmentOrderItemPlanningRecord = OrderItemPlanningBase & Readonly<{
+    kind: 'appointment';
+    metadata: AppointmentOrderItemMetadata;
+    appointmentId: string | null;
+    eventAttendeeId: null;
+    productId: null;
+    productVariantId: null;
+    customerPassId: string | null;
+    courseEnrollmentId: null;
+    customerMembershipId: null;
+}>;
+export type MembershipOrderItemPlanningRecord = OrderItemPlanningBase & Readonly<{
+    kind: 'membership';
+    metadata: MembershipOrderItemMetadata;
+    customerMembershipId: string | null;
+    eventAttendeeId: AttendeeId | null;
+    productId: null;
+    productVariantId: null;
+    customerPassId: null;
+    courseEnrollmentId: null;
+    appointmentId: null;
+}>;
+export type OrderItemPlanningRecord = EventTicketOrderItemPlanningRecord | ProductOrderItemPlanningRecord | PassOrderItemPlanningRecord | CourseEnrollmentOrderItemPlanningRecord | AppointmentOrderItemPlanningRecord | MembershipOrderItemPlanningRecord;
+export {};

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

@@ -0,0 +1,50 @@
+import { type OrderItemId, type NonNegativeCents, type Result } from '../../../core/src/index';
+export type OrderRefundLineInput = Readonly<{
+    orderItemId: OrderItemId;
+    netTotalCents: NonNegativeCents;
+    alreadyRefundedCents?: NonNegativeCents;
+}>;
+export type RequestedOrderLineRefund = Readonly<{
+    orderItemId: OrderItemId;
+    amountCents: NonNegativeCents;
+}>;
+export type PlannedOrderLineRefund = Readonly<{
+    orderItemId: OrderItemId;
+    requestedCents: NonNegativeCents;
+    refundableRemainingCents: NonNegativeCents;
+    appliedCents: NonNegativeCents;
+}>;
+export type OrderRefundPlan = Readonly<{
+    lines: PlannedOrderLineRefund[];
+    requestedTotalCents: NonNegativeCents;
+    appliedTotalCents: NonNegativeCents;
+    nextRefundedCents: NonNegativeCents;
+    nextStatus: 'partially_refunded' | 'refunded' | null;
+}>;
+export type SettledOrderRefundLine = Readonly<{
+    orderItemId: OrderItemId;
+    requestedCents: NonNegativeCents;
+    appliedCents: NonNegativeCents;
+}>;
+export type SettledOrderRefundPlan = Readonly<{
+    lines: SettledOrderRefundLine[];
+    refundedTotalCents: NonNegativeCents;
+}>;
+export declare function planOrderRefund(options: {
+    paidCents: NonNegativeCents;
+    currentRefundedCents: NonNegativeCents;
+    lines: ReadonlyArray<OrderRefundLineInput>;
+    requestedLineRefunds: ReadonlyArray<RequestedOrderLineRefund>;
+}): Result<OrderRefundPlan, string>;
+export declare function planOrderRefundSummaryUpdate(options: {
+    paidCents: NonNegativeCents;
+    currentRefundedCents: NonNegativeCents;
+    nextRefundedCents: NonNegativeCents;
+}): Result<Readonly<{
+    refundedCents: NonNegativeCents;
+    nextStatus: 'partially_refunded' | 'refunded' | null;
+}>, string>;
+export declare function settleOrderRefundPlan(options: {
+    planned: OrderRefundPlan;
+    actualRefundedCents: NonNegativeCents;
+}): Result<SettledOrderRefundPlan, string>;

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

@@ -0,0 +1,36 @@
+import { type NonNegativeCents, type Result } from '../../../core/src/index';
+import type { OrderItemKind } from './orderTypes';
+export declare const ORDER_REFUND_MODES: readonly ["refund_only", "refund_and_revoke"];
+export type OrderRefundMode = (typeof ORDER_REFUND_MODES)[number];
+export declare const ORDER_REFUND_ENTITLEMENT_ACTION_STATUSES: readonly ["not_requested", "pending", "succeeded", "reconciliation_needed"];
+export type OrderRefundEntitlementActionStatus = (typeof ORDER_REFUND_ENTITLEMENT_ACTION_STATUSES)[number];
+export type OrderRefundRevocationCandidate = Readonly<{
+    orderItemId: string;
+    kind: OrderItemKind;
+    refundableRemainingCents: NonNegativeCents;
+    plannedAppliedCents: NonNegativeCents;
+}>;
+export type PlannedOrderRefundEntitlementAction = Readonly<{
+    refundMode: 'refund_only';
+    entitlementActionStatus: 'not_requested';
+    revokedOrderItemIds: readonly [];
+}> | Readonly<{
+    refundMode: 'refund_and_revoke';
+    entitlementActionStatus: 'pending';
+    revokedOrderItemIds: readonly string[];
+}>;
+export declare function planOrderRefundEntitlementAction(options: {
+    refundMode: OrderRefundMode;
+    lines: ReadonlyArray<OrderRefundRevocationCandidate>;
+}): Result<PlannedOrderRefundEntitlementAction, string>;
+export declare function settleOrderRefundEntitlementAction(options: {
+    planned: PlannedOrderRefundEntitlementAction;
+    settledLines: ReadonlyArray<{
+        orderItemId: string;
+        appliedCents: NonNegativeCents;
+    }>;
+    plannedLines: ReadonlyArray<{
+        orderItemId: string;
+        refundableRemainingCents: NonNegativeCents;
+    }>;
+}): Result<readonly string[], string>;

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

@@ -0,0 +1,23 @@
+import { type Cents, type NonNegativeCents } from '../../../core/src/index';
+export type OrderGrandTotalSource = Readonly<{
+    subtotalCents: NonNegativeCents;
+    discountCents: NonNegativeCents;
+    taxCents: NonNegativeCents;
+    shippingCents: NonNegativeCents;
+}>;
+export type OrderReceiptTotalSource = OrderGrandTotalSource & Readonly<{
+    creditCents: NonNegativeCents;
+}>;
+export type RawOrderGrandTotalSource = Readonly<{
+    subtotalCents: number;
+    discountCents: number;
+    taxCents: number;
+    shippingCents: number;
+}>;
+export type RawOrderReceiptTotalSource = RawOrderGrandTotalSource & Readonly<{
+    creditCents: number;
+}>;
+export declare function brandOrderGrandTotalSource(source: RawOrderGrandTotalSource): OrderGrandTotalSource;
+export declare function brandOrderReceiptTotalSource(source: RawOrderReceiptTotalSource): OrderReceiptTotalSource;
+export declare function computeOrderGrandTotalCents(order: OrderGrandTotalSource): Cents;
+export declare function computeOrderReceiptTotalCents(order: OrderReceiptTotalSource): NonNegativeCents;

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

@@ -0,0 +1,39 @@
+export declare const ORDER_STATUSES: readonly ["pending", "paid", "partially_refunded", "refunded", "failed", "cancelled"];
+export type OrderStatus = (typeof ORDER_STATUSES)[number];
+export declare function isOrderStatus(value: string): value is OrderStatus;
+export declare const ORDER_PAYMENT_METHODS: readonly ["stripe", "store_credit", "mixed", "pass_redemption", "membership_access", "free", "manual", "waived"];
+export type OrderPaymentMethod = (typeof ORDER_PAYMENT_METHODS)[number];
+export declare function isOrderPaymentMethod(value: string): value is OrderPaymentMethod;
+export declare const CHECKOUT_COMMIT_STATES: readonly ["pending", "committing", "committed", "compensated"];
+export type CheckoutCommitState = (typeof CHECKOUT_COMMIT_STATES)[number];
+export declare function isCheckoutCommitState(value: string): value is CheckoutCommitState;
+export declare const ORDER_CHECKOUT_RECONCILIATION_STATES: readonly ["not_needed", "evidence_pending", "needed"];
+export type OrderCheckoutReconciliationState = (typeof ORDER_CHECKOUT_RECONCILIATION_STATES)[number];
+export declare function isOrderCheckoutReconciliationState(value: string): value is OrderCheckoutReconciliationState;
+export declare const ORDER_ITEM_RECONCILIATION_STATES: readonly ["not_needed", "needed"];
+export type OrderItemReconciliationState = (typeof ORDER_ITEM_RECONCILIATION_STATES)[number];
+export declare function isOrderItemReconciliationState(value: string): value is OrderItemReconciliationState;
+export declare const ORDER_ITEM_COMMIT_STATES: readonly ["pending", "committed", "compensated"];
+export type OrderItemCommitState = (typeof ORDER_ITEM_COMMIT_STATES)[number];
+export declare function isOrderItemCommitState(value: string): value is OrderItemCommitState;
+export declare const RESERVATION_FINALIZATION_STATES: readonly ["not_applicable", "reserved", "consumed", "released"];
+export type ReservationFinalizationState = (typeof RESERVATION_FINALIZATION_STATES)[number];
+export declare function isReservationFinalizationState(value: string): value is ReservationFinalizationState;
+export type CheckoutPaymentRail = 'bypass' | 'stripe';
+export type CheckoutCommitFailureStep = 'credit_consumption' | 'membership_provision' | 'fulfillment' | 'discount_redemption' | 'payment_record';
+export type CheckoutCompensationDecision = Readonly<{
+    kind: 'release_reservations';
+    reason: string;
+}> | Readonly<{
+    kind: 'compensate_order';
+    reason: string;
+}> | Readonly<{
+    kind: 'mark_reconciliation_needed';
+    reason: string;
+}>;
+export declare const DISCOUNT_REDEMPTION_STATUSES: readonly ["pending", "redeemed", "released", "expired"];
+export type DiscountRedemptionStatus = (typeof DISCOUNT_REDEMPTION_STATUSES)[number];
+export declare function isDiscountRedemptionStatus(value: string): value is DiscountRedemptionStatus;
+export declare const ORDER_ITEM_KINDS: readonly ["event_ticket", "product", "pass", "course_enrollment", "appointment", "membership"];
+export type OrderItemKind = (typeof ORDER_ITEM_KINDS)[number];
+export declare function isOrderItemKind(value: string): value is OrderItemKind;

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

@@ -0,0 +1 @@
+export declare function isPendingOrderCheckoutSessionClaim(stripeCheckoutSessionId: string | null): boolean;

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

@@ -0,0 +1,27 @@
+import { type Result, type CheckoutLineId } from '../../../core/src/index';
+import { type RefundableLineSettlement } from './settlement';
+import { type PositiveCheckoutQuantity } from './checkoutQuantity';
+export type PersistedCheckoutLineKind = 'event_ticket' | 'product' | 'pass' | 'course_enrollment' | 'appointment' | 'membership';
+export type PersistedCheckoutLineInput = Readonly<{
+    id: string;
+    kind: PersistedCheckoutLineKind;
+    quantity: number;
+    subtotalCents: number | null;
+    discountCents: number | null;
+    creditCents: number | null;
+    netTotalCents: number | null;
+    totalCents: number | null;
+    metadata: Readonly<{
+        checkoutLineId?: CheckoutLineId;
+        displayName?: string;
+    }>;
+}>;
+export type PersistedCheckoutLine = Readonly<{
+    orderItemId: string;
+    checkoutLineId: CheckoutLineId | null;
+    kind: PersistedCheckoutLineKind;
+    quantity: PositiveCheckoutQuantity;
+    displayName: string;
+    settlement: RefundableLineSettlement;
+}>;
+export declare function projectPersistedCheckoutLines(items: ReadonlyArray<PersistedCheckoutLineInput>): Result<readonly PersistedCheckoutLine[], string>;

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

@@ -0,0 +1,86 @@
+import { type BookingDepositRefundPolicy, type BookingInstalmentPlanConfig, type NonNegativeCents } from '../../../core/src/index';
+import type { OrderPaymentPurpose } from './orderPaymentReceipt';
+export type ProtectedDepositPolicySubject = Readonly<{
+    kind: 'none';
+}> | Readonly<{
+    kind: 'protected_deposit';
+    sourceKind: 'flexible_balance' | 'instalment_plan';
+    protectedDepositAmountCents: NonNegativeCents;
+    depositRefundability: BookingDepositRefundPolicy;
+}>;
+export type ProtectedDepositRefundExposure = Readonly<{
+    subject: ProtectedDepositPolicySubject;
+    totalRemainingRefundableCents: NonNegativeCents;
+    policyRefundableCents: NonNegativeCents;
+    protectedDepositRemainingCents: NonNegativeCents;
+}>;
+export type ProtectedDepositRefundRequest = Readonly<{
+    kind: 'full_remaining';
+}> | Readonly<{
+    kind: 'partial_amount';
+    amountCents: NonNegativeCents;
+}>;
+export type AdminProtectedDepositRefundDecision = Readonly<{
+    kind: 'allowed';
+    requestedAmountCents: NonNegativeCents;
+    canonicalRemainingRefundableCents: NonNegativeCents;
+    touchesProtectedDeposit: boolean;
+    exposure: ProtectedDepositRefundExposure;
+}> | Readonly<{
+    kind: 'blocked';
+    errorCode: 'already_refunded' | 'amount_exceeds_remaining';
+    errorMessage: string;
+    requestedAmountCents: NonNegativeCents;
+    exposure: ProtectedDepositRefundExposure;
+}> | Readonly<{
+    kind: 'admin_override_required';
+    errorCode: 'deposit_refund_override_required';
+    errorMessage: string;
+    requestedAmountCents: NonNegativeCents;
+    exposure: ProtectedDepositRefundExposure;
+}>;
+export type PolicyOnlyProtectedDepositRefundDecision = Readonly<{
+    kind: 'allowed';
+    requestedAmountCents: NonNegativeCents;
+    canonicalRemainingRefundableCents: NonNegativeCents;
+    exposure: ProtectedDepositRefundExposure;
+}> | Readonly<{
+    kind: 'blocked';
+    errorCode: 'already_refunded' | 'amount_exceeds_remaining' | 'non_refundable_deposit_remaining';
+    errorMessage: string;
+    requestedAmountCents: NonNegativeCents;
+    exposure: ProtectedDepositRefundExposure;
+}>;
+export declare function buildProtectedDepositPolicySubjectFromFlexibleBalance(input: Readonly<{
+    upfrontAmountCents: NonNegativeCents;
+    depositRefundability: BookingDepositRefundPolicy;
+}>): ProtectedDepositPolicySubject;
+export declare function buildProtectedDepositPolicySubjectFromInstalmentPlan(plan: BookingInstalmentPlanConfig): ProtectedDepositPolicySubject;
+export declare function calculateProtectedDepositRefundExposure(input: Readonly<{
+    subject: ProtectedDepositPolicySubject;
+    itemTotalCents: NonNegativeCents;
+    itemRefundedCents: NonNegativeCents;
+    collectedRemainingCents: NonNegativeCents;
+}>): ProtectedDepositRefundExposure;
+/**
+ * Calculates policy exposure for one receipt allocation.
+ *
+ * A protected deposit is collected by the initial-checkout receipt. Later
+ * paydowns and instalments therefore remain independently refundable even
+ * while the entity still has a non-refundable deposit balance.
+ */
+export declare function calculateReceiptProtectedDepositRefundExposure(input: Readonly<{
+    subject: ProtectedDepositPolicySubject;
+    receiptPurpose: OrderPaymentPurpose['kind'];
+    allocatedCents: NonNegativeCents;
+    refundedCents: NonNegativeCents;
+}>): ProtectedDepositRefundExposure;
+export declare function planAdminProtectedDepositRefund(input: Readonly<{
+    exposure: ProtectedDepositRefundExposure;
+    request: ProtectedDepositRefundRequest;
+    allowProtectedDepositOverride: boolean;
+}>): AdminProtectedDepositRefundDecision;
+export declare function planPolicyOnlyProtectedDepositRefund(input: Readonly<{
+    exposure: ProtectedDepositRefundExposure;
+    request: ProtectedDepositRefundRequest;
+}>): PolicyOnlyProtectedDepositRefundDecision;

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

@@ -0,0 +1,8 @@
+export type ShopRefundablePaymentMethod = 'stripe' | 'mixed' | 'store_credit';
+/**
+ * Whether an order's payment method supports refunds through the shop refund flow.
+ *
+ * Pass redemption, membership access, and free orders cannot be refunded
+ * through Stripe or site credit — they need domain-specific handling.
+ */
+export declare function isShopRefundablePaymentMethod(paymentMethod: string): paymentMethod is ShopRefundablePaymentMethod;

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

@@ -0,0 +1,40 @@
+import { type NonNegativeCents, type Result } from '../../../core/src/index';
+/**
+ * Typed result of a rail-aware refund split.
+ * Prevents confusing cash/credit amounts at call sites.
+ */
+export type RefundRailSplit = Readonly<{
+    cashCents: NonNegativeCents;
+    creditCents: NonNegativeCents;
+}>;
+type RefundLineAllocation = Readonly<{
+    orderItemId: string;
+    appliedCents: number;
+}>;
+/** Minimal shape of a refund record for rail-aware splitting. */
+type RefundWithAllocations = Readonly<{
+    refundRail: 'cash' | 'credit' | 'mixed';
+    lineAllocations: ReadonlyArray<RefundLineAllocation>;
+}>;
+/**
+ * For mixed-payment items, compute remaining refundable amount per rail.
+ * Must account for prior refunds that already consumed part of each rail.
+ *
+ * The allocation order (credit before cash) is an accounting convention
+ * that determines *how much* goes to each rail — it does NOT imply
+ * execution order. The caller decides execution order (typically cash
+ * first so Stripe settles before issuing site credit).
+ *
+ * Pure function — no DB calls. Testable with just numbers.
+ */
+export declare function computeRailAwareRefundSplit(originalCashCents: NonNegativeCents, originalCreditCents: NonNegativeCents, priorCashRefunded: NonNegativeCents, priorCreditRefunded: NonNegativeCents, totalRefundCents: NonNegativeCents): RefundRailSplit;
+/**
+ * Summarize prior successful refunds by rail for a specific order item.
+ * Reads from line_allocations in order_refunds records.
+ *
+ * Pure function — just array reduction.
+ */
+export declare function summarizePriorRefundsByRail(refunds: ReadonlyArray<RefundWithAllocations>, orderItemId: string): Result<RefundRailSplit, Readonly<{
+    kind: 'mixed_rail_attribution_missing';
+}>>;
+export {};

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

@@ -0,0 +1,2 @@
+import { type Result } from '../../../core/src/index';
+export declare function traverseResult<TValue, TError>(results: readonly Result<TValue, TError>[]): Result<readonly TValue[], TError>;

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

@@ -0,0 +1,97 @@
+import { type Brand, type NonNegativeCents, type Result } from '../../../core/src/index';
+export type CurrencyCode = Brand<string, 'CurrencyCode'>;
+export type SubtotalCents = Brand<number, 'SubtotalCents'>;
+export type DiscountCents = Brand<number, 'DiscountCents'>;
+export type CreditAppliedCents = Brand<number, 'CreditAppliedCents'>;
+export type StripeChargeCents = Brand<number, 'StripeChargeCents'>;
+export type RefundedCents = Brand<number, 'RefundedCents'>;
+export type RefundableTotalCents = Brand<number, 'RefundableTotalCents'>;
+export type Money<C extends CurrencyCode = CurrencyCode> = Readonly<{
+    amountCents: NonNegativeCents;
+    currency: C;
+}>;
+export type CurrencyValidationResult = {
+    ok: true;
+    currency: CurrencyCode;
+} | {
+    ok: false;
+    reason: 'empty_cart' | 'mixed_currency' | 'invalid_currency';
+    currencies: string[];
+};
+export type AllocationInput<TLineId extends string = string> = {
+    lineId: TLineId;
+    basisCents: NonNegativeCents;
+    maxReducibleCents: NonNegativeCents;
+};
+export type LineAllocation<TLineId extends string = string> = {
+    lineId: TLineId;
+    amountCents: NonNegativeCents;
+};
+export type AllocationResult<TLineId extends string = string> = {
+    requestedCents: NonNegativeCents;
+    appliedCents: NonNegativeCents;
+    allocations: LineAllocation<TLineId>[];
+};
+export type SettledOrderLine = {
+    lineId: string;
+    subtotalCents: NonNegativeCents;
+    discountCents: NonNegativeCents;
+    creditCents: NonNegativeCents;
+    netTotalCents: NonNegativeCents;
+};
+export type LineSettlementBreakdown = Readonly<{
+    subtotalCents: SubtotalCents;
+    discountCents: DiscountCents;
+    creditAppliedCents: CreditAppliedCents;
+    stripeChargeCents: StripeChargeCents;
+}>;
+export type LineSettlementMoneyField = 'subtotalCents' | 'discountCents' | 'creditAppliedCents' | 'stripeChargeCents' | 'alreadyRefundedCents';
+export type LineSettlementBreakdownError<TLineId extends string = string> = Readonly<{
+    _tag: 'invalid_line_money';
+    lineId: TLineId;
+    field: LineSettlementMoneyField;
+    message: string;
+}> | Readonly<{
+    _tag: 'inconsistent_line_totals';
+    lineId: TLineId;
+    message: string;
+}>;
+export type RefundableLineSettlementError<TLineId extends string = string> = LineSettlementBreakdownError<TLineId> | Readonly<{
+    _tag: 'refunded_exceeds_refundable_total';
+    lineId: TLineId;
+    message: string;
+}>;
+export type RefundableLineSettlement = Readonly<{
+    line: LineSettlementBreakdown;
+    refundableTotalCents: RefundableTotalCents;
+    alreadyRefundedCents: RefundedCents;
+}>;
+export declare function normalizeCurrencyCode(raw: string): CurrencyCode;
+export declare function toSubtotalCents(raw: number): SubtotalCents;
+export declare function toDiscountCents(raw: number): DiscountCents;
+export declare function toCreditAppliedCents(raw: number): CreditAppliedCents;
+export declare function toStripeChargeCents(raw: number): StripeChargeCents;
+export declare function toRefundedCents(raw: number): RefundedCents;
+export declare function toRefundableTotalCents(raw: number): RefundableTotalCents;
+export declare function money<C extends CurrencyCode>(amountCents: number, currency: C): Money<C>;
+export declare function buildLineSettlementBreakdown<TLineId extends string>(options: Readonly<{
+    lineId: TLineId;
+    subtotalCents: number;
+    discountCents: number;
+    creditAppliedCents: number;
+    stripeChargeCents: number;
+}>): Result<LineSettlementBreakdown, LineSettlementBreakdownError<TLineId>>;
+export declare function buildRefundableLineSettlement<TLineId extends string>(options: Readonly<{
+    lineId: TLineId;
+    subtotalCents: number;
+    discountCents: number;
+    creditAppliedCents: number;
+    stripeChargeCents: number;
+    alreadyRefundedCents: number;
+}>): Result<RefundableLineSettlement, RefundableLineSettlementError<TLineId>>;
+export declare function refundableRemainingCents(settlement: RefundableLineSettlement): NonNegativeCents;
+export declare function ensureSingleCurrency(lines: ReadonlyArray<{
+    currency: string;
+}>): CurrencyValidationResult;
+export declare function allocateReductionCents<TLineId extends string = string>(inputs: ReadonlyArray<AllocationInput<TLineId>>, requestedCents: number): AllocationResult<TLineId>;
+export declare function assertSettledOrderLineInvariants(lines: ReadonlyArray<SettledOrderLine>): void;