@openlup/platform 0.26.0 → 0.28.0

package/src/commerce/model/omsReadModelList.ts

@@ -0,0 +1,90 @@
+import type { SubscriptionCycleStatus } from "@openlup/core/subscription";
+import { adminCommerceOrdersListResponseSchema,type AdminCommerceOrdersListResponse,type AdminOmsOrderSearchMatch,type AdminOmsOrderListItem as OmsOrderListItem } from "../oms/omsContracts.js";
+import type {
+OmsFulfillmentOperationRow,
+OmsFulfillmentOrderRow,
+OmsProviderDispatchRefRow,
+OmsProviderStatusEvidenceRow,
+OmsReleasedProviderExceptionHoldRow,
+OmsShipmentExternalRefRow,
+} from "./omsFulfillmentSummary.js";
+import { summarizeOmsListTotals } from "./omsListTotals.js";
+import { findCustomer } from "./omsReadModelHelpers.js";
+import { summarizeOmsListOrders } from "./omsReadModelListSummary.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import { buildOmsOrderRowCore } from "./omsReadModelRowCore.js";
+import type { OmsAccountingInvoiceRow,OmsAccountingOutboxRow,OmsCustomerRow,OmsInventoryReservationRow,OmsOrderItemRow,OmsOrderRow,OmsPaymentAttemptRow,OmsPaymentIntentRow } from "./omsReadModelRows.js";
+import { COMMERCE_CONTRACT_VERSION } from "../../pricing/contracts/index.js";
+
+export function buildOmsOrderListResponse(input: {
+  orders: OmsOrderRow[];
+  identityExtras?: Record<string, Record<string, unknown>>;
+  projections?: OmsReadModelProjections;
+  paymentIntents: OmsPaymentIntentRow[];
+  paymentAttempts?: OmsPaymentAttemptRow[];
+  activeHoldCounts: Record<string, number>;
+  activeHoldReasons?: Record<string, OmsOrderListItem["activeHoldReasons"]>;
+  fulfillmentHealthDigests?: Record<string, OmsOrderListItem["fulfillmentHealthDigest"]>;
+  customers?: OmsCustomerRow[];
+  orderItems?: OmsOrderItemRow[];
+  inventoryReservations?: OmsInventoryReservationRow[];
+  fulfillmentOrders?: OmsFulfillmentOrderRow[];
+  fulfillmentOperations?: OmsFulfillmentOperationRow[];
+  shipmentExternalRefs?: OmsShipmentExternalRefRow[];
+  providerDispatchRefs?: OmsProviderDispatchRefRow[];
+  providerStatusEvidence?: OmsProviderStatusEvidenceRow[];
+  releasedProviderExceptionHolds?: OmsReleasedProviderExceptionHoldRow[];
+  accountingInvoices?: OmsAccountingInvoiceRow[];
+  accountingOutbox?: OmsAccountingOutboxRow[];
+  subscriptionCycleStatuses?: Record<string, SubscriptionCycleStatus | null>;
+  searchMatches?: Record<string, AdminOmsOrderSearchMatch>;
+  summaryCounts?: AdminCommerceOrdersListResponse["summaryCounts"];
+  summaryTotals?: AdminCommerceOrdersListResponse["summaryTotals"];
+  totalCount: number;
+  page: number;
+  pageSize: number;
+}): AdminCommerceOrdersListResponse {
+  const orders = input.orders.map((order) => {
+    // The list's only job on top of the shared core is to narrow each collection
+    // to this order; the detail hands the core the singletons it already loaded.
+    const { row: listItem } = buildOmsOrderRowCore({
+      projections: input.projections,
+      order,
+      activeHoldCount: input.activeHoldCounts[order.id] ?? 0,
+      paymentIntents: input.paymentIntents,
+      paymentAttempts: input.paymentAttempts ?? [],
+      identity: { customer: findCustomer(order, input.customers ?? []), ...input.identityExtras?.[order.id] },
+      orderItems: input.orderItems?.filter((item) => item.order_id === order.id),
+      inventoryReservations: (input.inventoryReservations ?? []).filter((reservation) => reservation.order_id === order.id),
+      fulfillmentOrders: (input.fulfillmentOrders ?? []).filter((candidate) => candidate.order_id === order.id),
+      fulfillmentOperations: input.fulfillmentOperations ?? [],
+      shipmentExternalRefs: (input.shipmentExternalRefs ?? []).filter((candidate) => candidate.order_id === order.id),
+      dispatchRefs: input.providerDispatchRefs ?? [],
+      statusEvidence: input.providerStatusEvidence ?? [],
+      releasedProviderExceptionHolds: (input.releasedProviderExceptionHolds ?? []).filter((hold) => hold.order_id === order.id),
+      accountingInvoice: (input.accountingInvoices ?? []).find((invoice) => invoice.order_id === order.id) ?? null,
+      accountingOutbox: input.accountingOutbox ?? [],
+      subscriptionCycleStatus: order.subscription_cycle_id ? input.subscriptionCycleStatuses?.[order.subscription_cycle_id] ?? null : null,
+    });
+    // Both diagnostics arrive as per-order maps built by the read that owns the
+    // rows they are derived from - the hold `reason` column for one, the health
+    // builder for the other - exactly as `activeHoldCounts` already does. A caller
+    // that supplies neither gets the quiet row it would have got before this wave.
+    const diagnostics = {
+      activeHoldReasons: input.activeHoldReasons?.[order.id] ?? [],
+      fulfillmentHealthDigest: input.fulfillmentHealthDigests?.[order.id] ?? { healthStatus: "ok" as const, attentionReasons: [] },
+    };
+    const match = input.searchMatches?.[order.id];
+    return match ? { ...listItem, ...diagnostics, match } : { ...listItem, ...diagnostics };
+  });
+
+  return (input.projections?.parseList ?? (value => adminCommerceOrdersListResponseSchema.parse(value)))({
+    contractVersion: COMMERCE_CONTRACT_VERSION,
+    orders,
+    summaryCounts: input.summaryCounts ?? summarizeOmsListOrders(orders, input.projections),
+    summaryTotals: input.summaryTotals ?? summarizeOmsListTotals(orders, input.projections?.currency),
+    totalCount: input.totalCount,
+    page: input.page,
+    pageSize: input.pageSize,
+  });
+}

