@openlup/platform 0.25.0 → 0.27.0

package/dist/commerce/oms/omsContractReadSchemas.js

@@ -0,0 +1,277 @@
+import { z } from "zod";
+import { FULFILLMENT_STATUS_MAP } 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((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/dist/commerce/oms/omsContractRequests.d.ts

@@ -0,0 +1,196 @@
+import { z } from "zod";
+export type { AdminCommerceOrderPaymentLinkRefusal } from "../contracts/omsTypes.js";
+export declare const adminCommerceOrdersListRequestSchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    search: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        expired: "expired";
+        pending_payment: "pending_payment";
+        paid: "paid";
+        failed: "failed";
+        fulfillment_pending: "fulfillment_pending";
+        cancelled: "cancelled";
+        fulfilled: "fulfilled";
+        refunded: "refunded";
+    }>>;
+    mode: z.ZodOptional<z.ZodEnum<{
+        one_time: "one_time";
+        subscription_cycle: "subscription_cycle";
+    }>>;
+    paymentStatus: z.ZodOptional<z.ZodEnum<{
+        expired: "expired";
+        created: "created";
+        failed: "failed";
+        cancelled: "cancelled";
+        refunded: "refunded";
+        not_started: "not_started";
+        requires_action: "requires_action";
+        processing: "processing";
+        partially_refunded: "partially_refunded";
+        disputed: "disputed";
+        succeeded: "succeeded";
+    }>>;
+    fulfillmentStatus: z.ZodOptional<z.ZodEnum<{
+        created: "created";
+        cancelled: "cancelled";
+        delivered: "delivered";
+        packed: "packed";
+        label_pending: "label_pending";
+        label_created: "label_created";
+        handed_over: "handed_over";
+        in_transit: "in_transit";
+        exception: "exception";
+    }>>;
+    inventoryStatus: z.ZodOptional<z.ZodEnum<{
+        expired: "expired";
+        not_checked: "not_checked";
+        reserved: "reserved";
+        missing: "missing";
+        released: "released";
+        consumed: "consumed";
+        review_required: "review_required";
+    }>>;
+    accountingStatus: z.ZodOptional<z.ZodString>;
+    providerOpsStatus: z.ZodOptional<z.ZodString>;
+    attentionReason: z.ZodOptional<z.ZodEnum<{
+        fulfillment_pending: "fulfillment_pending";
+        active_hold: "active_hold";
+        missing_shipping_address: "missing_shipping_address";
+        none: "none";
+        fulfillment_exception: "fulfillment_exception";
+        payment_required: "payment_required";
+        inventory_missing: "inventory_missing";
+        fulfillment_blocked: "fulfillment_blocked";
+        invoice_missing: "invoice_missing";
+        invoice_issue_failed: "invoice_issue_failed";
+        invoice_buyer_data_invalid: "invoice_buyer_data_invalid";
+    }>>;
+    attentionOnly: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodPipe<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "true" | "false">>]>>;
+    nextAction: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        review_payment: "review_payment";
+        release_hold: "release_hold";
+        review_address: "review_address";
+        review_inventory: "review_inventory";
+        review_fulfillment: "review_fulfillment";
+        create_fulfillment: "create_fulfillment";
+        record_label: "record_label";
+        hand_off: "hand_off";
+        review_tracking: "review_tracking";
+        review_invoice: "review_invoice";
+    }>>;
+    from: z.ZodOptional<z.ZodString>;
+    to: z.ZodOptional<z.ZodString>;
+    sort: z.ZodDefault<z.ZodEnum<{
+        created_desc: "created_desc";
+        created_asc: "created_asc";
+        updated_desc: "updated_desc";
+        updated_asc: "updated_asc";
+        attention_priority_desc: "attention_priority_desc";
+    }>>;
+    includeWithdrawn: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodPipe<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "true" | "false">>]>>;
+}, z.core.$strict>;
+export declare const adminCommerceOrderDetailRequestSchema: z.ZodObject<{
+    orderId: z.ZodGUID;
+}, z.core.$strict>;
+export declare const adminCommerceOrderHoldRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    orderId: z.ZodGUID;
+    reason: z.ZodEnum<{
+        payment_not_succeeded: "payment_not_succeeded";
+        inventory_review: "inventory_review";
+        risk_review: "risk_review";
+        fulfillment_exception: "fulfillment_exception";
+        address_review: "address_review";
+        manual_support: "manual_support";
+    }>;
+    note: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const adminCommerceOrderReleaseHoldRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    holdId: z.ZodGUID;
+    note: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const adminCommerceOrderNoteRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    orderId: z.ZodGUID;
+    note: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const adminCommerceOrderMarkRefundedRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    orderId: z.ZodGUID;
+    reason: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const adminCommerceOrderCancelRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    orderId: z.ZodGUID;
+    reason: z.ZodString;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const adminCommerceOrderShippingAddressInputSchema: z.ZodObject<{
+    recipientName: z.ZodString;
+    contactEmail: z.ZodString;
+    line1: z.ZodString;
+    line2: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    city: z.ZodString;
+    postalCode: z.ZodString;
+    country: z.ZodString;
+    contactPhone: z.ZodString;
+    deliveryInstructions: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    courierInstructions: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strict>;
+export declare const adminCommerceOrderRequestReplacementShipmentRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    orderId: z.ZodGUID;
+    reason: z.ZodEnum<{
+        other: "other";
+        damaged: "damaged";
+        lost: "lost";
+        returned_undelivered: "returned_undelivered";
+    }>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$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 declare const ADMIN_COMMERCE_ORDER_PAYMENT_LINK_REFUSALS: readonly ["order_not_found", "order_paid", "order_cancelled", "order_not_recoverable", "order_changed"];
+export declare const adminCommerceOrderPaymentLinkRequestSchema: z.ZodObject<{
+    orderId: z.ZodGUID;
+    delivery: z.ZodOptional<z.ZodEnum<{
+        email: "email";
+        copy: "copy";
+    }>>;
+}, z.core.$strict>;
+export declare const adminCommerceOrderUpdateShippingAddressRequestSchema: z.ZodObject<{
+    idempotencyKey: z.ZodString;
+    orderId: z.ZodGUID;
+    expectedRevision: z.ZodNumber;
+    expectedContactDigest: z.ZodString;
+    address: z.ZodObject<{
+        recipientName: z.ZodString;
+        contactEmail: z.ZodString;
+        line1: z.ZodString;
+        line2: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        city: z.ZodString;
+        postalCode: z.ZodString;
+        country: z.ZodString;
+        contactPhone: z.ZodString;
+        deliveryInstructions: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        courierInstructions: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strict>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;

package/dist/commerce/oms/omsContractRequests.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { commerceOrderModeSchema, omsAccountingStatusSchema, omsAttentionReasonSchema, omsFulfillmentStatusSchema, omsHoldReasonSchema, omsInventoryStatusSchema, omsNextActionSchema, omsPaymentStatusSchema, omsProviderOpsStatusSchema, uuidSchema, } from "./omsContractBase.js";
+import { orderStatusSchema } from "../contractPrimitives.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",
+];
+// 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/dist/commerce/oms/omsContracts.d.ts

@@ -0,0 +1,5 @@
+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/dist/commerce/oms/omsContracts.js

@@ -0,0 +1,4 @@
+export * from "./omsContractBase.js";
+export { omsDeliveryContactResolutionSchema } from "./omsContractReadAuxSchemas.js";
+export * from "./omsContractReadSchemas.js";
+export * from "./omsContractRequests.js";