@openlup/platform 0.26.0 → 0.27.0

package/src/commerce/oms/omsContractReadAuxSchemas.ts

@@ -0,0 +1,130 @@
+import { z } from "zod";
+import { datetimeSchema,nullableTextSchema,uuidSchema } from "./omsContractBase.js";
+import { commerceMoneySchema } from "./omsPrimitives.js";
+
+export const omsPricingSummarySchema = z.object({
+  subtotal: commerceMoneySchema,
+  productDiscount: commerceMoneySchema,
+  shipping: commerceMoneySchema,
+  shippingDiscount: commerceMoneySchema,
+  discountTotal: commerceMoneySchema,
+  finalTotal: commerceMoneySchema,
+  source: z.literal("order_columns"),
+}).strict();
+
+export const omsCommunicationDeliveryStatusSchema = z.enum([
+  "planned",
+  "queued",
+  "blocked",
+  "skipped",
+  "processing",
+  "sent",
+  "delivered",
+  "delivery_delayed",
+  "bounced",
+  "complained",
+  "failed",
+  "missed",
+  "legacy_unlinked",
+]);
+
+export const omsCommunicationDeliverySchema = z.object({
+  id: uuidSchema,
+  purpose: z.string().min(1),
+  templateSlug: z.string().min(1),
+  triggerSource: z.string().min(1),
+  triggerEvent: z.string().min(1),
+  aggregateType: z.string().nullable(),
+  aggregateId: z.string().nullable(),
+  dedupeKey: z.string().min(1),
+  status: omsCommunicationDeliveryStatusSchema,
+  providerKind: z.string().nullable(),
+  providerMessageId: z.string().nullable(),
+  scheduledDueAt: datetimeSchema.nullable(),
+  expectedSendAt: datetimeSchema.nullable(),
+  queuedAt: datetimeSchema.nullable(),
+  firstAttemptAt: datetimeSchema.nullable(),
+  sentAt: datetimeSchema.nullable(),
+  deliveredAt: datetimeSchema.nullable(),
+  terminalAt: datetimeSchema.nullable(),
+  lastErrorCode: z.string().nullable(),
+  outboxEventId: uuidSchema.nullable(),
+  platformJobRunId: uuidSchema.nullable(),
+  emailSendId: uuidSchema.nullable(),
+  metadata: z.record(z.string(), z.unknown()),
+  createdAt: datetimeSchema,
+  updatedAt: datetimeSchema,
+}).strict();
+
+export const omsDeliverySelectionSchema = z.object({
+  deliveryKind: z.enum(["courier", "parcel-locker"]),
+  providerKind: nullableTextSchema,
+  carrierKind: nullableTextSchema,
+  carrierCode: nullableTextSchema,
+  serviceCode: nullableTextSchema,
+  pickupPoint: z
+    .object({
+      id: z.string().min(1),
+      name: z.string().min(1),
+      address: z
+        .object({
+          line1: z.string().min(1),
+          postalCode: z.string().min(1),
+          city: z.string().min(1),
+          country: z.string().min(1),
+        })
+        .strict()
+        .nullable(),
+    })
+    .strict()
+    .nullable(),
+  source: nullableTextSchema,
+}).strict();
+
+export const omsDeliveryContactSchema = z.object({
+  schemaVersion: z.literal(1),
+  source: z.string().trim().min(1).max(80),
+  revision: z.number().int().positive(),
+  recipientName: nullableTextSchema,
+  contactEmail: nullableTextSchema,
+  contactPhone: nullableTextSchema,
+  line1: nullableTextSchema,
+  line2: nullableTextSchema,
+  city: nullableTextSchema,
+  postalCode: nullableTextSchema,
+  country: nullableTextSchema,
+  selectedDelivery: z.record(z.string(), z.unknown()).nullable(),
+  deliveryInstructions: nullableTextSchema,
+  courierInstructions: nullableTextSchema,
+}).strict();
+
+export const omsDeliveryContactResolutionSchema = z.object({
+  resolutionVersion: z.literal(1),
+  scope: z.enum(["baseline", "order_override", "parcel", "legacy_inferred", "missing"]),
+  baseline: omsDeliveryContactSchema.nullable(),
+  contact: omsDeliveryContactSchema.nullable(),
+  contactDigest: z.string().regex(/^[0-9a-f]{32}$/).nullable(),
+}).strict().superRefine((value, context) => {
+  if (Boolean(value.contact) !== Boolean(value.contactDigest)) {
+    context.addIssue({
+      code: "custom",
+      message: "contact and contactDigest must be present together",
+      path: ["contactDigest"],
+    });
+  }
+});
+
+export const omsDeliveryContactProjectionSchema = z.object({
+  baseline: omsDeliveryContactSchema.nullable(),
+  effective: omsDeliveryContactSchema.nullable(),
+  scope: z.enum(["baseline", "order_override", "parcel", "legacy_inferred", "missing"]),
+  source: nullableTextSchema,
+  revision: z.number().int().positive().nullable(),
+  digest: z.string().regex(/^[0-9a-f]{32}$/).nullable(),
+  frozen: z.boolean(),
+  providerSubmissionState: z.enum([
+    "not_materialized", "not_started", "draft", "submitting", "created", "uncertain",
+    "failed", "cancel_requested", "cancelled", "unknown",
+  ]),
+  correctionAllowed: z.boolean(),
+}).strict();