package/src/commerce/model/omsReadModelListSummary.ts

@@ -0,0 +1,19 @@
+import type { AdminCommerceOrdersListResponse } from "../oms/omsContracts.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+
+export function summarizeOmsListOrders(
+  orders: AdminCommerceOrdersListResponse["orders"],
+  projections?: OmsReadModelProjections,
+): AdminCommerceOrdersListResponse["summaryCounts"] {
+  return {
+    needsAttention: orders.filter((order) => order.attentionReason !== "none").length,
+    activeHold: orders.filter((order) => order.activeHoldCount > 0).length,
+    readyForFulfillment: orders.filter((order) => order.nextAction === "create_fulfillment").length,
+    paymentIssues: orders.filter((order) => order.attentionReason === "payment_required").length,
+    inventoryRisk: orders.filter((order) => order.attentionReason === "inventory_missing").length,
+    fulfillmentBlocked: orders.filter((order) => order.attentionReason === "fulfillment_blocked").length,
+    fulfillmentExceptions: orders.filter((order) => order.attentionReason === "fulfillment_exception").length,
+    invoiceIssues: orders.filter((order) => order.nextAction === "review_invoice").length,
+    providerDispatchedNotPicked: orders.filter((order) => Boolean(projections?.dispatchedNotPickedStatus) && order.providerOpsStatus === projections?.dispatchedNotPickedStatus).length,
+  };
+}

package/src/commerce/model/omsReadModelPricing.ts

