@openlup/platform 0.26.0 → 0.28.0

package/src/commerce/contracts/order.ts

@@ -0,0 +1,44 @@
+import type { CartStatus, CheckoutStatus, OrderDraftStatus, OrderStatus, PaymentStatus } from "./state.js";
+
+export interface CartDraft<Line, Currency> {
+  id: string;
+  status: CartStatus;
+  lines: Line[];
+  currency: Currency;
+}
+
+export interface CheckoutSessionPlaceholder {
+  id: string;
+  cartId: string;
+  status: CheckoutStatus;
+  redirectUrl: string | null;
+  paymentProviderSessionId: string | null;
+}
+
+export interface OrderDraftSummary<Quote, Version extends string> {
+  orderId: string;
+  status: OrderDraftStatus;
+  paymentStatus: "not_started";
+  idempotencyKey: string;
+  quoteSnapshot: {
+    contractVersion: Version;
+    quote: Quote;
+  };
+  replayed: boolean;
+}
+
+export interface OrderSummary<Line, Money> {
+  id: string;
+  status: OrderStatus;
+  paymentStatus: PaymentStatus;
+  total: Money | null;
+  lines: Line[];
+}
+
+export interface PaymentSummary<Money> {
+  id: string;
+  orderId: string;
+  status: PaymentStatus;
+  amount: Money | null;
+  providerReference: string | null;
+}

package/src/commerce/contracts/orderMoney.ts

@@ -0,0 +1,75 @@
+export type OrderMoneyIssueCode =
+  | "allocated_discount_mismatch"
+  | "catalog_subtotal_mismatch"
+  | "effective_subtotal_mismatch"
+  | "header_equation_mismatch"
+  | "item_catalog_equation_mismatch"
+  | "item_catalog_money_out_of_range"
+  | "item_discount_out_of_range"
+  | "item_effective_money_out_of_range"
+  | "item_gross_equation_mismatch"
+  | "item_net_vat_mismatch"
+  | "item_quantity_out_of_range"
+  | "item_vat_rate_out_of_range"
+  | "missing_item_canonical_money"
+  | "mixed_vat_rates"
+  | "product_discount_out_of_range"
+  | "shipping_discount_out_of_range"
+  | "tax_total_mismatch"
+  | "total_positions_mismatch";
+
+export interface OrderMoneyHeaderRow {
+  id?: string;
+  currency: string;
+  subtotal_cents: number;
+  discount_cents: number;
+  shipping_cents: number;
+  shipping_discount_cents: number;
+  tax_cents: number;
+  total_cents: number;
+}
+
+export interface OrderMoneyItemRow {
+  id?: string;
+  quantity: number;
+  unit_price_cents: number;
+  total_cents: number;
+  discount_allocated_cents: number | null | undefined;
+  effective_total_cents: number | null | undefined;
+  effective_net_cents: number | null | undefined;
+  vat_rate_bps: number;
+}
+
+export interface CanonicalOrderMoneyLine {
+  id: string | null;
+  quantity: number;
+  catalogUnit: number;
+  catalogTotal: number;
+  discountAllocated: number;
+  effectiveGross: number;
+  effectiveNet: number;
+  vatRateBps: number;
+}
+
+export interface CanonicalOrderMoney {
+  orderId: string | null;
+  currency: string;
+  subtotal: number;
+  productDiscount: number;
+  shippingGross: number;
+  shippingDiscount: number;
+  shippingEffective: number;
+  tax: number;
+  total: number;
+  lines: CanonicalOrderMoneyLine[];
+  validationScope: "full" | "header";
+  reconciled: boolean;
+  issueCodes: OrderMoneyIssueCode[];
+}
+
+export interface OrderMoneyDiagnostic {
+  event: "commerce_order_money_unreconciled";
+  orderId: string | null;
+  validationScope: CanonicalOrderMoney["validationScope"];
+  issueCodes: OrderMoneyIssueCode[];
+}

package/src/commerce/contracts/ports.ts