package/src/commerce/oms/omsContractReadSchemas.ts

@@ -0,0 +1,303 @@
+import { z } from "zod";
+import { FULFILLMENT_STATUS_MAP, type CustomerFulfillmentStep } from "@openlup/core/fulfillment";
+import { COMMERCE_CONTRACT_VERSION } from "../../pricing/contracts/index.js";
+import {
+actionEligibilitySchema,commerceOrderModeSchema,datetimeSchema,nullableTextSchema,
+omsAccountingStatusSchema,omsAttentionReasonSchema,omsFulfillmentBlockReasonSchema,
+omsFulfillmentStatusSchema,omsHoldReasonSchema,omsHoldStatusSchema,omsInventoryStatusSchema,
+omsNextActionSchema,omsOperationTypeSchema,omsPaymentAttemptStatusSchema,omsPaymentStatusSchema,
+omsProviderOpsStatusSchema,uuidSchema,
+} from "./omsContractBase.js";
+import { omsCommunicationDeliverySchema,omsDeliveryContactProjectionSchema,omsDeliveryContactSchema,omsDeliverySelectionSchema,omsPricingSummarySchema } from "./omsContractReadAuxSchemas.js";
+import {
+defaultOmsReplacementChain,omsFulfillmentSummarySchema,omsInventorySummarySchema,
+omsProviderOpsSlaSchema,omsReplacementChainSchema,omsSubscriptionContextSchema,
+} from "./omsFulfillmentContractSchemas.js";
+import { defaultOmsFulfillmentDebug,omsFulfillmentDebugSchema } from "./omsFulfillmentDebugSchemas.js";
+import { omsFulfillmentHealthDigestSchema,omsFulfillmentHealthSchema } from "./omsFulfillmentHealthSchemas.js";
+import { commerceMoneySchema } from "./omsPrimitives.js";
+import { orderStatusSchema } from "../contractPrimitives.js";
+export { omsCommunicationDeliverySchema,omsCommunicationDeliveryStatusSchema,omsDeliveryContactProjectionSchema,omsDeliveryContactSchema,omsDeliverySelectionSchema,omsPricingSummarySchema } from "./omsContractReadAuxSchemas.js";
+export {
+omsFulfillmentSummarySchema,omsFulfillmentTimelineEventSchema,omsFulfillmentTrackingReferenceSchema,
+omsInventorySummarySchema,omsProviderOpsSlaSchema,omsReplacementChainSchema,
+omsSubscriptionContextSchema,omsSupersededParcelSchema
+} from "./omsFulfillmentContractSchemas.js";
+export { omsFulfillmentHealthDigestSchema,omsFulfillmentHealthSchema } from "./omsFulfillmentHealthSchemas.js";
+export const omsCustomerSummarySchema = z.object({
+  id: uuidSchema,
+  email: z.string().min(1),
+  firstName: nullableTextSchema,
+  lastName: nullableTextSchema,
+  phone: nullableTextSchema,
+  lifecycleStage: z.string().nullable(),
+}).strict();
+export const omsAddressSummarySchema = z.object({
+  id: uuidSchema,
+  label: nullableTextSchema,
+  line1: nullableTextSchema,
+  line2: nullableTextSchema,
+  city: nullableTextSchema,
+  postalCode: nullableTextSchema,
+  country: nullableTextSchema,
+  recipientName: nullableTextSchema,
+  contactPhone: nullableTextSchema,
+  companyName: nullableTextSchema,
+  taxId: nullableTextSchema,
+  deliveryNotes: nullableTextSchema,
+  courierInstructions: nullableTextSchema,
+}).strict();
+export const omsOrderLineSchema = z.object({
+  id: uuidSchema,
+  skuId: uuidSchema.nullable(),
+  sku: nullableTextSchema,
+  title: nullableTextSchema,
+  quantity: z.number().int().positive(),
+  unitPrice: commerceMoneySchema,
+  total: commerceMoneySchema,
+  discountAllocated: commerceMoneySchema,
+  effectiveTotal: commerceMoneySchema,
+  effectiveNet: commerceMoneySchema,
+  vatRateBps: z.number().int().nonnegative().nullable(),
+  productSnapshot: z.record(z.string(), z.unknown()),
+  variantSnapshot: z.record(z.string(), z.unknown()).nullable(),
+}).strict();
+export const omsAccountingSummarySchema = z.object({
+  status: omsAccountingStatusSchema,
+  invoiceId: uuidSchema.nullable(),
+  invoiceRef: nullableTextSchema,
+  providerKind: nullableTextSchema,
+  providerInvoiceNumber: nullableTextSchema,
+  fiscalStatus: nullableTextSchema.optional(),
+  outboxStatus: nullableTextSchema,
+  outboxAttemptCount: z.number().int().nonnegative().nullable(),
+  outboxNextAttemptAt: datetimeSchema.nullable(),
+  outboxLastError: z
+    .object({
+      code: z.string().trim().min(1).max(80).nullable(),
+      message: z.string().trim().min(1).max(240).nullable(),
+      retryable: z.boolean().nullable(),
+    })
+    .strict()
+    .nullable(),
+  recoveryGuidance: z.enum(["none", "not_requested", "wait_for_retry", "review_and_retry"]),
+  updatedAt: datetimeSchema.nullable(),
+}).strict();
+export const omsOrderActionEligibilitySchema = z.object({
+  addNote: actionEligibilitySchema,
+  createHold: actionEligibilitySchema,
+  releaseHold: actionEligibilitySchema,
+  createFulfillment: actionEligibilitySchema,
+  updateShippingAddress: actionEligibilitySchema,
+  recordLabel: actionEligibilitySchema,
+  handOff: actionEligibilitySchema,
+  recordTrackingEvent: actionEligibilitySchema,
+  cancelFulfillment: actionEligibilitySchema,
+  cancelOrder: actionEligibilitySchema,
+  markRefunded: actionEligibilitySchema,
+}).strict();
+export const omsOrderSearchMatchSchema = z.object({
+  field: z.string(),
+  label: z.string().trim().min(1).max(80),
+  valuePreview: z.string().trim().min(1).max(120).nullable(),
+}).strict();
+export const omsOrderListItemSchema = z.object({
+  orderId: uuidSchema,
+  orderNumber: z.string().nullable(),
+  clientId: uuidSchema.nullable(),
+  customer: omsCustomerSummarySchema.nullable(),
+  status: orderStatusSchema,
+  mode: commerceOrderModeSchema,
+  // Where the order was sold. Absent on a reader predating the source axis, and
+  // sourceChannelSlug is absent on a storefront order, which names no channel.
+  // Open strings, not enums: selling surfaces are a registry, not a vocabulary.
+  sourceKind: z.string().optional(),
+  sourceChannelSlug: z.string().optional(),
+  sourceOrderRef: z.string().optional(),
+  paymentMethodLabel: z.string().nullable(),
+  paymentProvider: z.string().nullable(),
+  paymentStatus: omsPaymentStatusSchema,
+  fulfillmentStatus: omsFulfillmentStatusSchema.nullable(),
+  customerFulfillmentStep: z.custom<CustomerFulfillmentStep>((value) =>
+    FULFILLMENT_STATUS_MAP.stages.some((stage) => stage.customerStep === value)),
+  inventoryStatus: omsInventoryStatusSchema,
+  accountingStatus: omsAccountingStatusSchema,
+  providerOpsStatus: omsProviderOpsStatusSchema.default("none"),
+  providerOpsSla: omsProviderOpsSlaSchema.nullable().default(null),
+  providerOrderId: nullableTextSchema.default(null),
+  attentionReason: omsAttentionReasonSchema,
+  nextAction: omsNextActionSchema,
+  activeHoldCount: z.number().int().min(0),
+  // Why, not just that: `attentionReason` says `active_hold` and stops.
+  activeHoldReasons: z.array(omsHoldReasonSchema),
+  fulfillmentHealthDigest: omsFulfillmentHealthDigestSchema,
+  total: commerceMoneySchema,
+  pricingSummary: omsPricingSummarySchema,
+  createdAt: datetimeSchema,
+  updatedAt: datetimeSchema,
+  match: omsOrderSearchMatchSchema.optional(),
+});
+export const omsOrderListSummaryCountsSchema = z.object({
+  needsAttention: z.number().int().min(0),
+  activeHold: z.number().int().min(0),
+  readyForFulfillment: z.number().int().min(0),
+  paymentIssues: z.number().int().min(0),
+  inventoryRisk: z.number().int().min(0),
+  fulfillmentBlocked: z.number().int().min(0),
+  fulfillmentExceptions: z.number().int().min(0),
+  invoiceIssues: z.number().int().min(0),
+  providerDispatchedNotPicked: z.number().int().min(0).optional(),
+}).strict();
+export const omsOrderListSummaryTotalsSchema = z.object({
+  gmv: commerceMoneySchema, aov: commerceMoneySchema,
+  orderCount: z.number().int().min(0), paidSubscriptionCycleCount: z.number().int().min(0),
+}).strict();
+export const omsOrderHoldSchema = z.object({
+  id: uuidSchema,
+  orderId: uuidSchema,
+  status: omsHoldStatusSchema,
+  reason: omsHoldReasonSchema,
+  note: z.string().nullable(),
+  createdAt: datetimeSchema,
+  releasedAt: datetimeSchema.nullable(),
+});
+export const omsOrderOperationSchema = z.object({
+  id: uuidSchema,
+  orderId: uuidSchema,
+  type: omsOperationTypeSchema,
+  holdId: uuidSchema.nullable(),
+  actorUserId: uuidSchema.nullable(),
+  occurredAt: datetimeSchema,
+  payload: z.record(z.string(), z.unknown()),
+});
+
+export const omsPaymentSummarySchema = z.object({
+  intentId: uuidSchema.nullable(),
+  paymentId: uuidSchema.nullable(),
+  status: omsPaymentStatusSchema,
+  activeAttemptId: uuidSchema.nullable(),
+  providerPaymentId: z.string().nullable(),
+  updatedAt: datetimeSchema.nullable(),
+});
+
+export const omsPaymentAttemptSchema = z.object({
+  id: uuidSchema,
+  status: omsPaymentAttemptStatusSchema,
+  provider: z.string().min(1),
+  providerAttemptId: z.string().nullable(),
+  nextActionKind: z.string().nullable(),
+  updatedAt: datetimeSchema,
+});
+
+export const omsPaymentTransitionSchema = z.object({
+  id: uuidSchema,
+  transitionKind: z.string().min(1),
+  fromStatus: z.string().nullable(),
+  toStatus: z.string().min(1),
+  reason: z.string().min(1),
+  occurredAt: datetimeSchema,
+});
+
+export const omsFulfillmentEligibilitySchema = z.object({
+  allowed: z.boolean(),
+  reason: omsFulfillmentBlockReasonSchema.nullable(),
+});
+
+export const omsOrderDetailSchema = omsOrderListItemSchema.extend({
+  shippingAddress: omsAddressSummarySchema.nullable(),
+  deliveryContact: omsDeliveryContactProjectionSchema.optional(),
+  billingAddress: omsAddressSummarySchema.nullable(),
+  deliverySelection: omsDeliverySelectionSchema.nullable().default(null),
+  lines: z.array(omsOrderLineSchema),
+  subscription: omsSubscriptionContextSchema,
+  fulfillmentEligibility: omsFulfillmentEligibilitySchema,
+  inventory: omsInventorySummarySchema,
+  fulfillment: omsFulfillmentSummarySchema,
+  replacementChain: omsReplacementChainSchema.optional().default(defaultOmsReplacementChain),
+  fulfillmentHealth: omsFulfillmentHealthSchema,
+  fulfillmentDebug: omsFulfillmentDebugSchema.optional().default(defaultOmsFulfillmentDebug),
+  accounting: omsAccountingSummarySchema,
+  actionEligibility: omsOrderActionEligibilitySchema,
+  holds: z.array(omsOrderHoldSchema),
+  operations: z.array(omsOrderOperationSchema),
+  payment: omsPaymentSummarySchema,
+  paymentAttempts: z.array(omsPaymentAttemptSchema),
+  paymentTransitions: z.array(omsPaymentTransitionSchema),
+  communicationDeliveries: z.array(omsCommunicationDeliverySchema),
+});
+
+export const adminCommerceOrdersListResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  orders: z.array(omsOrderListItemSchema),
+  summaryCounts: omsOrderListSummaryCountsSchema,
+  summaryTotals: omsOrderListSummaryTotalsSchema,
+  totalCount: z.number().int().min(0),
+  page: z.number().int().min(1),
+  pageSize: z.number().int().min(1),
+}).strict();
+
+export const adminCommerceOrderDetailResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  order: omsOrderDetailSchema,
+});
+
+export const adminCommerceOrderHoldResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  hold: omsOrderHoldSchema,
+  operationId: uuidSchema,
+  replayed: z.boolean(),
+});
+
+export const adminCommerceOrderNoteResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  operation: omsOrderOperationSchema,
+  replayed: z.boolean(),
+});
+
+export const adminCommerceOrderUpdateShippingAddressResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  result: z.enum(["applied", "replayed"]),
+  scope: z.enum(["order", "parcel"]),
+  deliveryContact: omsDeliveryContactSchema,
+  operation: omsOrderOperationSchema,
+  address: z.object({
+    recipientName: nullableTextSchema,
+    contactEmail: nullableTextSchema,
+    contactPhone: nullableTextSchema,
+    line1: nullableTextSchema,
+    line2: nullableTextSchema,
+    city: nullableTextSchema,
+    postalCode: nullableTextSchema,
+    country: nullableTextSchema,
+  }).strict(),
+  replayed: z.boolean(),
+}).strict();
+
+// Mirrors what `commerce_oms_request_replacement_shipment` returns. `releasedHoldIds`
+// is the audit trail of D-R6: the command releases only `fulfillment_exception` holds,
+// and the operator is shown exactly which ones went.
+export const adminCommerceOrderRequestReplacementShipmentResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  operation: omsOrderOperationSchema,
+  replacement: z.object({
+    fulfillmentOrderId: z.string().uuid(),
+    orderId: z.string().uuid(),
+    sequenceNo: z.number().int().min(1),
+    replacesFulfillmentOrderId: z.string().uuid(),
+    reason: z.enum(["damaged", "lost", "returned_undelivered", "other"]),
+    status: z.string(),
+  }),
+  releasedHoldIds: z.array(z.string().uuid()).default([]),
+  replayed: z.boolean(),
+});
+
+export const adminCommerceOrderPaymentLinkResponseSchema = z.object({
+  // The raw token, once: storage is hash-only, so nothing ever reads it back. `emailQueued` is always sent, false for the copy flow, and true only once the email is durably enqueued.
+  token: z.string().min(1), expiresAt: z.string().datetime({ offset: true }), orderRef: z.string().min(1), emailQueued: z.boolean() }).strict();
+
+export const adminCommerceOrderMarkRefundedResponseSchema = z.object({
+  contractVersion: z.literal(COMMERCE_CONTRACT_VERSION),
+  orderId: uuidSchema,
+  status: orderStatusSchema,
+  replayed: z.boolean(),
+}).strict();