@@ -0,0 +1,57 @@
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import type { OmsOrderItemRow,OmsOrderRow } from "./omsReadModelRows.js";
+import {
+deriveOrderMoney,
+type CanonicalOrderMoney,
+} from "../orderMoney.js";
+
+export function deriveOmsOrderMoney(
+  order: OmsOrderRow,
+  items?: readonly OmsOrderItemRow[],
+): CanonicalOrderMoney {
+  return deriveOrderMoney(
+    {
+      id: order.id,
+      currency: order.currency,
+      subtotal_cents: order.subtotal_cents ?? order.total_cents,
+      discount_cents: order.discount_cents ?? 0,
+      shipping_cents: order.shipping_cents ?? 0,
+      shipping_discount_cents: order.shipping_discount_cents ?? 0,
+      tax_cents: order.tax_cents ?? 0,
+      total_cents: order.total_cents,
+    },
+    items?.map((item) => ({
+      id: item.id,
+      quantity: item.quantity,
+      unit_price_cents: item.unit_price_cents ?? 0,
+      total_cents: item.total_cents ?? 0,
+      discount_allocated_cents: item.discount_allocated_cents,
+      effective_total_cents: item.effective_total_cents,
+      effective_net_cents: item.effective_net_cents,
+      vat_rate_bps: item.vat_rate_bps ?? 0,
+    })),
+  );
+}
+
+export function pricingSummaryForOrder(
+  order: OmsOrderRow,
+  items?: readonly OmsOrderItemRow[],
+  orderMoney: CanonicalOrderMoney = deriveOmsOrderMoney(order, items),
+): OmsOrderDetail["pricingSummary"] {
+  return {
+    subtotal: money(orderMoney.subtotal, order.currency),
+    productDiscount: money(orderMoney.productDiscount, order.currency),
+    shipping: money(orderMoney.shippingEffective, order.currency),
+    shippingDiscount: money(orderMoney.shippingDiscount, order.currency),
+    discountTotal: money(
+      orderMoney.productDiscount + orderMoney.shippingDiscount,
+      order.currency,
+    ),
+    finalTotal: money(orderMoney.total, order.currency),
+    source: "order_columns",
+  };
+}
+
+function money(amountMinor: number, currency: OmsOrderDetail["total"]["currency"]): OmsOrderDetail["total"] {
+  return { amountMinor, currency };
+}

package/src/commerce/model/omsReadModelProjections.ts

@@ -0,0 +1 @@
+export type { OmsReadModelProjections } from "../contracts/omsTypes.js";

package/src/commerce/model/omsReadModelRowCore.ts