@@ -0,0 +1,124 @@
+import type { AsyncCheckoutStatus, CheckoutKind } from "./index.js";
+
+export interface ConfiguratorIntentPersistencePort<Request, Response> {
+  persistIntent(
+    request: Request,
+  ): Promise<Response>;
+  /**
+   * Resolve the identity already provisioned under a COMPLETED idempotency key,
+   * or null when none exists. Lets checkout recover the `clientId` when
+   * `persistIntent` raises an idempotency conflict (same key, mutated payload) so
+   * the client's in-flight order can be resumed instead of surfacing a
+   * transient-looking error. Optional: adapters that cannot read back the
+   * completed row simply omit it and the caller falls back to a 409.
+   */
+  findCompletedIdentity?(
+    idempotencyKey: string,
+  ): Promise<Response | null>;
+}
+
+export interface CommerceRecommendationPort<Request, Response> {
+  recommend(request: Request): Promise<Response>;
+}
+
+export interface CommerceProductCompatibilityPort<Request, Response> {
+  getCompatibility(
+    request: Request,
+  ): Promise<Response>;
+}
+
+export interface CommerceCustomerDefaultsReadPort<Snapshot> {
+  getCustomerDefaultsSnapshot(input: {
+    clientId: string;
+    checkoutKind: CheckoutKind;
+  }): Promise<Snapshot | null>;
+}
+
+export interface CommerceCheckoutResumeDraftUpsertInput<Section, State> {
+  tokenHash: string;
+  idempotencyKeyHash: string | null;
+  lastSectionId: Section;
+  draftState: State;
+  expiresAt: string;
+  now: string;
+}
+
+export interface CommerceCheckoutResumeDraftReadInput {
+  tokenHash: string;
+  now: string;
+}
+
+export interface CommerceCheckoutResumeDraftPort<Section, State, Draft> {
+  upsertDraft(input: CommerceCheckoutResumeDraftUpsertInput<Section, State>): Promise<Draft>;
+  readDraftByTokenHash(input: CommerceCheckoutResumeDraftReadInput): Promise<Draft | null>;
+}
+
+/**
+ * Server-resolved options for the order draft. Passed OUT-OF-BAND by the caller
+ * (orchestration -> provisioned.clientId; standalone route -> none/null) — NEVER
+ * sourced from the client request body — so the persisted client_id (which the
+ * outbox dispatcher resolves into an email recipient) cannot be forged.
+ */
+export interface CreateOrderDraftOptions {
+  clientId?: string | null;
+}
+
+export interface CommerceOrderDraftWritePort<Request, Response> {
+  createOrderDraft(
+    request: Request,
+    options?: CreateOrderDraftOptions,
+  ): Promise<Response>;
+}
+
+/**
+ * A still-in-flight order found for a client, for the checkout handler's
+ * duplicate-charge guard. `status` is always an in-flight `AsyncCheckoutStatus`.
+ */
+export interface ResumableOrderSnapshot {
+  orderId: string;
+  paymentIntentId: string;
+  status: AsyncCheckoutStatus;
+  metadata?: Record<string, unknown> | null;
+  /**
+   * True when the submitting journey PRODUCED this order — a cart edit, not a
+   * cross-device return. Never resume one: superseding re-prices the cart.
+   */
+  sameJourney: boolean;
+}
+
+export interface CommerceResumableOrderReadPort {
+  /**
+   * Newest still-resumable order for `clientId` within `withinMinutes`, or null.
+   * Resumable = payment neither settled nor terminally failed, so a charge may
+   * be in flight and re-submitting would double-charge; a paid/dead order is NOT
+   * returned. `journeyKey` is resolved here to set `sameJourney`.
+   */
+  findResumableOrderForClient(input: {
+    clientId: string;
+    withinMinutes: number;
+    now: Date;
+    journeyKey: string;
+  }): Promise<ResumableOrderSnapshot | null>;
+}
+
+
+/** Neutral sizing seam; the host defines demand units and line names. */
+export interface CommercePackageSizingPort<Input, Result> {
+  recomputeQuantities(input: Input): Promise<Result>;
+  eligibleVariantIds(): Promise<Set<string>>;
+}
+
+export type CheckoutOfferResolution = { kind: "bound"; offerVersion: string } | { kind: "refused"; reason: string };
+/** Offer policy binds or refuses an opaque client ask; evidence is server minted. No executor is included. */
+export interface CheckoutOfferPolicyPort<Intent, Quote> {
+  resolve(input: { intent: Intent; checkoutKind: CheckoutKind }): Promise<CheckoutOfferResolution>;
+  evidence(input: { intent: Intent; offerVersion: string; quote: Quote }): Promise<Record<string, unknown>>;
+}
+
+/** Shared journey projection; pricing and host metadata types are supplied by composition. */
+export interface CheckoutJourney<Request, Policy> {
+  idempotencyKey: string;
+  contactEmail: string;
+  createQuoteRequest: () => Request;
+  createRuntimeMetadata: (pricingPolicy?: Policy) => Record<string, unknown>;
+}