package/src/commerce/oms/omsContractRequests.ts

@@ -0,0 +1,143 @@
+import { z } from "zod";
+import {
+commerceOrderModeSchema,
+omsAccountingStatusSchema,
+omsAttentionReasonSchema,
+omsFulfillmentStatusSchema,
+omsHoldReasonSchema,
+omsInventoryStatusSchema,
+omsNextActionSchema,
+omsPaymentStatusSchema,
+omsProviderOpsStatusSchema,
+uuidSchema,
+} from "./omsContractBase.js";
+import { orderStatusSchema } from "../contractPrimitives.js";
+export type { AdminCommerceOrderPaymentLinkRefusal } from "../contracts/omsTypes.js";
+
+const booleanQuerySchema = z.union([
+  z.boolean(),
+  z.enum(["true", "false"]).transform((value) => value === "true"),
+]);
+
+export const adminCommerceOrdersListRequestSchema = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(25),
+  search: z.string().trim().min(1).max(120).optional(),
+  status: orderStatusSchema.optional(),
+  mode: commerceOrderModeSchema.optional(),
+  paymentStatus: omsPaymentStatusSchema.optional(),
+  fulfillmentStatus: omsFulfillmentStatusSchema.optional(),
+  inventoryStatus: omsInventoryStatusSchema.optional(),
+  accountingStatus: omsAccountingStatusSchema.optional(),
+  providerOpsStatus: omsProviderOpsStatusSchema.optional(),
+  attentionReason: omsAttentionReasonSchema.optional(),
+  attentionOnly: booleanQuerySchema.optional(),
+  nextAction: omsNextActionSchema.optional(),
+  from: z.string().trim().min(1).max(40).optional(),
+  to: z.string().trim().min(1).max(40).optional(),
+  sort: z.enum(["created_desc", "created_asc", "updated_desc", "updated_asc", "attention_priority_desc"]).default("created_desc"),
+  // Withdrawn rows are the cancelled residue of a checkout journey that was
+  // declined and retried on another payment method. They are hidden by default
+  // and never deleted; this asks for them back. Absent means false, which is why
+  // it is the operator's explicit act rather than a remembered preference.
+  includeWithdrawn: booleanQuerySchema.optional(),
+}).strict();
+
+export const adminCommerceOrderDetailRequestSchema = z.object({
+  orderId: uuidSchema,
+}).strict();
+
+export const adminCommerceOrderHoldRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  orderId: uuidSchema,
+  reason: omsHoldReasonSchema,
+  note: z.string().trim().max(1000).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceOrderReleaseHoldRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  holdId: uuidSchema,
+  note: z.string().trim().max(1000).optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceOrderNoteRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  orderId: uuidSchema,
+  note: z.string().trim().min(1).max(2000),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceOrderMarkRefundedRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  orderId: uuidSchema,
+  reason: z.string().trim().min(1).max(2000),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceOrderCancelRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  orderId: uuidSchema,
+  reason: z.string().trim().min(1).max(2000),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+export const adminCommerceOrderShippingAddressInputSchema = z.object({
+  recipientName: z.string().trim().min(1).max(200),
+  contactEmail: z.string().trim().email().max(200),
+  line1: z.string().trim().min(1).max(240),
+  line2: z.string().trim().max(240).nullable().optional(),
+  city: z.string().trim().min(1).max(120),
+  postalCode: z.string().trim().min(1).max(32),
+  country: z.string().trim().min(2).max(3),
+  contactPhone: z.string().trim().min(1).max(64),
+  deliveryInstructions: z.string().trim().max(500).nullable().optional(),
+  courierInstructions: z.string().trim().max(500).nullable().optional(),
+}).strict();
+
+// The operator's reasons are the four the database CHECK admits; a fifth would be
+// refused by `commerce_fulfillment_orders_replacement_reason_check`, so the contract
+// and the constraint are deliberately the same list.
+export const adminCommerceOrderRequestReplacementShipmentRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  orderId: uuidSchema,
+  reason: z.enum(["damaged", "lost", "returned_undelivered", "other"]),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+
+/**
+ * Every way the payment-link command declines. Closed on purpose and shared by
+ * both ends: the handler may only send one of these, and the operator surface has
+ * a sentence for each, so no database text can ever reach a screen.
+ */
+export const ADMIN_COMMERCE_ORDER_PAYMENT_LINK_REFUSALS = [
+  "order_not_found",
+  "order_paid",
+  "order_cancelled",
+  "order_not_recoverable",
+  "order_changed",
+] as const;
+
+// The order, and how the operator wants the link to travel. The expiry is still
+// derived from the order's own age and the link still lands on the one recovery
+// page, so `delivery` is the only choice there is to make.
+//
+// `copy` (the default, and what an omitted field means) hands the link back for
+// the operator to paste into their own reply. `email` additionally puts it on the
+// existing transactional recovery rail, addressed to the order's own customer.
+// Optional rather than required so a caller that predates this field keeps its
+// exact behaviour, which is also what keeps the copy flow's request byte-identical.
+export const adminCommerceOrderPaymentLinkRequestSchema = z.object({
+  orderId: uuidSchema,
+  delivery: z.enum(["copy", "email"]).optional(),
+}).strict();
+
+export const adminCommerceOrderUpdateShippingAddressRequestSchema = z.object({
+  idempotencyKey: z.string().trim().min(8).max(120),
+  orderId: uuidSchema,
+  expectedRevision: z.number().int().positive(),
+  expectedContactDigest: z.string().regex(/^[0-9a-f]{32}$/),
+  address: adminCommerceOrderShippingAddressInputSchema,
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).strict();

package/src/commerce/oms/omsContracts.ts

@@ -0,0 +1,6 @@
+export type { AdminCommerceOrderCancelRequest,AdminCommerceOrderDetailRequest,AdminCommerceOrderDetailResponse,AdminCommerceOrderHoldRequest,AdminCommerceOrderHoldResponse,AdminCommerceOrderMarkRefundedRequest,AdminCommerceOrderMarkRefundedResponse,AdminCommerceOrderNoteRequest,AdminCommerceOrderNoteResponse,AdminCommerceOrderPaymentLinkRequest,AdminCommerceOrderPaymentLinkResponse,AdminCommerceOrderReleaseHoldRequest,AdminCommerceOrderRequestReplacementShipmentRequest,AdminCommerceOrderRequestReplacementShipmentResponse,AdminCommerceOrdersListRequest,AdminCommerceOrdersListRequestInput,AdminCommerceOrdersListResponse,AdminCommerceOrderUpdateShippingAddressRequest,AdminCommerceOrderUpdateShippingAddressResponse,AdminOmsAttentionReason,AdminOmsNextAction,AdminOmsOrderListItem,AdminOmsOrderListSummaryCounts,AdminOmsOrderListSummaryTotals,AdminOmsOrderSearchMatch,AdminOmsProviderOpsStatus,OmsAccountingStatus,OmsDeliveryContactResolution,OmsFulfillmentBlockReason,OmsInventoryStatus,OmsOrderDetail,OmsOrderHold,OmsOrderPaymentStatus } from "../contracts/omsTypes.js";
+
+export * from "./omsContractBase.js";
+export { omsDeliveryContactResolutionSchema } from "./omsContractReadAuxSchemas.js";
+export * from "./omsContractReadSchemas.js";
+export * from "./omsContractRequests.js";

package/src/commerce/oms/omsControlPlane.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import type { OmsControlPlaneOrder } from "../contracts/omsTypes.js";
+import { datetimeSchema,actionEligibilitySchema as eligibilitySchema,omsFulfillmentStatusSchema,omsHoldReasonSchema,omsHoldStatusSchema,uuidSchema } from "./omsContractBase.js";
+import { orderStatusSchema } from "../contractPrimitives.js";
+export type { CommerceOmsControlPlanePort,CommerceOmsOperatorResolver,OmsControlPlaneDetailRequest,OmsControlPlaneDetailResponse,OmsControlPlaneListRequest,OmsControlPlaneListResponse,OmsControlPlaneOrder } from "../contracts/omsTypes.js";
+
+export const OMS_CONTROL_PLANE_VERSION = "commerce.oms_control_plane.v1" as const;
+export const OMS_CONTROL_PLANE_VIEW = "control_plane_v1" as const;
+
+const moneySchema = z.object({ amountMinor: z.number().int().nonnegative(), currency: z.string().regex(/^[A-Z]{3}$/) }).strict();
+
+export const omsControlPlaneListRequestSchema = z.object({
+  view: z.literal(OMS_CONTROL_PLANE_VIEW),
+  page: z.coerce.number().int().min(1).default(1),
+  pageSize: z.coerce.number().int().min(1).max(100).default(25),
+  status: orderStatusSchema.optional(),
+}).strict();
+
+export const omsControlPlaneDetailRequestSchema = z.object({
+  view: z.literal(OMS_CONTROL_PLANE_VIEW),
+  orderId: uuidSchema,
+}).strict();
+
+export const omsControlPlaneHoldSchema = z.object({
+  id: uuidSchema,
+  status: omsHoldStatusSchema,
+  reason: omsHoldReasonSchema,
+  note: z.string().nullable(),
+  createdAt: datetimeSchema,
+  releasedAt: datetimeSchema.nullable(),
+}).strict();
+
+export const omsControlPlaneOperationSchema = z.object({
+  id: uuidSchema,
+  action: z.enum(["hold_created", "hold_released", "order_cancelled", "order_refunded"]),
+  holdId: uuidSchema.nullable(),
+  actorId: uuidSchema.nullable(),
+  occurredAt: datetimeSchema,
+}).strict();
+
+const actionsSchema = z.object({
+  createHold: eligibilitySchema,
+  releaseHold: eligibilitySchema,
+  cancelOrder: eligibilitySchema,
+  markRefunded: eligibilitySchema,
+}).strict();
+
+export const omsControlPlaneOrderSchema = z.object({
+  orderId: uuidSchema,
+  status: orderStatusSchema,
+  sourceKind: z.string().min(1).max(32),
+  sourceOrderRef: z.string().min(1).max(128).nullable(),
+  money: moneySchema.nullable(),
+  shipmentStatus: omsFulfillmentStatusSchema.nullable(),
+  activeHoldCount: z.number().int().nonnegative(),
+  activeHoldReasons: z.array(omsHoldReasonSchema),
+  actions: actionsSchema,
+  createdAt: datetimeSchema,
+  updatedAt: datetimeSchema,
+}).strict();
+
+export const omsControlPlaneListResponseSchema = z.object({
+  contractVersion: z.literal(OMS_CONTROL_PLANE_VERSION),
+  orders: z.array(omsControlPlaneOrderSchema),
+  totalCount: z.number().int().nonnegative(),
+  page: z.number().int().positive(),
+  pageSize: z.number().int().positive(),
+}).strict();
+
+export const omsControlPlaneDetailResponseSchema = z.object({
+  contractVersion: z.literal(OMS_CONTROL_PLANE_VERSION),
+  order: omsControlPlaneOrderSchema,
+  holds: z.array(omsControlPlaneHoldSchema),
+  operations: z.array(omsControlPlaneOperationSchema),
+}).strict();
+
+export function omsControlPlaneActions(status: OmsControlPlaneOrder["status"], activeHoldCount: number): OmsControlPlaneOrder["actions"] {
+  const terminal = status === "cancelled" || status === "refunded";
+  return {
+    createHold: { allowed: !terminal, reason: terminal ? "order_terminal" : null },
+    releaseHold: { allowed: activeHoldCount > 0, reason: activeHoldCount > 0 ? null : "no_active_hold" },
+    cancelOrder: { allowed: status === "pending_payment", reason: status === "pending_payment" ? null : "payment_state_ineligible" },
+    markRefunded: { allowed: status === "paid", reason: status === "paid" ? null : "payment_state_ineligible" },
+  };
+}