@@ -0,0 +1,193 @@
+import type { OmsDeliveryContactResolution,OmsOrderDetail } from "../oms/omsContracts.js";
+import { accountingSummary } from "./omsAccountingVisibility.js";
+import {
+buildOmsFulfillmentSummary,
+deriveOmsCustomerFulfillmentStep,
+type OmsProviderDispatchRefRow as OmsDispatchRefRow,
+type OmsFulfillmentOrderRow
+} from "./omsFulfillmentSummary.js";
+import { paymentMethodForOrder } from "./omsPaymentMethodSummary.js";
+import {
+baseOrder,
+evaluateOperationalState,
+inventorySummary,
+paymentStatusForOrder,
+} from "./omsReadModelHelpers.js";
+import type { OmsOrderRowCore,OmsOrderRowCoreInput } from "./omsReadModelRows.js";
+import { evaluateCommerceFulfillmentEligibility } from "../fulfillmentEligibility.js";
+
+export function buildOmsOrderRowCore(input: OmsOrderRowCoreInput): OmsOrderRowCore {
+  const paymentStatus = paymentStatusForOrder(input.order.id, input.paymentIntents);
+  const paymentMethod = paymentMethodForOrder(input.order.id, input.paymentIntents, input.paymentAttempts, input.projections);
+  const inventory = inventorySummary(input.inventoryReservations, input.orderItems ?? []);
+  const fulfillment = buildOmsFulfillmentSummary({
+    projections: input.projections,
+    fulfillmentOrders: input.fulfillmentOrders,
+    fulfillmentOperations: input.fulfillmentOperations,
+    shipmentExternalRefs: input.shipmentExternalRefs,
+    providerAttempts: input.providerAttempts,
+    providerDispatchRefs: input.dispatchRefs,
+    providerStatusEvidence: input.statusEvidence,
+  });
+  const providerOps = input.projections?.providerOps?.(input) ?? { status: "none", sla: null, providerOrderId: null };
+  const customerFulfillmentStep = deriveOmsCustomerFulfillmentStep(
+    input.order.status,
+    fulfillment,
+    input.fulfillmentOrders[0]?.delivered_at,
+    input.releasedProviderExceptionHolds,
+    input.statusEvidence,
+    input.activeHoldCount,
+    input.projections,
+  );
+  const accounting = accountingSummary(input.accountingInvoice, input.accountingOutbox, input.projections);
+  const fulfillmentEligibility = evaluateCommerceFulfillmentEligibility({
+    orderMode: input.order.mode,
+    orderStatus: input.order.status,
+    paymentStatus,
+    subscriptionCycleStatus: input.subscriptionCycleStatus,
+    activeHoldCount: input.activeHoldCount,
+    hasShippingAddress: Boolean(input.order.shipping_address_id),
+    inventoryStatus: inventory.status,
+  });
+  const operational = evaluateOperationalState({
+    order: input.order,
+    paymentStatus,
+    activeHoldCount: input.activeHoldCount,
+    inventoryStatus: inventory.status,
+    fulfillmentStatus: fulfillment.status,
+    fulfillmentEligibility,
+    accountingStatus: accounting.status,
+  });
+  return {
+    row: baseOrder({
+      order: input.order,
+      paymentStatus,
+      paymentMethod,
+      activeHoldCount: input.activeHoldCount,
+      identity: input.identity,
+      inventoryStatus: inventory.status,
+      fulfillmentStatus: fulfillment.status,
+      customerFulfillmentStep,
+      accountingStatus: accounting.status,
+      providerOpsStatus: providerOps.status,
+      providerOpsSla: providerOps.sla,
+      providerOrderId: providerOps.providerOrderId,
+      attentionReason: operational.attentionReason,
+      nextAction: operational.nextAction,
+      orderItems: input.orderItems,
+      orderMoney: input.orderMoney,
+    }),
+    paymentStatus,
+    inventory,
+    fulfillment,
+    accounting,
+    fulfillmentEligibility,
+  };
+}
+
+type DeliveryContact = NonNullable<NonNullable<OmsOrderDetail["deliveryContact"]>["effective"]>;
+
+export function buildOmsDeliveryContactProjection(input: {
+  resolution: OmsDeliveryContactResolution;
+  currentParcel: OmsFulfillmentOrderRow | null;
+  dispatchRefs: OmsDispatchRefRow[];
+}): NonNullable<OmsOrderDetail["deliveryContact"]> {
+  const baseline = parseDeliveryContact(input.resolution.baseline);
+  const effective = parseDeliveryContact(input.resolution.contact);
+  const providerSubmissionState = deliveryContactProviderSubmissionState(input.currentParcel, input.dispatchRefs);
+  const frozen = input.dispatchRefs.some(deliveryContactRefIsEffectful)
+    || Boolean(input.currentParcel && !canUpdateShippingAddress(input.currentParcel.status));
+  return {
+    baseline, effective, scope: input.resolution.scope, source: effective?.source ?? null,
+    revision: effective?.revision ?? null, digest: effective ? input.resolution.contactDigest : null,
+    frozen, providerSubmissionState,
+    correctionAllowed: Boolean(effective && input.resolution.contactDigest) && !frozen,
+  };
+}
+
+export function deliveryContactAddress(
+  contact: DeliveryContact | null,
+  addressId: string | null | undefined,
+): OmsOrderDetail["shippingAddress"] {
+  if (!contact || !addressId) return null;
+  return {
+    id: addressId, label: null, line1: contact.line1, line2: contact.line2,
+    city: contact.city, postalCode: contact.postalCode, country: contact.country,
+    recipientName: contact.recipientName, contactPhone: contact.contactPhone,
+    companyName: null, taxId: null, deliveryNotes: contact.deliveryInstructions,
+    courierInstructions: contact.courierInstructions,
+  };
+}
+
+export function buildCurrentDeliveryContact(input: {
+  resolution: OmsDeliveryContactResolution;
+  shippingAddressId: string | null | undefined;
+  fulfillmentOrders: OmsFulfillmentOrderRow[];
+  dispatchRefs: OmsDispatchRefRow[];
+}) {
+  const currentParcel = input.fulfillmentOrders[0] ?? null;
+  const deliveryContact = buildOmsDeliveryContactProjection({
+    resolution: input.resolution,
+    currentParcel,
+    dispatchRefs: currentParcel
+      ? input.dispatchRefs.filter((row) => row.fulfillment_order_id === currentParcel.id)
+      : [],
+  });
+  return {
+    deliveryContact,
+    effectiveShippingAddress: deliveryContactAddress(deliveryContact.effective, input.shippingAddressId),
+  };
+}
+
+function parseDeliveryContact(value: unknown): DeliveryContact | null {
+  const row = objectRecord(value);
+  if (row.schemaVersion !== 1) return null;
+  const source = nullableText(row.source);
+  const revision = positiveInteger(row.revision);
+  if (!source || revision === null) return null;
+  return {
+    schemaVersion: 1, source, revision,
+    recipientName: nullableText(row.recipientName), contactEmail: nullableText(row.contactEmail),
+    contactPhone: nullableText(row.contactPhone), line1: nullableText(row.line1),
+    line2: nullableText(row.line2), city: nullableText(row.city),
+    postalCode: nullableText(row.postalCode), country: nullableText(row.country),
+    selectedDelivery: recordOrNull(row.selectedDelivery),
+    deliveryInstructions: nullableText(row.deliveryInstructions),
+    courierInstructions: nullableText(row.courierInstructions),
+  };
+}
+
+function deliveryContactProviderSubmissionState(
+  parcel: OmsFulfillmentOrderRow | null,
+  dispatchRefs: OmsDispatchRefRow[],
+): NonNullable<OmsOrderDetail["deliveryContact"]>["providerSubmissionState"] {
+  if (!parcel) return "not_materialized";
+  if (!dispatchRefs.length) return "not_started";
+  const dispatchRef = dispatchRefs.find(deliveryContactRefIsEffectful) ?? dispatchRefs[0]!;
+  const known = ["draft", "submitting", "created", "uncertain", "failed", "cancel_requested", "cancelled"] as const;
+  return known.find((status) => status === dispatchRef.status) ?? "unknown";
+}
+
+function deliveryContactRefIsEffectful(dispatchRef: OmsDispatchRefRow | null): boolean {
+  return Boolean(dispatchRef && !(dispatchRef.status === "draft" && !dispatchRef.provider_order_id));
+}
+
+function objectRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+
+function recordOrNull(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+
+function nullableText(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function positiveInteger(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}
+
+function canUpdateShippingAddress(status: OmsOrderDetail["fulfillmentStatus"]): boolean {
+  return !status || status === "created" || status === "packed" || status === "label_pending";
+}

package/src/commerce/model/omsReadModelRows.ts

@@ -0,0 +1,7 @@
+export type { OmsAccountingInvoiceRow,OmsAccountingOutboxRow,OmsAddressRow,OmsCommunicationDeliveryRow,OmsCustomerRow,OmsHoldRow,OmsInventoryReservationRow,OmsOperationRow,OmsOrderItemRow,OmsOrderRow,OmsOrderRowCore,OmsOrderRowCoreInput,OmsPaymentAttemptRow,OmsPaymentIntentRow,OmsPaymentTransitionRow } from "../contracts/omsTypes.js";
+
+// Every status union below is read back out of the contract the row feeds, so a
+// vocabulary can only be widened in one place. The rows are DB shapes, not
+// contract shapes, so the derivation is by indexed access rather than by
+// re-importing the zod schemas - this file stays type-only and carries no
+// runtime import.

package/src/commerce/offerAvailability.ts

@@ -0,0 +1,75 @@
+import type {
+  CommerceOfferAvailability,
+  CommerceOfferAvailabilityRequestItem,
+  CommerceOfferAvailabilityStatus,
+} from "./contracts/availability.js";
+
+export const DEFAULT_LOW_STOCK_THRESHOLD = 20;
+
+export interface DeriveOfferAvailabilityInput
+  extends CommerceOfferAvailabilityRequestItem {
+  sellableNow: number | null;
+  lowStockThreshold?: number;
+  source: string;
+}
+
+export function deriveOfferAvailability(
+  input: DeriveOfferAvailabilityInput,
+): CommerceOfferAvailability {
+  const status = statusForSellableNow(input.sellableNow, input.lowStockThreshold);
+  return {
+    sku: input.sku,
+    productSlug: input.productSlug,
+    variantId: input.variantId,
+    status,
+    visibleInConfigurator: status !== "out_of_stock",
+    sellableNow: input.sellableNow,
+    reasonCode: reasonCodeFor(status),
+    source: input.source,
+  };
+}
+
+export function defaultOfferAvailability(
+  item: CommerceOfferAvailabilityRequestItem,
+  source = "static",
+): CommerceOfferAvailability {
+  return {
+    sku: item.sku,
+    productSlug: item.productSlug,
+    variantId: item.variantId,
+    status: "available",
+    visibleInConfigurator: true,
+    sellableNow: null,
+    reasonCode: "static_available",
+    source,
+  };
+}
+
+export function availabilityBySku(
+  items: readonly CommerceOfferAvailability[],
+): Map<string, CommerceOfferAvailability> {
+  return new Map(items.map((item) => [item.sku, item]));
+}
+
+/**
+ * The status ladder itself, exported so a composed offer (a bundle derives one
+ * status from many components) reads the SAME four rungs rather than mirroring
+ * them. A second copy would drift the first time a rung moves.
+ */
+export function statusForSellableNow(
+  sellableNow: number | null,
+  lowStockThreshold = DEFAULT_LOW_STOCK_THRESHOLD,
+): CommerceOfferAvailabilityStatus {
+  if (sellableNow == null) return "unknown";
+  if (sellableNow <= 0) return "out_of_stock";
+  if (sellableNow <= lowStockThreshold) return "low_stock";
+  return "available";
+}
+
+/** The reason-code vocabulary for a stock-derived status; exported for the same reason. */
+export function reasonCodeFor(status: CommerceOfferAvailabilityStatus): string {
+  if (status === "available") return "stock_available";
+  if (status === "low_stock") return "low_stock";
+  if (status === "out_of_stock") return "out_of_stock";
+  return "stock_unknown";
+}

package/src/commerce/offerAvailabilitySchemas.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+
+import type { CommerceOfferAvailabilityRequestItem } from "./contracts/index.js";
+
+/** Bind the existing product identifier and SKU validators without importing a host. */
+export function createOfferAvailabilitySchemas(
+  catalogProductSlugSchema: z.ZodType<string, string>,
+  commerceSkuSchema: z.ZodType<string, string>,
+) {
+const commerceOfferAvailabilityStatusSchema = z.enum([
+  "available",
+  "low_stock",
+  "out_of_stock",
+  "unknown",
+]);
+
+const commerceOfferAvailabilitySourceSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(80);
+
+const commerceOfferAvailabilityRequestItemSchema = z
+  .object({
+    sku: commerceSkuSchema,
+    productSlug: catalogProductSlugSchema,
+    variantId: z.string().trim().min(1).max(120),
+    requestedQuantity: z.number().int().positive().default(1),
+    checkoutMode: z.enum(["one_time", "subscription"]).default("one_time"),
+  })
+  .strict();
+
+const commerceOfferAvailabilitySchema = z
+  .object({
+    sku: commerceSkuSchema,
+    productSlug: catalogProductSlugSchema,
+    variantId: z.string().trim().min(1).max(120),
+    status: commerceOfferAvailabilityStatusSchema,
+    visibleInConfigurator: z.boolean(),
+    sellableNow: z.number().int().nonnegative().nullable(),
+    reasonCode: z.string().trim().min(1).max(120),
+    source: commerceOfferAvailabilitySourceSchema,
+  })
+  .strict();
+
+return { commerceOfferAvailabilityStatusSchema, commerceOfferAvailabilitySourceSchema, commerceOfferAvailabilityRequestItemSchema, commerceOfferAvailabilitySchema };
+}
+
+/** One request per variant, preserving order and checkout mode. */
+export function offerAvailabilityRequestItems(
+  variants: readonly { sku: string; slug: string; variantId: string }[],
+  checkoutMode: CommerceOfferAvailabilityRequestItem["checkoutMode"],
+): CommerceOfferAvailabilityRequestItem[] {
+  return variants.map(variant => ({ sku: variant.sku, productSlug: variant.slug,
+    variantId: variant.variantId, requestedQuantity: 1, checkoutMode }));
+}

package/src/commerce/offerEvidenceSchemas.ts

@@ -0,0 +1,17 @@
+import { z } from "zod";
+
+const COMMERCE_OFFER_EVIDENCE_MAX_JSON_LENGTH = 4_096;
+
+/**
+ * The adopter's own record of why a checkout was bound to an offer version.
+ * Server-minted only: core bounds its keys and size and never reads it.
+ */
+export const commerceOfferEvidenceSchema = z
+  .record(z.string().regex(/^[A-Za-z][A-Za-z0-9]{0,39}$/), z.unknown())
+  .superRefine((evidence, ctx) => {
+    if (JSON.stringify(evidence).length > COMMERCE_OFFER_EVIDENCE_MAX_JSON_LENGTH) {
+      ctx.addIssue({ code: z.ZodIssueCode.custom, message: "offer evidence exceeds 4096 characters" });
+    }
+  });
+
+export type CommerceOfferEvidence = z.infer<typeof commerceOfferEvidenceSchema>;

package/src/commerce/oms/omsContractBase.ts

@@ -0,0 +1,92 @@
+import { PAYMENT_ATTEMPT_STATUSES,PAYMENT_INTENT_STATUSES } from "@openlup/core/payment";
+import { SUBSCRIPTION_CYCLE_STATUSES } from "@openlup/core/subscription";
+import { z } from "zod";
+import {
+OMS_FULFILLMENT_BLOCK_REASONS,
+OMS_INVENTORY_STATUSES,
+} from "../contracts/state.js";
+
+export const commerceOrderModeSchema = z.enum(["one_time", "subscription_cycle"]);
+export const omsPaymentStatusSchema = z.enum(["not_started", ...PAYMENT_INTENT_STATUSES]);
+export const omsPaymentAttemptStatusSchema = z.enum(PAYMENT_ATTEMPT_STATUSES);
+export const omsSubscriptionCycleStatusSchema = z.enum(SUBSCRIPTION_CYCLE_STATUSES);
+
+export const omsHoldReasonSchema = z.enum([
+  "payment_not_succeeded",
+  "inventory_review",
+  "risk_review",
+  "address_review",
+  "fulfillment_exception",
+  "manual_support",
+]);
+export const omsHoldStatusSchema = z.enum(["active", "released"]);
+export const omsOperationTypeSchema = z.enum([
+  "hold_created",
+  "hold_released",
+  "fulfillment_reviewed",
+  "support_note",
+  "shipping_address_updated",
+  "order_marked_refunded",
+  "order_cancelled_manual",
+  // The replacement command's audit row. The database CHECK was widened for it by
+  // 20260820100000_replacement_shipment_command.sql; without the same widening here
+  // the operation appears in `commerce_order_operations` and then fails this enum on
+  // every read of the order that carries it - the replacement response itself, and
+  // the whole order-detail timeline afterwards.
+  "replacement_shipment_requested",
+]);
+export const omsFulfillmentBlockReasonSchema = z.enum(OMS_FULFILLMENT_BLOCK_REASONS);
+export const omsInventoryStatusSchema = z.enum(OMS_INVENTORY_STATUSES);
+export const omsFulfillmentStatusSchema = z.enum([
+  "created",
+  "packed",
+  "label_pending",
+  "label_created",
+  "handed_over",
+  "in_transit",
+  "delivered",
+  "exception",
+  "cancelled",
+]);
+export const omsAccountingStatusSchema = z.string();
+export const omsAttentionReasonSchema = z.enum([
+  "none",
+  "payment_required",
+  "active_hold",
+  "missing_shipping_address",
+  "inventory_missing",
+  "fulfillment_blocked",
+  "fulfillment_pending",
+  "fulfillment_exception",
+  "invoice_missing",
+  "invoice_issue_failed",
+  "invoice_buyer_data_invalid",
+]);
+export const omsNextActionSchema = z.enum([
+  "none",
+  "review_payment",
+  "release_hold",
+  "review_address",
+  "review_inventory",
+  "review_fulfillment",
+  "create_fulfillment",
+  "record_label",
+  "hand_off",
+  "review_tracking",
+  "review_invoice",
+]);
+export const omsProviderOpsStatusSchema = z.string();
+export const omsProviderOpsSlaStatusSchema = z.enum([
+  "ok",
+  "watch",
+  "breached",
+  "paused_non_shipping_day",
+]);
+
+export const uuidSchema = z.guid();
+export const datetimeSchema = z.string().datetime({ offset: true });
+export const nullableTextSchema = z.string().nullable();
+export const actionEligibilitySchema = z.object({
+  allowed: z.boolean(),
+  reason: z.string().nullable(),
+}).strict();