package/src/commerce/contracts/recovery.ts

@@ -0,0 +1,24 @@
+export type RecoveryDestinationIntent =
+  | "checkout_recovery"
+  | "account_payment_recovery"
+  | "customer_dashboard"
+  | "fresh_checkout";
+
+export type RecoveryDestinationState =
+  | "recoverable"
+  | "unrecoverable"
+  | "terminal_expired";
+
+export type RecoveryDestinationSource =
+  | "checkout_recovery"
+  | "subscription_dunning"
+  | "checkout_expired";
+
+export interface RecoveryDestinationPolicyInput {
+  state: RecoveryDestinationState;
+  source: RecoveryDestinationSource;
+  orderMode?: "one_time_order" | "subscription_cycle" | null;
+  hasOrderSubscription?: boolean;
+  requestedSubscriptionContext?: boolean;
+  clientHasLiveOrPendingSubscription?: boolean;
+}

package/src/commerce/contracts/runtimePorts.ts

@@ -0,0 +1,201 @@
+export interface CommercePaymentRuntimeVocabulary {
+  currency: string; intentStatus: string; executionProvider: string; executionAttemptStatus: string;
+  nextActionKind: string; attemptStatus: string; targetKind: string;
+}
+
+export interface FinalizedCheckoutOrderItem {
+  orderItemId: string;
+  skuId: string;
+  sku: string;
+  quantity: number;
+}
+
+export interface FinalizedCheckoutOrder<Currency> {
+  orderId: string;
+  orderRef: string;
+  mode: "one_time" | "subscription_cycle";
+  clientId: string;
+  shippingAddressId: string;
+  subscriptionId: string | null;
+  subscriptionCycleId: string | null;
+  total: { amountMinor: number; currency: Currency };
+  items: FinalizedCheckoutOrderItem[];
+  replayed: boolean;
+}
+
+export interface CommerceCheckoutRuntimeOrderPort<Request, Order> {
+  finalizeOrderForCheckout(
+    request: Request,
+  ): Promise<Order>;
+}
+
+export interface InventoryCheckoutReservationPort<Order, PaymentStatus, Reservation> {
+  reserveOrderItems(input: {
+    idempotencyKey: string;
+    order: Order;
+    paymentStatus: PaymentStatus;
+    metadata?: Record<string, unknown>;
+  }): Promise<Reservation[]>;
+  releaseOrderReservations(input: {
+    idempotencyKey: string;
+    orderId: string;
+    reason: string;
+  }): Promise<{ releasedCount: number }>;
+}
+
+export interface PaymentControlRuntimePort<V extends CommercePaymentRuntimeVocabulary, Result extends { resultStatus: string }, Evidence = never> {
+  createIntent(input: {
+    idempotencyKey: string;
+    targetKind: V["targetKind"];
+    orderId: string;
+    subscriptionId: string | null;
+    subscriptionCycleId: string | null;
+    amountMinor: number;
+    currency: V["currency"];
+    metadata: Record<string, unknown>;
+  }): Promise<{
+    paymentIntentId: string;
+    paymentId: string;
+    status: V["intentStatus"];
+    replayed: boolean;
+  }>;
+  recordAttempt(input: {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    provider: V["executionProvider"];
+    providerAttemptId: string | null;
+    providerSessionId: string | null;
+    attemptStatus: V["executionAttemptStatus"];
+    nextActionKind: V["nextActionKind"] | null;
+    requestPayload: Record<string, unknown>;
+    responsePayload: Record<string, unknown>;
+  }): Promise<{
+    paymentAttemptId: string;
+    status: V["attemptStatus"];
+    replayed: boolean;
+  }>;
+  applyResult(input: Result): Promise<{
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    paymentId: string;
+    orderId: string;
+    status: Result["resultStatus"];
+    kind: string;
+    replayed: boolean;
+  }>;
+  reopenInteractivePreparedAttempt?(input: {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    expectedOrderId: string;
+    expectedSubscriptionId: string | null;
+    expectedSubscriptionCycleId: string | null;
+    evidence: Evidence;
+  }): Promise<{
+    paymentAttemptId: string;
+    paymentIntentId: string;
+    paymentAttemptStatus: "failed";
+    paymentIntentStatus: "failed";
+    replayed: boolean;
+  }>;
+}
+
+export interface InteractivePreparedAttemptRuntimePort<V extends CommercePaymentRuntimeVocabulary, Result extends { resultStatus: string }, Evidence> extends PaymentControlRuntimePort<V, Result, Evidence> {
+  reopenInteractivePreparedAttempt(input: {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    expectedOrderId: string;
+    expectedSubscriptionId: string | null;
+    expectedSubscriptionCycleId: string | null;
+    evidence: Evidence;
+  }): Promise<{
+    paymentAttemptId: string;
+    paymentIntentId: string;
+    paymentAttemptStatus: "failed";
+    paymentIntentStatus: "failed";
+    replayed: boolean;
+  }>;
+}
+
+export interface PreparedProviderAttemptRuntimePort<V extends CommercePaymentRuntimeVocabulary, Result extends { resultStatus: string }, Evidence = never> extends PaymentControlRuntimePort<V, Result, Evidence> {
+  prepareProviderAttempt(input: {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    provider: V["executionProvider"];
+    providerIdempotencyKey: string;
+    providerRequestFingerprint: string;
+    providerFlow: string;
+    paymentMethodRef?: string | null;
+    requestPayload: Record<string, unknown>;
+  }): Promise<{
+    paymentAttemptId: string;
+    status: V["attemptStatus"];
+    replayed: boolean;
+    providerAttemptId: string | null;
+    providerSessionId: string | null;
+    nextActionKind: V["nextActionKind"] | null;
+  }>;
+  finalizeProviderAttempt(input: {
+    idempotencyKey: string;
+    paymentIntentId: string;
+    paymentAttemptId: string;
+    providerIdempotencyKey: string;
+    providerRequestFingerprint: string;
+    providerAttemptId: string | null;
+    providerSessionId: string | null;
+    attemptStatus: V["executionAttemptStatus"];
+    nextActionKind: V["nextActionKind"] | null;
+    requestPayload: Record<string, unknown>;
+    responsePayload: Record<string, unknown>;
+  }): Promise<{
+    paymentAttemptId: string;
+    status: V["attemptStatus"];
+    replayed: boolean;
+    providerAttemptId: string | null;
+    providerSessionId: string | null;
+    nextActionKind: V["nextActionKind"] | null;
+  }>;
+}
+
+export interface CommerceRuntimeReadinessPort<Readiness> {
+  evaluateOrderReadiness(input: {
+    orderId: string;
+    fallbackOrderItemCount: number | null;
+    allOrderItemsHaveSku: boolean;
+  }): Promise<Readiness>;
+}
+
+export interface CommerceCheckoutRuntimePort<StartRequest, StartResponse, ResultRequest, ResultResponse> {
+  startRuntime(
+    request: StartRequest,
+  ): Promise<StartResponse>;
+  applyPaymentResult(
+    request: ResultRequest,
+  ): Promise<ResultResponse>;
+}
+
+export interface CheckoutCommandPersistencePort<Command, Persistence> {
+  persistCheckoutCommand(command: Command): Promise<Persistence>;
+}
+
+export interface CheckoutCommandRuntimeRequest<Command, Provider> {
+  command: Command;
+  paymentProvider: Provider;
+  paymentAttemptSequence?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface CheckoutCommandRuntimeResult<Quote, Persistence, OrderDraft, Runtime, Settlement> {
+  quoteSnapshot: Quote;
+  persistence: Persistence;
+  orderDraft: OrderDraft;
+  runtime: Runtime;
+  settlement: Settlement | null;
+}
+
+export interface CheckoutCommandRuntimePort<Request, Response> {
+  startCheckoutCommand(
+    request: Request,
+  ): Promise<Response>;
+}

package/src/commerce/contracts/state.ts

@@ -0,0 +1,64 @@
+export const CART_STATUSES = ["draft"] as const;
+export const CHECKOUT_STATUSES = ["not_configured", "created", "expired"] as const;
+export const ORDER_DRAFT_STATUSES = ["draft"] as const;
+export const ORDER_STATUSES = [
+  "draft",
+  "pending_payment",
+  "paid",
+  "failed",
+  "expired",
+  "fulfillment_pending",
+  "cancelled",
+  "fulfilled",
+  "refunded",
+] as const;
+export const PAYMENT_STATUSES = [
+  "not_started",
+  "requires_action",
+  "processing",
+  "paid",
+  "failed",
+  "expired",
+  "refunded",
+  "partially_refunded",
+  "disputed",
+] as const;
+export const OMS_FULFILLMENT_BLOCK_REASONS = [
+  "order_not_paid",
+  "payment_not_succeeded",
+  "subscription_cycle_not_paid",
+  "active_hold",
+  "missing_shipping_address",
+  "inventory_review",
+  "risk_review",
+] as const;
+export const OMS_INVENTORY_STATUSES = [
+  "not_checked",
+  "reserved",
+  "missing",
+  "released",
+  "expired",
+  "consumed",
+  "review_required",
+] as const;
+export type CartStatus = (typeof CART_STATUSES)[number];
+export type CheckoutStatus = (typeof CHECKOUT_STATUSES)[number];
+export type OrderDraftStatus = (typeof ORDER_DRAFT_STATUSES)[number];
+export type OrderStatus = (typeof ORDER_STATUSES)[number];
+export type PaymentStatus = (typeof PAYMENT_STATUSES)[number];
+export type OmsFulfillmentBlockReason = (typeof OMS_FULFILLMENT_BLOCK_REASONS)[number];
+export type OmsInventoryStatus = (typeof OMS_INVENTORY_STATUSES)[number];
+
+export interface CommerceFulfillmentEligibilityInput<PaymentState extends string = string, SubscriptionState extends string = string> {
+  orderMode: "one_time" | "subscription_cycle";
+  orderStatus: OrderStatus;
+  paymentStatus: PaymentState;
+  subscriptionCycleStatus?: SubscriptionState | null;
+  activeHoldCount: number;
+  hasShippingAddress: boolean;
+  inventoryStatus?: OmsInventoryStatus;
+  inventoryReviewRequired?: boolean;
+  riskReviewRequired?: boolean;
+}
+
+export type OmsPaymentStatus<PaymentState extends string> = "not_started" | PaymentState;

package/src/commerce/customerDefaultsSnapshotSchemas.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+export const CUSTOMER_DEFAULTS_SNAPSHOT_VERSION =
+  "commerce.customer_defaults_snapshot.v1";
+
+const uuidSchema = z.guid();
+export const commerceCustomerDefaultsRedactedFieldSchema = z.enum([
+  "contact",
+  "orderer_profile",
+  "shipping_address",
+  "billing_address",
+  "delivery_notes",
+  "courier_instructions",
+  "payment_provider",
+  "payment_secret",
+]);
+
+
+export function createCustomerDefaultsSnapshotSchemas<Scope extends z.ZodType, Method extends z.ZodType>(input: {
+  paymentPreferenceScopeSchema: Scope; paymentMethodKindSchema: Method; additionalForbiddenKeys?: readonly string[];
+}) {
+  const customerPaymentPreferenceScopeSchema = input.paymentPreferenceScopeSchema;
+  const customerPaymentMethodKindSchema = input.paymentMethodKindSchema;
+  const forbiddenKeys = new Set([...FORBIDDEN_DEFAULTS_KEYS, ...(input.additionalForbiddenKeys ?? [])]);
+  const commerceCustomerDefaultsSnapshotSchema = z
+    .object({
+      version: z.literal(CUSTOMER_DEFAULTS_SNAPSHOT_VERSION),
+      clientId: uuidSchema,
+      payment: z
+        .object({
+          available: z.boolean(),
+          scope: customerPaymentPreferenceScopeSchema.nullable(),
+          methodKind: customerPaymentMethodKindSchema.nullable(),
+          source: z.literal("customer_payment_preferences"),
+          applied: z.literal(false),
+        })
+        .strict(),
+      addresses: z
+        .object({
+          hasDefaultShippingAddress: z.boolean(),
+          defaultShippingAddressId: uuidSchema.nullable(),
+          hasDefaultBillingAddress: z.boolean(),
+          defaultBillingAddressId: uuidSchema.nullable(),
+          hasDefaultOrdererProfile: z.boolean(),
+          defaultOrdererProfileId: uuidSchema.nullable(),
+          hasDeliveryNotes: z.boolean(),
+          hasCourierInstructions: z.boolean(),
+          source: z.literal("customer_address_profiles"),
+          applied: z.literal(false),
+        })
+        .strict(),
+      redactedFields: z.array(commerceCustomerDefaultsRedactedFieldSchema).default([]),
+    })
+    .strict()
+    .superRefine((snapshot, ctx) => {
+      const forbiddenPath = findForbiddenDefaultsPath(snapshot, [], forbiddenKeys);
+      if (forbiddenPath) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: "customer defaults snapshot cannot include raw PII, address or payment payloads",
+          path: forbiddenPath,
+        });
+      }
+    });
+
+  return { commerceCustomerDefaultsSnapshotSchema };
+}
+
+const FORBIDDEN_DEFAULTS_KEYS = new Set([
+  "name",
+  "firstName",
+  "lastName",
+  "fullName",
+  "email",
+  "phone",
+  "contactPhone",
+  "recipientName",
+  "companyName",
+  "taxId",
+  "line1",
+  "line2",
+  "street",
+  "postalCode",
+  "city",
+  "country",
+  "address",
+  "deliveryNotes",
+  "courierInstructions",
+  "providerPayload",
+  "pspReference",
+  "paymentProvider",
+  "paymentMethodRef",
+  "card",
+  "rawFormPayload",
+]);
+
+function findForbiddenDefaultsPath(
+  value: unknown,
+  path: (string | number)[] = [],
+  forbiddenKeys: ReadonlySet<string> = FORBIDDEN_DEFAULTS_KEYS,
+): (string | number)[] | null {
+  if (!value || typeof value !== "object") return null;
+  if (Array.isArray(value)) {
+    for (const [index, item] of value.entries()) {
+      const result = findForbiddenDefaultsPath(item, [...path, index], forbiddenKeys);
+      if (result) return result;
+    }
+    return null;
+  }
+
+  for (const [key, nestedValue] of Object.entries(value)) {
+    if (forbiddenKeys.has(key)) return [...path, key];
+    const result = findForbiddenDefaultsPath(nestedValue, [...path, key], forbiddenKeys);
+    if (result) return result;
+  }
+
+  return null;
+}

package/src/commerce/errors.ts

@@ -0,0 +1,53 @@
+export class CommerceNotEnabledError extends Error {
+  constructor(feature: "cart" | "checkout" | "order draft" | "order" | "payment") {
+    super(`Commerce ${feature} is not enabled yet`);
+    this.name = "CommerceNotEnabledError";
+  }
+}
+
+export class CommerceOrderDraftConflictError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(
+    message = "Commerce order draft idempotency conflict",
+    details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = "CommerceOrderDraftConflictError";
+    this.details = details;
+  }
+}
+
+
+export class CommerceOrderDraftInvalidResponseError extends Error {
+  constructor() {
+    super("Commerce order draft returned invalid response");
+    this.name = "CommerceOrderDraftInvalidResponseError";
+  }
+}
+
+export class CommerceOrderDraftPersistenceError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(
+    message = "Commerce order draft persistence failed",
+    details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = "CommerceOrderDraftPersistenceError";
+    this.details = details;
+  }
+}
+
+export class CommerceCheckoutResumePersistenceError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(
+    message = "Commerce checkout resume persistence failed",
+    details: Record<string, unknown> = {},
+  ) {
+    super(message);
+    this.name = "CommerceCheckoutResumePersistenceError";
+    this.details = details;
+  }
+}