@openlup/platform 0.26.0 → 0.27.0

package/dist/commerce/oms/omsControlPlane.d.ts

@@ -0,0 +1,275 @@
+import { z } from "zod";
+import type { OmsControlPlaneOrder } from "../contracts/omsTypes.js";
+export type { CommerceOmsControlPlanePort, CommerceOmsOperatorResolver, OmsControlPlaneDetailRequest, OmsControlPlaneDetailResponse, OmsControlPlaneListRequest, OmsControlPlaneListResponse, OmsControlPlaneOrder } from "../contracts/omsTypes.js";
+export declare const OMS_CONTROL_PLANE_VERSION: "commerce.oms_control_plane.v1";
+export declare const OMS_CONTROL_PLANE_VIEW: "control_plane_v1";
+export declare const omsControlPlaneListRequestSchema: z.ZodObject<{
+    view: z.ZodLiteral<"control_plane_v1">;
+    page: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    pageSize: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    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";
+    }>>;
+}, z.core.$strict>;
+export declare const omsControlPlaneDetailRequestSchema: z.ZodObject<{
+    view: z.ZodLiteral<"control_plane_v1">;
+    orderId: z.ZodGUID;
+}, z.core.$strict>;
+export declare const omsControlPlaneHoldSchema: z.ZodObject<{
+    id: z.ZodGUID;
+    status: z.ZodEnum<{
+        active: "active";
+        released: "released";
+    }>;
+    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.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    releasedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const omsControlPlaneOperationSchema: z.ZodObject<{
+    id: z.ZodGUID;
+    action: z.ZodEnum<{
+        hold_created: "hold_created";
+        hold_released: "hold_released";
+        order_cancelled: "order_cancelled";
+        order_refunded: "order_refunded";
+    }>;
+    holdId: z.ZodNullable<z.ZodGUID>;
+    actorId: z.ZodNullable<z.ZodGUID>;
+    occurredAt: z.ZodString;
+}, z.core.$strict>;
+export declare const omsControlPlaneOrderSchema: z.ZodObject<{
+    orderId: z.ZodGUID;
+    status: z.ZodEnum<{
+        draft: "draft";
+        expired: "expired";
+        pending_payment: "pending_payment";
+        paid: "paid";
+        failed: "failed";
+        fulfillment_pending: "fulfillment_pending";
+        cancelled: "cancelled";
+        fulfilled: "fulfilled";
+        refunded: "refunded";
+    }>;
+    sourceKind: z.ZodString;
+    sourceOrderRef: z.ZodNullable<z.ZodString>;
+    money: z.ZodNullable<z.ZodObject<{
+        amountMinor: z.ZodNumber;
+        currency: z.ZodString;
+    }, z.core.$strict>>;
+    shipmentStatus: z.ZodNullable<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";
+    }>>;
+    activeHoldCount: z.ZodNumber;
+    activeHoldReasons: z.ZodArray<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";
+    }>>;
+    actions: z.ZodObject<{
+        createHold: z.ZodObject<{
+            allowed: z.ZodBoolean;
+            reason: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        releaseHold: z.ZodObject<{
+            allowed: z.ZodBoolean;
+            reason: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        cancelOrder: z.ZodObject<{
+            allowed: z.ZodBoolean;
+            reason: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+        markRefunded: z.ZodObject<{
+            allowed: z.ZodBoolean;
+            reason: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strict>;
+export declare const omsControlPlaneListResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"commerce.oms_control_plane.v1">;
+    orders: z.ZodArray<z.ZodObject<{
+        orderId: z.ZodGUID;
+        status: z.ZodEnum<{
+            draft: "draft";
+            expired: "expired";
+            pending_payment: "pending_payment";
+            paid: "paid";
+            failed: "failed";
+            fulfillment_pending: "fulfillment_pending";
+            cancelled: "cancelled";
+            fulfilled: "fulfilled";
+            refunded: "refunded";
+        }>;
+        sourceKind: z.ZodString;
+        sourceOrderRef: z.ZodNullable<z.ZodString>;
+        money: z.ZodNullable<z.ZodObject<{
+            amountMinor: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strict>>;
+        shipmentStatus: z.ZodNullable<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";
+        }>>;
+        activeHoldCount: z.ZodNumber;
+        activeHoldReasons: z.ZodArray<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";
+        }>>;
+        actions: z.ZodObject<{
+            createHold: z.ZodObject<{
+                allowed: z.ZodBoolean;
+                reason: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            releaseHold: z.ZodObject<{
+                allowed: z.ZodBoolean;
+                reason: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            cancelOrder: z.ZodObject<{
+                allowed: z.ZodBoolean;
+                reason: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            markRefunded: z.ZodObject<{
+                allowed: z.ZodBoolean;
+                reason: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strict>>;
+    totalCount: z.ZodNumber;
+    page: z.ZodNumber;
+    pageSize: z.ZodNumber;
+}, z.core.$strict>;
+export declare const omsControlPlaneDetailResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<"commerce.oms_control_plane.v1">;
+    order: z.ZodObject<{
+        orderId: z.ZodGUID;
+        status: z.ZodEnum<{
+            draft: "draft";
+            expired: "expired";
+            pending_payment: "pending_payment";
+            paid: "paid";
+            failed: "failed";
+            fulfillment_pending: "fulfillment_pending";
+            cancelled: "cancelled";
+            fulfilled: "fulfilled";
+            refunded: "refunded";
+        }>;
+        sourceKind: z.ZodString;
+        sourceOrderRef: z.ZodNullable<z.ZodString>;
+        money: z.ZodNullable<z.ZodObject<{
+            amountMinor: z.ZodNumber;
+            currency: z.ZodString;
+        }, z.core.$strict>>;
+        shipmentStatus: z.ZodNullable<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";
+        }>>;
+        activeHoldCount: z.ZodNumber;
+        activeHoldReasons: z.ZodArray<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";
+        }>>;
+        actions: z.ZodObject<{
+            createHold: z.ZodObject<{
+                allowed: z.ZodBoolean;
+                reason: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            releaseHold: z.ZodObject<{
+                allowed: z.ZodBoolean;
+                reason: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            cancelOrder: z.ZodObject<{
+                allowed: z.ZodBoolean;
+                reason: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+            markRefunded: z.ZodObject<{
+                allowed: z.ZodBoolean;
+                reason: z.ZodNullable<z.ZodString>;
+            }, z.core.$strict>;
+        }, z.core.$strict>;
+        createdAt: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strict>;
+    holds: z.ZodArray<z.ZodObject<{
+        id: z.ZodGUID;
+        status: z.ZodEnum<{
+            active: "active";
+            released: "released";
+        }>;
+        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.ZodNullable<z.ZodString>;
+        createdAt: z.ZodString;
+        releasedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>;
+    operations: z.ZodArray<z.ZodObject<{
+        id: z.ZodGUID;
+        action: z.ZodEnum<{
+            hold_created: "hold_created";
+            hold_released: "hold_released";
+            order_cancelled: "order_cancelled";
+            order_refunded: "order_refunded";
+        }>;
+        holdId: z.ZodNullable<z.ZodGUID>;
+        actorId: z.ZodNullable<z.ZodGUID>;
+        occurredAt: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare function omsControlPlaneActions(status: OmsControlPlaneOrder["status"], activeHoldCount: number): OmsControlPlaneOrder["actions"];

package/dist/commerce/oms/omsControlPlane.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { datetimeSchema, actionEligibilitySchema as eligibilitySchema, omsFulfillmentStatusSchema, omsHoldReasonSchema, omsHoldStatusSchema, uuidSchema } from "./omsContractBase.js";
+import { orderStatusSchema } from "../contractPrimitives.js";
+export const OMS_CONTROL_PLANE_VERSION = "commerce.oms_control_plane.v1";
+export const OMS_CONTROL_PLANE_VIEW = "control_plane_v1";
+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, activeHoldCount) {
+    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" },
+    };
+}

package/dist/commerce/oms/omsFulfillmentContractSchemas.d.ts

@@ -0,0 +1,203 @@
+import { z } from "zod";
+import type { OmsReplacementChain } from "../contracts/omsTypes.js";
+export type { OmsReplacementChain } from "../contracts/omsTypes.js";
+export declare const omsProviderOpsSlaSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        ok: "ok";
+        watch: "watch";
+        breached: "breached";
+        paused_non_shipping_day: "paused_non_shipping_day";
+    }>;
+    dispatchedAt: z.ZodNullable<z.ZodString>;
+    deadlineAt: z.ZodNullable<z.ZodString>;
+    remainingOperationalMinutes: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strict>;
+export declare const omsFulfillmentTrackingReferenceSchema: z.ZodObject<{
+    providerKind: z.ZodString;
+    trackingNumber: z.ZodString;
+    trackingUrl: z.ZodNullable<z.ZodString>;
+    carrierKind: z.ZodNullable<z.ZodString>;
+    service: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export declare const omsFulfillmentTimelineEventSchema: z.ZodObject<{
+    eventType: z.ZodString;
+    label: z.ZodString;
+    occurredAt: z.ZodNullable<z.ZodString>;
+    source: z.ZodEnum<{
+        provider: "provider";
+        webhook: "webhook";
+        reconciliation: "reconciliation";
+        manual: "manual";
+        simulator: "simulator";
+        fulfillment: "fulfillment";
+        dispatch: "dispatch";
+    }>;
+}, z.core.$strict>;
+export declare const omsSubscriptionContextSchema: z.ZodObject<{
+    subscriptionId: z.ZodNullable<z.ZodGUID>;
+    subscriptionCycleId: z.ZodNullable<z.ZodGUID>;
+    subscriptionCycleStatus: z.ZodNullable<z.ZodEnum<{
+        paid: "paid";
+        cancelled: "cancelled";
+        planned: "planned";
+        skipped: "skipped";
+        payment_pending: "payment_pending";
+        payment_failed: "payment_failed";
+        retry_scheduled: "retry_scheduled";
+    }>>;
+    nextCycleAt: z.ZodNullable<z.ZodString>;
+    cyclePaidAt: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const omsInventorySummarySchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        expired: "expired";
+        not_checked: "not_checked";
+        reserved: "reserved";
+        missing: "missing";
+        released: "released";
+        consumed: "consumed";
+        review_required: "review_required";
+    }>;
+    reservationId: z.ZodNullable<z.ZodGUID>;
+    reservationStatus: z.ZodNullable<z.ZodEnum<{
+        expired: "expired";
+        reserved: "reserved";
+        released: "released";
+        consumed: "consumed";
+    }>>;
+    expiresAt: z.ZodNullable<z.ZodString>;
+    locationId: z.ZodNullable<z.ZodGUID>;
+    locationCode: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const omsFulfillmentSummarySchema: z.ZodObject<{
+    fulfillmentOrderId: z.ZodNullable<z.ZodGUID>;
+    status: z.ZodNullable<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";
+    }>>;
+    providerKind: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    latestOperationType: z.ZodNullable<z.ZodString>;
+    latestOperationAt: z.ZodNullable<z.ZodString>;
+    providerTrackingId: z.ZodNullable<z.ZodString>;
+    trackingUrl: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    carrierKind: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    service: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    trackingReferences: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        providerKind: z.ZodString;
+        trackingNumber: z.ZodString;
+        trackingUrl: z.ZodNullable<z.ZodString>;
+        carrierKind: z.ZodNullable<z.ZodString>;
+        service: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>;
+    trackingTimeline: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        eventType: z.ZodString;
+        label: z.ZodString;
+        occurredAt: z.ZodNullable<z.ZodString>;
+        source: z.ZodEnum<{
+            provider: "provider";
+            webhook: "webhook";
+            reconciliation: "reconciliation";
+            manual: "manual";
+            simulator: "simulator";
+            fulfillment: "fulfillment";
+            dispatch: "dispatch";
+        }>;
+    }, z.core.$strict>>>;
+    providerEvidence: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodObject<{
+        evidenceType: z.ZodEnum<{
+            dispatch_ref: "dispatch_ref";
+            provider_attempt: "provider_attempt";
+            status_evidence: "status_evidence";
+        }>;
+        status: z.ZodNullable<z.ZodString>;
+        providerStatus: z.ZodNullable<z.ZodString>;
+        providerOrderId: z.ZodNullable<z.ZodString>;
+        evidenceKind: z.ZodNullable<z.ZodString>;
+        occurredAt: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodNullable<z.ZodString>;
+        summary: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>>;
+}, z.core.$strip>;
+/**
+ * The order's replacement chain, detail-only.
+ *
+ * ⛔ This is NOT a second fulfilment summary. `fulfillment` stays exactly what W3 collapsed it
+ * to - one row, the parcel currently representing the order, with every companion narrowed to
+ * that parcel's id. Widening those companions was measured and rejected: the dispatch refs,
+ * provider attempts and status evidence of a superseded parcel would then be read by the
+ * fulfilment health classifier, the fulfilment debug panel and the customer-step derivation,
+ * each of which would answer for the wrong parcel - a dispatch status of `created` for a
+ * replacement that has never been dispatched, or a customer step of `delivered` for a parcel
+ * that is still `created`.
+ *
+ * So the superseded parcels carry their own, deliberately small payload: what a support agent
+ * needs to answer "where did the first one go?" and to file a carrier claim. Tracking number,
+ * carrier, service, the two handover instants, and the parcel's own status.
+ */
+export declare const omsSupersededParcelSchema: z.ZodObject<{
+    fulfillmentOrderId: z.ZodGUID;
+    sequenceNo: z.ZodNumber;
+    status: z.ZodNullable<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";
+    }>>;
+    replacementReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    handedOverAt: z.ZodNullable<z.ZodString>;
+    deliveredAt: z.ZodNullable<z.ZodString>;
+    trackingReferences: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        providerKind: z.ZodString;
+        trackingNumber: z.ZodString;
+        trackingUrl: z.ZodNullable<z.ZodString>;
+        carrierKind: z.ZodNullable<z.ZodString>;
+        service: z.ZodNullable<z.ZodString>;
+        updatedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const omsReplacementChainSchema: z.ZodObject<{
+    sequenceNo: z.ZodNumber;
+    replacesFulfillmentOrderId: z.ZodNullable<z.ZodGUID>;
+    replacementReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    supersededParcels: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        fulfillmentOrderId: z.ZodGUID;
+        sequenceNo: z.ZodNumber;
+        status: z.ZodNullable<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";
+        }>>;
+        replacementReason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        handedOverAt: z.ZodNullable<z.ZodString>;
+        deliveredAt: z.ZodNullable<z.ZodString>;
+        trackingReferences: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            providerKind: z.ZodString;
+            trackingNumber: z.ZodString;
+            trackingUrl: z.ZodNullable<z.ZodString>;
+            carrierKind: z.ZodNullable<z.ZodString>;
+            service: z.ZodNullable<z.ZodString>;
+            updatedAt: z.ZodNullable<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const defaultOmsReplacementChain: OmsReplacementChain;

package/dist/commerce/oms/omsFulfillmentContractSchemas.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { datetimeSchema, nullableTextSchema, omsFulfillmentStatusSchema, omsInventoryStatusSchema, omsProviderOpsSlaStatusSchema, omsSubscriptionCycleStatusSchema, uuidSchema, } from "./omsContractBase.js";
+import { omsProviderEvidenceSchema } from "./omsProviderEvidenceSchemas.js";
+export const omsProviderOpsSlaSchema = z.object({
+    status: omsProviderOpsSlaStatusSchema,
+    dispatchedAt: datetimeSchema.nullable(),
+    deadlineAt: datetimeSchema.nullable(),
+    remainingOperationalMinutes: z.number().int().min(0).nullable(),
+}).strict();
+export const omsFulfillmentTrackingReferenceSchema = z.object({
+    providerKind: z.string().min(1),
+    trackingNumber: z.string().min(1),
+    trackingUrl: nullableTextSchema,
+    carrierKind: nullableTextSchema,
+    service: nullableTextSchema,
+    updatedAt: datetimeSchema.nullable(),
+}).strict();
+export const omsFulfillmentTimelineEventSchema = z.object({
+    eventType: z.string().min(1),
+    label: z.string().min(1),
+    occurredAt: datetimeSchema.nullable(),
+    source: z.enum(["webhook", "reconciliation", "manual", "simulator", "fulfillment", "dispatch", "provider"]),
+}).strict();
+export const omsSubscriptionContextSchema = z.object({
+    subscriptionId: uuidSchema.nullable(),
+    subscriptionCycleId: uuidSchema.nullable(),
+    subscriptionCycleStatus: omsSubscriptionCycleStatusSchema.nullable(),
+    // Operator-facing dates. `nextCycleAt` is `subscriptions.next_cycle_at` (the
+    // next CHARGE instant, not a delivery date); `cyclePaidAt` is this cycle's
+    // `subscription_cycles.paid_at`. Both nullable: `commerce_orders` has no
+    // `paid_at`, so one-time orders carry neither.
+    nextCycleAt: datetimeSchema.nullable(),
+    cyclePaidAt: datetimeSchema.nullable(),
+});
+export const omsInventorySummarySchema = z.object({
+    status: omsInventoryStatusSchema,
+    reservationId: uuidSchema.nullable(),
+    reservationStatus: z.enum(["reserved", "released", "consumed", "expired"]).nullable(),
+    expiresAt: datetimeSchema.nullable(),
+    locationId: uuidSchema.nullable(),
+    locationCode: z.string().nullable(),
+});
+export const omsFulfillmentSummarySchema = z.object({
+    fulfillmentOrderId: uuidSchema.nullable(),
+    status: omsFulfillmentStatusSchema.nullable(),
+    providerKind: nullableTextSchema.default(null),
+    latestOperationType: z.string().min(1).nullable(),
+    latestOperationAt: datetimeSchema.nullable(),
+    providerTrackingId: z.string().min(1).nullable(),
+    trackingUrl: nullableTextSchema.default(null),
+    carrierKind: nullableTextSchema.default(null),
+    service: nullableTextSchema.default(null),
+    trackingReferences: z.array(omsFulfillmentTrackingReferenceSchema).default([]),
+    trackingTimeline: z.array(omsFulfillmentTimelineEventSchema).default([]),
+    providerEvidence: z.array(omsProviderEvidenceSchema).optional().default([]),
+});
+/**
+ * The order's replacement chain, detail-only.
+ *
+ * ⛔ This is NOT a second fulfilment summary. `fulfillment` stays exactly what W3 collapsed it
+ * to - one row, the parcel currently representing the order, with every companion narrowed to
+ * that parcel's id. Widening those companions was measured and rejected: the dispatch refs,
+ * provider attempts and status evidence of a superseded parcel would then be read by the
+ * fulfilment health classifier, the fulfilment debug panel and the customer-step derivation,
+ * each of which would answer for the wrong parcel - a dispatch status of `created` for a
+ * replacement that has never been dispatched, or a customer step of `delivered` for a parcel
+ * that is still `created`.
+ *
+ * So the superseded parcels carry their own, deliberately small payload: what a support agent
+ * needs to answer "where did the first one go?" and to file a carrier claim. Tracking number,
+ * carrier, service, the two handover instants, and the parcel's own status.
+ */
+export const omsSupersededParcelSchema = z.object({
+    fulfillmentOrderId: uuidSchema,
+    sequenceNo: z.number().int().min(0),
+    status: omsFulfillmentStatusSchema.nullable(),
+    replacementReason: nullableTextSchema.default(null),
+    handedOverAt: datetimeSchema.nullable(),
+    deliveredAt: datetimeSchema.nullable(),
+    trackingReferences: z.array(omsFulfillmentTrackingReferenceSchema).default([]),
+}).strict();
+export const omsReplacementChainSchema = z.object({
+    // `sequenceNo` 0 is the ordinary order: one parcel, no replacement, nothing to disclose.
+    sequenceNo: z.number().int().min(0),
+    replacesFulfillmentOrderId: uuidSchema.nullable(),
+    replacementReason: nullableTextSchema.default(null),
+    supersededParcels: z.array(omsSupersededParcelSchema).default([]),
+}).strict();
+export const defaultOmsReplacementChain = {
+    sequenceNo: 0,
+    replacesFulfillmentOrderId: null,
+    replacementReason: null,
+    supersededParcels: [],
+};