@openlup/platform 0.26.0 → 0.27.0

package/src/commerce/outboxOrderDraftEmailPorts.ts

@@ -0,0 +1,241 @@
+
+export const OUTBOX_ORDER_CONFIRMATION_TEMPLATE_SLUG = "commerce-order-confirmation";
+
+export interface OrderRecipient {
+  email: string;
+  firstName: string | null;
+  country?: string | null;
+  contextName?: string | null;
+}
+
+export interface OrderRecipientPort {
+  resolve(orderUuid: string, signal: AbortSignal): Promise<OrderRecipient | null>;
+}
+
+export interface OrderPaymentLifecycleState {
+  orderStatus: string | null;
+  paymentStatus: string | null;
+  paymentUpdatedAt?: string | null;
+  hasPayment: boolean;
+  /** The activation sweep abandoned this order's provisional subscription: it writes
+   * `cancelled`, not `expired`, so the expired-checkout gate needs this to tell a swept
+   * first subscription from any other cancellation. Absent for every one-time order. */
+  subscriptionActivationAbandoned?: boolean;
+}
+
+export interface OrderPaymentLifecyclePort {
+  read(orderUuid: string, signal: AbortSignal): Promise<OrderPaymentLifecycleState | null>;
+}
+
+export interface OrderEmailLineItem {
+  name: string;
+  quantity: number;
+  lineTotalLabel: string;
+}
+
+export interface OrderEmailTotals {
+  subtotalLabel: string | null;
+  discountLabel: string | null;
+  totalLabel: string;
+  firstSubscription?: {
+    discountPercent?: number;
+    catalogLabel: string;
+    productPayableLabel: string;
+    shippingLabel: string | null;
+    shippingFree: boolean;
+  };
+}
+
+export interface OrderConfirmationEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  contextName?: string | null;
+  orderId: string;
+  outboxEventId: string;
+  items: OrderEmailLineItem[];
+  totals: OrderEmailTotals | null;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export interface TransactionalEmailSendOutcome {
+  ok: boolean;
+  messageId: string | null;
+  httpStatus: number;
+  providerError: string | null;
+  aborted: boolean;
+  providerErrorCode?: string | null;
+  /** Terminal intentional non-send; callers must not count it as sent. */
+  skipReason?: "admin_disabled" | "egress_suppressed" | null;
+}
+
+export const OUTBOX_ORDER_PAID_TEMPLATE_SLUG = "commerce-order-paid";
+
+export const OUTBOX_CHECKOUT_RECOVERY_TEMPLATE_SLUG = "commerce-checkout-recovery";
+
+export interface CheckoutRecoveryEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  contextName?: string | null;
+  orderId: string;
+  recoveryToken: string;
+  mode: string;
+  reminderHours: number;
+  linkSource?: "buyer_hatch";
+  outboxEventId: string;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export interface OrderPaidRawLine {
+  /** Frozen historical display label, or null for sparse legacy snapshots. */
+  label: string | null;
+  quantity: number;
+  lineTotalMinor: number;
+}
+
+export interface OrderPaidRawData {
+  currency: string;
+  subtotalMinor: number;
+  discountMinor: number;
+  totalMinor: number;
+  presentation?: unknown;
+  lines: OrderPaidRawLine[];
+}
+
+export interface OrderPaidLinesPort {
+  read(orderUuid: string, signal: AbortSignal): Promise<OrderPaidRawData | null>;
+}
+
+export interface OrderPaidConfirmationEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  contextName?: string | null;
+  orderId: string;
+  mode: string;
+  outboxEventId: string;
+  items: OrderEmailLineItem[];
+  totals: OrderEmailTotals | null;
+  parcelNote?: string | null;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export const OUTBOX_PAYMENT_FAILED_TEMPLATE_SLUG = "commerce-payment-failed";
+
+export interface PaymentFailedEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  orderId: string;
+  amountLabel: string | null;
+  recoveryToken: string;
+  mode: string;
+  outboxEventId: string;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export const OUTBOX_CHECKOUT_EXPIRED_TEMPLATE_SLUG = "commerce-checkout-expired";
+
+export interface CheckoutExpiredEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  orderId: string;
+  amountLabel: string | null;
+  /** Raw checkout-recovery token, emitted only in the outbox payload: the database
+   * stores only its hash, and the host renderer builds the recovery link. */
+  recoveryToken?: string | null;
+  outboxEventId: string;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export const OUTBOX_ORDER_CANCELED_TEMPLATE_SLUG = "commerce-order-canceled";
+
+export interface OrderCanceledEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  orderId: string;
+  amountLabel: string | null;
+  outboxEventId: string;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export const OUTBOX_ORDER_REFUNDED_TEMPLATE_SLUG = "commerce-order-refunded";
+
+export interface OrderRefundedEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  orderId: string;
+  amountLabel: string | null;
+  outboxEventId: string;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export const OUTBOX_SHIPMENT_DISPATCHED_TEMPLATE_SLUG = "commerce-shipment-dispatched";
+
+export interface ShipmentDispatchedEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  contextName?: string | null;
+  orderId: string;
+  trackingNumber: string | null;
+  trackingUrl: string | null;
+  outboxEventId: string;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export const OUTBOX_SHIPMENT_DELIVERED_TEMPLATE_SLUG = "commerce-shipment-delivered";
+
+export interface ShipmentDeliveredEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  contextName?: string | null;
+  orderId: string;
+  outboxEventId: string;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export const OUTBOX_SHIPMENT_EXCEPTION_TEMPLATE_SLUG = "commerce-shipment-exception";
+
+export interface ShipmentExceptionEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  orderId: string;
+  outboxEventId: string;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export const OUTBOX_RETURN_APPROVED_TEMPLATE_SLUG = "commerce-return-approved";
+
+export const OUTBOX_RETURN_REJECTED_TEMPLATE_SLUG = "commerce-return-rejected";
+
+export interface ReturnDecisionEmailInput<Locale extends string = string> {
+  to: string;
+  firstName: string | null;
+  orderId: string;
+  outboxEventId: string;
+  locale?: Locale;
+  signal: AbortSignal;
+}
+
+export interface TransactionalEmailPort<Locale extends string = string> {
+  findExistingSend(templateSlug: string, outboxEventId: string): Promise<boolean>;
+  sendReturnApprovedNotice(input: ReturnDecisionEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendReturnRejectedNotice(input: ReturnDecisionEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendOrderConfirmation(input: OrderConfirmationEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendCheckoutRecovery(input: CheckoutRecoveryEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendOrderPaidConfirmation(input: OrderPaidConfirmationEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendPaymentFailedNotice(input: PaymentFailedEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendCheckoutExpiredNotice(input: CheckoutExpiredEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendOrderCanceledNotice(input: OrderCanceledEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendOrderRefundedNotice(input: OrderRefundedEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendShipmentDispatchedNotice(input: ShipmentDispatchedEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendShipmentDeliveredNotice(input: ShipmentDeliveredEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+  sendShipmentExceptionNotice(input: ShipmentExceptionEmailInput<Locale>): Promise<TransactionalEmailSendOutcome>;
+}

package/src/commerce/paymentContinuation.ts

@@ -0,0 +1,5 @@
+import { z } from "zod";
+
+export const checkoutContinuationJourneyIdSchema = z.string().regex(/^checkout:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
+/** Shared client/server lifetime; terminal payment status still invalidates continuation. */
+export const CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS = 45 * 60;

package/src/commerce/ports.ts

@@ -0,0 +1,7 @@
+/** Host-owned quote options are extended only with a server-bound offer. */
+export type CreateQuoteOptions<Options extends object> = Options & { offerVersion?: string };
+
+export interface CommerceQuotePort<Request, Response, Options extends object> {
+  createQuote(request: Request, options?: CreateQuoteOptions<Options>): Promise<Response>;
+  createServerAuthoritativeQuote?(request: Request, options?: CreateQuoteOptions<Options>): Promise<Response>;
+}

package/src/commerce/recoveryDestination.ts

@@ -0,0 +1,23 @@
+import type { RecoveryDestinationPolicyInput, RecoveryDestinationIntent } from "./contracts/index.js";
+
+export function resolveRecoveryDestination(
+  input: RecoveryDestinationPolicyInput,
+): RecoveryDestinationIntent {
+  if (input.source === "subscription_dunning") return "account_payment_recovery";
+  if (input.state === "recoverable") return "checkout_recovery";
+  if (hasSubscriptionRecoveryContext(input)) return "account_payment_recovery";
+  if (input.state === "terminal_expired") return "fresh_checkout";
+  return "fresh_checkout";
+}
+
+export function hasSubscriptionRecoveryContext(
+  input: Pick<
+    RecoveryDestinationPolicyInput,
+    "orderMode" | "hasOrderSubscription" | "requestedSubscriptionContext" | "clientHasLiveOrPendingSubscription"
+  >,
+): boolean {
+  return input.orderMode === "subscription_cycle" ||
+    input.hasOrderSubscription === true ||
+    input.requestedSubscriptionContext === true ||
+    input.clientHasLiveOrPendingSubscription === true;
+}

package/src/commerce/runtimeErrors.ts

@@ -0,0 +1,19 @@
+export class CommerceRuntimeConflictError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(message = "Commerce runtime conflict", details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = "CommerceRuntimeConflictError";
+    this.details = details;
+  }
+}
+
+export class CommerceRuntimePersistenceError extends Error {
+  readonly details: Record<string, unknown>;
+
+  constructor(message = "Commerce runtime persistence failed", details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = "CommerceRuntimePersistenceError";
+    this.details = details;
+  }
+}

package/src/commerce/salesChannelEnvelope.ts

@@ -0,0 +1,28 @@
+export interface CommerceSalesChannelEnvelope {
+  sourceKind: string | null;
+  sourceChannelSlug: string | null;
+  sourceOrderRef: string | null;
+}
+
+export interface CommerceSalesChannelRow {
+  source_kind?: string | null;
+  source_order_ref?: string | null;
+  sales_channels?: { slug: string | null } | null;
+}
+
+export function projectCommerceSalesChannelEnvelope(row: CommerceSalesChannelRow): CommerceSalesChannelEnvelope {
+  return { sourceKind: row.source_kind ?? null, sourceChannelSlug: row.sales_channels?.slug ?? null,
+    sourceOrderRef: row.source_order_ref ?? null };
+}
+
+/** Host-bound read only; the inventory owner supplies exposure semantics. */
+export type CommerceChannelExposureReadPort = (skuId: string, signal: AbortSignal) => Promise<number>;
+
+export interface OrderBuyerCommsPolicy {
+  sourceKind: string;
+  buyerCommsOwner: string;
+}
+
+export function platformOwnsBuyerEmail(policy: OrderBuyerCommsPolicy | null): boolean {
+  return policy === null || policy.buyerCommsOwner !== "channel";
+}

package/src/commerce/schemas.ts

@@ -0,0 +1,104 @@
+import { z } from "zod";
+import { cartStatusSchema, checkoutStatusSchema, commerceIdempotencyKeySchema, orderDraftStatusSchema, orderStatusSchema, paymentStatusSchema } from "./contractPrimitives.js";
+
+/** Preserve pricing validation and let the host extend cart locale policy. */
+export function createCommerceSchemas<Line extends z.ZodType, Currency extends z.ZodType<string>, Money extends z.ZodType, Quote extends z.ZodType, Version extends string>(input: {
+  cartLineInputSchema: Line; commerceCurrencySchema: Currency; commerceMoneySchema: Money;
+  createQuoteResponseSchema: Quote; contractVersion: Version;
+}) {
+  const { cartLineInputSchema, commerceCurrencySchema, commerceMoneySchema, createQuoteResponseSchema } = input;
+  const createCartRequestSchema = z.object({
+    lines: z.array(cartLineInputSchema).min(1).max(50),
+    clientId: z.string().trim().min(1).optional(),
+  });
+
+  const cartDraftSchema = z.object({
+    id: z.string().regex(/^cart_[a-z0-9-]+$/),
+    status: cartStatusSchema,
+    lines: z.array(cartLineInputSchema).min(1),
+    currency: commerceCurrencySchema,
+  });
+
+  const createCartResponseSchema = z.object({
+    contractVersion: z.literal(input.contractVersion),
+    cart: cartDraftSchema,
+  });
+
+  const createCheckoutRequestSchema = z.object({
+    cartId: z.string().regex(/^cart_[a-z0-9-]+$/),
+    successUrl: z.string().url(),
+    cancelUrl: z.string().url(),
+    idempotencyKey: z.string().trim().min(8).max(120).optional(),
+  });
+
+  const createCheckoutResponseSchema = z
+    .object({
+      contractVersion: z.literal(input.contractVersion),
+      checkout: z.object({
+        id: z.string().regex(/^checkout_[a-z0-9-]+$/),
+        cartId: z.string().regex(/^cart_[a-z0-9-]+$/),
+        status: checkoutStatusSchema,
+        redirectUrl: z.string().url().nullable(),
+        paymentProviderSessionId: z.string().trim().min(1).nullable(),
+      }),
+    })
+    .refine(
+      ({ checkout }) =>
+        checkout.status === "not_configured"
+          ? checkout.redirectUrl === null && checkout.paymentProviderSessionId === null
+          : checkout.redirectUrl !== null,
+      {
+        message: "checkout status must match redirect/provider fields",
+        path: ["checkout"],
+      },
+    );
+
+  const orderDraftSummarySchema = z.object({
+    orderId: z.string().regex(/^order_[a-z0-9-]+$/),
+    status: orderDraftStatusSchema,
+    paymentStatus: z.literal("not_started"),
+    idempotencyKey: commerceIdempotencyKeySchema,
+    quoteSnapshot: createQuoteResponseSchema,
+    replayed: z.boolean(),
+  });
+
+  const createOrderDraftRequestSchema = z.object({
+    idempotencyKey: commerceIdempotencyKeySchema,
+    quoteSnapshot: createQuoteResponseSchema,
+  });
+  // Customer identity is supplied out of band by trusted composition, never
+  // accepted from the public order-draft request body.
+
+  const createOrderDraftResponseSchema = z.object({
+    contractVersion: z.literal(input.contractVersion),
+    orderDraft: orderDraftSummarySchema,
+  });
+
+  const orderSummarySchema = z.object({
+    id: z.string().regex(/^order_[a-z0-9-]+$/),
+    status: orderStatusSchema,
+    paymentStatus: paymentStatusSchema,
+    total: commerceMoneySchema.nullable(),
+    lines: z.array(cartLineInputSchema).min(1),
+  });
+
+  const orderReadResponseSchema = z.object({
+    contractVersion: z.literal(input.contractVersion),
+    order: orderSummarySchema,
+  });
+
+  const paymentSummarySchema = z.object({
+    id: z.string().regex(/^payment_[a-z0-9-]+$/),
+    orderId: z.string().regex(/^order_[a-z0-9-]+$/),
+    status: paymentStatusSchema,
+    amount: commerceMoneySchema.nullable(),
+    providerReference: z.string().trim().min(1).nullable(),
+  });
+
+  const paymentStatusReadResponseSchema = z.object({
+    contractVersion: z.literal(input.contractVersion),
+    payment: paymentSummarySchema,
+  });
+
+  return { createCartRequestSchema, cartDraftSchema, createCartResponseSchema, createCheckoutRequestSchema, createCheckoutResponseSchema, orderDraftSummarySchema, createOrderDraftRequestSchema, createOrderDraftResponseSchema, orderSummarySchema, orderReadResponseSchema, paymentSummarySchema, paymentStatusReadResponseSchema };
+}

package/src/commerce/server/checkoutCompensation.ts

@@ -0,0 +1,49 @@
+import { CommerceRuntimePersistenceError } from "../runtimeErrors.js";
+import type { CheckoutCompensationPort } from "./commerceCheckoutCompensation.js";
+
+export interface CompensationRpcClient {
+  rpc(functionName: string, args: Record<string, unknown>): PromiseLike<{
+    data: unknown;
+    error: { code?: string } | null;
+  }>;
+}
+
+/**
+ * Binds both cancellations to one service-role client. Compositions inject the
+ * result into the inventory reservation port, so the staying domain module
+ * never imports this adapter.
+ */
+export function createCheckoutCompensationRpcAdapter(
+  client: CompensationRpcClient,
+): Pick<CheckoutCompensationPort, "cancelAbandonedOrder" | "cancelUnstartedPromotionOrder"> {
+  return {
+    cancelAbandonedOrder: (input) => cancelAbandonedCheckout(client, input),
+    cancelUnstartedPromotionOrder: (input) => cancelUnstartedPromotionCheckout(client, input),
+  };
+}
+
+export async function cancelAbandonedCheckout(
+  client: CompensationRpcClient,
+  input: Parameters<CheckoutCompensationPort["cancelAbandonedOrder"]>[0],
+): Promise<{ cancelled: boolean }> {
+  const { data, error } = await client.rpc("commerce_cancel_abandoned_checkout", {
+    p_idempotency_key: `${input.idempotencyKey}:abandon`,
+    p_order_id: input.orderId,
+    p_reason: input.reason,
+  });
+  if (error) throw new CommerceRuntimePersistenceError("Checkout cancellation RPC failed", { code: error.code });
+  return { cancelled: (data as Record<string, unknown> | null)?.cancelled === true };
+}
+
+export async function cancelUnstartedPromotionCheckout(
+  client: CompensationRpcClient,
+  input: Parameters<CheckoutCompensationPort["cancelUnstartedPromotionOrder"]>[0],
+): Promise<{ cancelled: boolean }> {
+  const { data, error } = await client.rpc("commerce_cancel_unstarted_promotion_order", {
+    p_idempotency_key: input.idempotencyKey,
+    p_order_id: input.orderId,
+    p_reason: input.reason,
+  });
+  if (error) throw new CommerceRuntimePersistenceError("Promotion cancellation RPC failed", { code: error.code });
+  return { cancelled: data === true };
+}

package/src/commerce/server/checkoutConflictClassifiers.ts

@@ -0,0 +1,53 @@
+import { CheckoutOrchestrationError } from "./commerceCheckoutOrchestrationError.js";
+
+// Classifiers for the conflict outcomes the checkout orchestration can throw at the
+// `start_runtime` stage. Extracted from the handler so the money-path handler stays
+// within the source-size budget; behaviour is unchanged (pure predicates).
+
+export function isStockUnavailableCheckoutConflict(error: unknown): boolean {
+  return (
+    error instanceof CheckoutOrchestrationError &&
+    error.message === "start_runtime: Inventory reservation conflict"
+  );
+}
+
+export function isProviderAttemptInFlightCheckoutConflict(error: unknown): boolean {
+  return (
+    error instanceof CheckoutOrchestrationError &&
+    error.reason === "provider_attempt_in_flight"
+  );
+}
+
+export function isJourneyConsumedCheckoutConflict(error: unknown): boolean {
+  return (
+    error instanceof CheckoutOrchestrationError &&
+    error.reason === "journey_consumed"
+  );
+}
+
+/**
+ * `start_runtime` conflicts that map to an identical `CONFLICT + reason` response with
+ * no compensation side effect — the FE resumes/handles each by its `reason`. Order is
+ * significant and preserved from the original inline branches. Stock-unavailable is
+ * intentionally NOT here: it additionally cancels the abandoned order, so the handler
+ * keeps that branch inline.
+ */
+export const START_RUNTIME_SIMPLE_CONFLICTS: ReadonlyArray<{
+  match: (error: unknown) => boolean;
+  message: string;
+  reason: string;
+}> = [
+  {
+    match: isProviderAttemptInFlightCheckoutConflict,
+    message: "Checkout payment already in flight",
+    reason: "provider_attempt_in_flight",
+  },
+];
+
+/** Scoped semantic details only; raw SQLSTATE does not authorize this classification. */
+export function isInventoryAdmissionBusy(error: unknown): boolean {
+  if (!error || typeof error !== "object" || !("details" in error)) return false;
+  const details = error.details;
+  return !!details && typeof details === "object" && "code" in details && details.code === "55P03"
+    && "reason" in details && ["inventory_admission_busy", "inventory_lock_unavailable"].includes(String(details.reason));
+}

package/src/commerce/server/checkoutExpiredRecoveryPolicy.ts

@@ -0,0 +1,107 @@
+import type { CreateQuoteResponse } from "../../pricing/index.js";
+import type { CheckoutRecoveryOrderSnapshot } from "./checkoutRecoveryOrderPort.js";
+import type { CheckoutRecoveryTokenInspection } from "./checkoutRecoveryToken.js";
+type RecoveryQuoteSnapshot = CreateQuoteResponse & { quote: { context?: { sizeConstraint?: unknown; shippingTerms?: {
+  version: unknown; currency: string; flatMinor: number; freeThresholdMinor: number | null;
+} } } };
+
+export const EXPIRED_CHECKOUT_RECOVERY_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+
+export type ExpiredRecoveryEligibility =
+  | { kind: "eligible" }
+  | { kind: "paid" }
+  | { kind: "cancelled" }
+  | { kind: "unavailable" };
+
+export function createExpiredCheckoutRecoveryPolicy<Order extends CheckoutRecoveryOrderSnapshot<unknown, unknown>>(bindings: {
+  admitsSubscriptionSubject(order: Order): boolean;
+}) {
+  function classifyExpiredRecovery(input: {
+    inspection: CheckoutRecoveryTokenInspection | null;
+    order: Order | null;
+    now: Date;
+  }): ExpiredRecoveryEligibility {
+    const { inspection, order, now } = input;
+    if (!inspection || !order || inspection.clientId !== order.clientId) return { kind: "unavailable" };
+    if (order.status === "paid") return { kind: "paid" };
+    if (inspection.tokenState === "revoked" || inspection.tokenState === "used") {
+      return { kind: "unavailable" };
+    }
+    return classifyOrderRecoveryEligibility(order, now);
+  }
+
+  /**
+   * The ORDER half of the same decision, without a token in hand.
+   *
+   * `classifyExpiredRecovery` answers "may this bearer redeem?"; two of its checks
+   * (the token exists, belongs to this order's client, and is neither revoked nor
+   * used) are about the bearer and the rest are about the order. Only the second
+   * half can be asked BEFORE a token exists, which is exactly the question the
+   * operator's mint asks, so it lives here as one function both callers share.
+   *
+   * ⛔ Do not fork it. Mint-side eligibility drifting from redeem-side eligibility
+   * is how support hands a customer a link that the redeem rail then refuses — a
+   * dead link is worse than no button at all.
+   */
+  function classifyOrderRecoveryEligibility(
+    order: Order | null,
+    now: Date,
+  ): ExpiredRecoveryEligibility {
+    if (!order) return { kind: "unavailable" };
+    if (order.status === "paid") return { kind: "paid" };
+    const createdAt = Date.parse(order.createdAt);
+    if (!Number.isFinite(createdAt) || now.getTime() - createdAt > EXPIRED_CHECKOUT_RECOVERY_WINDOW_MS) {
+      return { kind: "unavailable" };
+    }
+    if (order.status === "cancelled" && !order.technicallyExpired) return { kind: "cancelled" };
+    // Recreation is only safe after a canonical expiry transition has also
+    // released the source reservation. `pending_payment` plus expired-looking
+    // metadata is an inconsistent/legacy state: keep the technical-expiry fence
+    // that prevents retrying its stale intent, but never create a second hold.
+    if (order.status !== "expired" && order.status !== "cancelled") return { kind: "unavailable" };
+    if (!order.technicallyExpired) return { kind: "unavailable" };
+    if (!order.quoteSnapshot || !order.shippingAddressId) return { kind: "unavailable" };
+    if (order.mode === "subscription_cycle" && (!order.subscriptionId || !order.subscriptionCycleId || !bindings.admitsSubscriptionSubject(order))) {
+      return { kind: "unavailable" };
+    }
+    return { kind: "eligible" };
+  }
+
+  return { classifyExpiredRecovery, classifyOrderRecoveryEligibility };
+}
+
+export function quotesMatchForRecovery(
+  frozen: RecoveryQuoteSnapshot,
+  fresh: RecoveryQuoteSnapshot,
+): boolean {
+  return JSON.stringify(commercialFingerprint(frozen)) === JSON.stringify(commercialFingerprint(fresh));
+}
+
+function commercialFingerprint(snapshot: RecoveryQuoteSnapshot) {
+  const quote = snapshot.quote;
+  const terms = quote.context?.shippingTerms;
+  return {
+    currency: quote.currency,
+    lines: quote.lines.map((line) => ({
+      sku: line.sku,
+      productSlug: line.productSlug,
+      quantity: line.quantity,
+      unitPriceGross: line.unitPriceGross,
+      lineSubtotalGross: line.lineSubtotalGross,
+      tax: line.tax,
+    })),
+    discounts: quote.discounts,
+    subtotalGross: quote.subtotalGross,
+    discountTotalGross: quote.discountTotalGross,
+    shippingGross: quote.shippingGross ?? null,
+    shippingDiscountGross: quote.shippingDiscountGross ?? null,
+    shippingTerms: terms ? { version: terms.version, currency: terms.currency,
+      flatMinor: terms.flatMinor, freeThresholdMinor: terms.freeThresholdMinor } : null,
+    totalGross: quote.totalGross,
+    netTotal: quote.netTotal,
+    taxTotal: quote.taxTotal,
+    mode: quote.context?.mode ?? null,
+    cadenceDays: quote.context?.cadenceDays ?? null,
+    sizeConstraint: quote.context?.sizeConstraint ?? null,
+  };
+}

package/src/commerce/server/checkoutInvoiceBuyerSnapshot.ts

@@ -0,0 +1,36 @@
+import type { z } from "zod";
+export function buildCheckoutInvoiceBuyerSnapshot<Buyer>(
+  intent: { contact: { firstName: string; lastName: string; email: string }; address: { street: string; city: string; postalCode: string; country: string } },
+  invoicePreference: { kind: "b2c_named" } | { kind: "b2b_vat"; companyName: string; email?: string; taxId?: string; address: object },
+  schema: z.ZodType<Buyer>,
+): Buyer {
+  if (invoicePreference.kind === "b2b_vat") {
+    return schema.parse({
+      name: invoicePreference.companyName,
+      email: invoicePreference.email ?? intent.contact.email,
+      taxId: invoicePreference.taxId,
+      companyName: invoicePreference.companyName,
+      source: "checkout_invoice_preference",
+      address: {
+        ...invoicePreference.address,
+        source: "checkout_invoice_billing_address",
+      },
+    });
+  }
+
+  return schema.parse({
+    name: `${intent.contact.firstName} ${intent.contact.lastName}`.trim(),
+    email: intent.contact.email,
+    taxId: null,
+    companyName: null,
+    source: "checkout_invoice_preference",
+    address: {
+      line1: intent.address.street,
+      line2: null,
+      city: intent.address.city,
+      postalCode: intent.address.postalCode,
+      country: intent.address.country,
+      source: "checkout_shipping_address",
+    },
+  });
+}