@openlup/platform 0.26.0 → 0.27.0

package/dist/commerce/model/omsReadModel.d.ts

@@ -0,0 +1,43 @@
+import type { SubscriptionCycleStatus } from "@openlup/core/subscription";
+import { type AdminCommerceOrderDetailResponse, type OmsDeliveryContactResolution, type OmsOrderDetail } from "../oms/omsContracts.js";
+import { type OmsFulfillmentProviderStockCurrentRow, type OmsInboundProviderEventRow } from "./omsFulfillmentDebug.js";
+import { type OmsFulfillmentOperationRow, type OmsFulfillmentOrderRow, type OmsProviderAttemptRow, type OmsProviderDispatchRefRow, type OmsProviderStatusEvidenceRow, type OmsReleasedProviderExceptionHoldRow, type OmsShipmentExternalRefRow } from "./omsFulfillmentSummary.js";
+import { type OmsActionAvailabilityFlags } from "./omsReadModelHelpers.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import type { OmsAccountingInvoiceRow, OmsAccountingOutboxRow, OmsAddressRow, OmsCommunicationDeliveryRow, OmsCustomerRow, OmsHoldRow, OmsInventoryReservationRow, OmsOperationRow, OmsOrderItemRow, OmsOrderRow, OmsPaymentAttemptRow, OmsPaymentIntentRow, OmsPaymentTransitionRow } from "./omsReadModelRows.js";
+export { buildOmsOrderListResponse } from "./omsReadModelList.js";
+export type { OmsAccountingInvoiceRow, OmsAccountingOutboxRow, OmsAddressRow, OmsCommunicationDeliveryRow, OmsCustomerRow, OmsHoldRow, OmsInventoryReservationRow, OmsOperationRow, OmsOrderItemRow, OmsOrderRow, OmsPaymentAttemptRow, OmsPaymentIntentRow, OmsPaymentTransitionRow } from "./omsReadModelRows.js";
+export declare function buildOmsOrderDetailResponse(input: {
+    order: OmsOrderRow;
+    identityExtras?: Record<string, unknown>;
+    projections?: OmsReadModelProjections;
+    paymentIntent: OmsPaymentIntentRow | null;
+    paymentAttempts: OmsPaymentAttemptRow[];
+    paymentTransitions: OmsPaymentTransitionRow[];
+    holds: OmsHoldRow[];
+    operations: OmsOperationRow[];
+    customer?: OmsCustomerRow | null;
+    shippingAddress?: OmsAddressRow | null;
+    billingAddress?: OmsAddressRow | null;
+    accountingInvoice?: OmsAccountingInvoiceRow | null;
+    accountingOutbox?: OmsAccountingOutboxRow[];
+    communicationDeliveries?: OmsCommunicationDeliveryRow[];
+    orderItems?: OmsOrderItemRow[];
+    inventoryReservations?: OmsInventoryReservationRow[];
+    fulfillmentOrders?: OmsFulfillmentOrderRow[];
+    fulfillmentOperations?: OmsFulfillmentOperationRow[];
+    supersededFulfillmentOrders?: OmsFulfillmentOrderRow[];
+    shipmentExternalRefs?: OmsShipmentExternalRefRow[];
+    providerAttempts?: OmsProviderAttemptRow[];
+    providerDispatchRefs?: OmsProviderDispatchRefRow[];
+    providerStatusEvidence?: OmsProviderStatusEvidenceRow[];
+    releasedProviderExceptionHolds?: OmsReleasedProviderExceptionHoldRow[];
+    fulfillmentHealth?: OmsOrderDetail["fulfillmentHealth"];
+    inboundProviderEvents?: OmsInboundProviderEventRow[];
+    providerStockCurrent?: OmsFulfillmentProviderStockCurrentRow[];
+    subscriptionCycleStatus: SubscriptionCycleStatus | null;
+    subscriptionCyclePaidAt?: string | null;
+    subscriptionNextCycleAt?: string | null;
+    actionFlags?: OmsActionAvailabilityFlags;
+    deliveryContactResolution?: OmsDeliveryContactResolution;
+}): AdminCommerceOrderDetailResponse;

package/dist/commerce/model/omsReadModel.js

@@ -0,0 +1,211 @@
+import { parcelSequenceNo } from "@openlup/core/fulfillment";
+import { resolveDeliverySelectionEvidence, summarizeDeliverySelection, } from "../../shipping/index.js";
+import { adminCommerceOrderDetailResponseSchema, } from "../oms/omsContracts.js";
+import { enrichBillingWithInvoiceBuyer } from "./omsBillingInvoiceBuyer.js";
+import { buildOmsFulfillmentDebug, } from "./omsFulfillmentDebug.js";
+import { mapOmsOrderLine } from "./omsOrderLineMoney.js";
+import { mapCommunicationDelivery } from "./omsReadModelCommunication.js";
+import { actionEligibility, mapAddress, mapCustomer, } from "./omsReadModelHelpers.js";
+import { deriveOmsOrderMoney } from "./omsReadModelPricing.js";
+import { buildCurrentDeliveryContact, buildOmsOrderRowCore } from "./omsReadModelRowCore.js";
+import { COMMERCE_CONTRACT_VERSION } from "../../pricing/contracts/index.js";
+export { buildOmsOrderListResponse } from "./omsReadModelList.js";
+export function buildOmsOrderDetailResponse(input) {
+    const activeHoldCount = input.holds.filter((hold) => hold.status === "active").length;
+    const orderItems = input.orderItems;
+    const orderMoney = deriveOmsOrderMoney(input.order, orderItems);
+    const { row: order, paymentStatus, inventory, fulfillment, accounting, fulfillmentEligibility, } = buildOmsOrderRowCore({
+        projections: input.projections,
+        order: input.order,
+        activeHoldCount,
+        paymentIntents: input.paymentIntent ? [input.paymentIntent] : [],
+        paymentAttempts: input.paymentAttempts,
+        identity: { customer: mapCustomer(input.customer ?? null), ...input.identityExtras },
+        orderItems,
+        inventoryReservations: input.inventoryReservations ?? [],
+        fulfillmentOrders: input.fulfillmentOrders ?? [],
+        fulfillmentOperations: input.fulfillmentOperations ?? [],
+        shipmentExternalRefs: input.shipmentExternalRefs ?? [],
+        providerAttempts: input.providerAttempts ?? [],
+        dispatchRefs: input.providerDispatchRefs ?? [],
+        statusEvidence: input.providerStatusEvidence ?? [],
+        releasedProviderExceptionHolds: input.releasedProviderExceptionHolds,
+        accountingInvoice: input.accountingInvoice ?? null,
+        accountingOutbox: input.accountingOutbox ?? [],
+        subscriptionCycleStatus: input.subscriptionCycleStatus,
+        orderMoney,
+    });
+    const fulfillmentHealth = buildOmsFulfillmentHealth({ orderId: input.order.id, fulfillmentHealth: input.fulfillmentHealth });
+    const { deliveryContact, effectiveShippingAddress } = buildCurrentDeliveryContact({
+        resolution: input.deliveryContactResolution ?? { resolutionVersion: 1, scope: "missing", baseline: null, contact: null, contactDigest: null },
+        shippingAddressId: input.order.shipping_address_id,
+        fulfillmentOrders: input.fulfillmentOrders ?? [],
+        dispatchRefs: input.providerDispatchRefs ?? [],
+    });
+    const detail = {
+        ...order,
+        ...input.projections?.detailFields?.({ order: input.order, orderItems, orderMoney }),
+        activeHoldReasons: [...new Set(input.holds.filter((hold) => hold.status === "active").map((hold) => hold.reason))],
+        fulfillmentHealthDigest: { healthStatus: fulfillmentHealth.healthStatus, attentionReasons: fulfillmentHealth.attentionReasons },
+        shippingAddress: deliveryContact.scope === "missing"
+            ? mapAddress(input.shippingAddress ?? null)
+            : effectiveShippingAddress,
+        deliveryContact,
+        billingAddress: enrichBillingWithInvoiceBuyer(mapAddress(input.billingAddress ?? input.shippingAddress ?? null), input.order.metadata),
+        deliverySelection: (() => {
+            const evidence = resolveDeliverySelectionEvidence({ orderMetadata: input.order.metadata });
+            const summary = summarizeDeliverySelection(evidence.selection, evidence.source);
+            return summary ? { ...summary, source: summary.source ?? null } : null;
+        })(),
+        lines: (orderItems ?? []).map((item, index) => mapOmsOrderLine(item, input.order.currency, orderMoney.lines[index])),
+        subscription: {
+            subscriptionId: input.order.subscription_id,
+            subscriptionCycleId: input.order.subscription_cycle_id,
+            subscriptionCycleStatus: input.subscriptionCycleStatus,
+            nextCycleAt: input.subscriptionNextCycleAt ?? null,
+            cyclePaidAt: input.subscriptionCyclePaidAt ?? null,
+        },
+        fulfillmentEligibility,
+        inventory,
+        fulfillment,
+        replacementChain: buildOmsReplacementChain({
+            currentParcel: (input.fulfillmentOrders ?? [])[0] ?? null,
+            supersededParcels: input.supersededFulfillmentOrders ?? [],
+            shipmentExternalRefs: input.shipmentExternalRefs ?? [],
+        }),
+        fulfillmentHealth,
+        fulfillmentDebug: buildOmsFulfillmentDebug({
+            projections: input.projections,
+            paymentStatus,
+            inventory,
+            fulfillment,
+            reservations: input.inventoryReservations ?? [],
+            communicationDeliveries: input.communicationDeliveries ?? [],
+            providerAttempts: input.providerAttempts ?? [],
+            providerDispatchRefs: input.providerDispatchRefs ?? [],
+            providerStatusEvidence: input.providerStatusEvidence ?? [],
+            inboundProviderEvents: input.inboundProviderEvents ?? [],
+            providerStockCurrent: input.providerStockCurrent ?? [],
+        }),
+        accounting,
+        actionEligibility: actionEligibility({
+            fulfillmentEligibility,
+            activeHoldCount,
+            fulfillmentStatus: fulfillment.status,
+            hasFulfillmentOrder: Boolean(fulfillment.fulfillmentOrderId),
+            hasShippingAddress: Boolean(input.order.shipping_address_id),
+            deliveryContact,
+            orderStatus: input.order.status,
+            orderMode: input.order.mode,
+            providerCancellationConfirmed: hasLatestProviderCancellation(input.providerStatusEvidence ?? [], fulfillment.fulfillmentOrderId),
+            flags: input.actionFlags,
+        }),
+        holds: input.holds.map((hold) => ({
+            id: hold.id,
+            orderId: hold.order_id,
+            status: hold.status,
+            reason: hold.reason,
+            note: hold.note,
+            createdAt: hold.created_at,
+            releasedAt: hold.released_at,
+        })),
+        operations: input.operations.map((operation) => ({
+            id: operation.id,
+            orderId: operation.order_id,
+            type: operation.operation_type,
+            holdId: operation.hold_id,
+            actorUserId: operation.actor_user_id,
+            occurredAt: operation.occurred_at,
+            payload: operation.payload,
+        })),
+        payment: {
+            intentId: input.paymentIntent?.id ?? null,
+            paymentId: input.paymentIntent?.payment_id ?? null,
+            status: paymentStatus,
+            activeAttemptId: input.paymentIntent?.active_attempt_id ?? null,
+            providerPaymentId: input.paymentIntent?.provider_payment_id ?? null,
+            updatedAt: input.paymentIntent?.updated_at ?? null,
+        },
+        paymentAttempts: input.paymentAttempts.map((attempt) => ({
+            id: attempt.id,
+            status: attempt.status,
+            provider: attempt.provider,
+            providerAttemptId: attempt.provider_attempt_id,
+            nextActionKind: attempt.next_action_kind,
+            updatedAt: attempt.updated_at,
+        })),
+        paymentTransitions: input.paymentTransitions.map((transition) => ({
+            id: transition.id,
+            transitionKind: transition.transition_kind,
+            fromStatus: transition.from_status,
+            toStatus: transition.to_status,
+            reason: transition.reason,
+            occurredAt: transition.occurred_at,
+        })),
+        communicationDeliveries: (input.communicationDeliveries ?? []).map(mapCommunicationDelivery),
+    };
+    return (input.projections?.parseDetail ?? (value => adminCommerceOrderDetailResponseSchema.parse(value)))({
+        contractVersion: COMMERCE_CONTRACT_VERSION,
+        order: detail,
+    });
+}
+function hasLatestProviderCancellation(evidence, fulfillmentOrderId) {
+    if (!fulfillmentOrderId)
+        return false;
+    const latest = evidence
+        .filter((row) => row.fulfillment_order_id === fulfillmentOrderId)
+        .sort((left, right) => evidenceTimestamp(right) - evidenceTimestamp(left))[0];
+    return latest?.provider_status?.trim().toUpperCase() === "CANCELLED";
+}
+function evidenceTimestamp(row) {
+    const raw = row.occurred_at ?? row.created_at;
+    const parsed = raw ? Date.parse(raw) : Number.NaN;
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/**
+ * The order's replacement chain, from rows the detail read already holds.
+ *
+ * ⛔ Attribution here is STRICT, unlike `rowsForParcel`: a tracking reference that names no
+ * parcel belongs to whichever parcel is asking, which is right for the current parcel and
+ * wrong here - it would print one legacy reference under every superseded parcel as if the
+ * carrier had issued it several times. A superseded parcel shows only references that name it.
+ */
+function buildOmsReplacementChain(input) {
+    return {
+        sequenceNo: input.currentParcel ? parcelSequenceNo(input.currentParcel) : 0,
+        replacesFulfillmentOrderId: input.currentParcel?.replaces_fulfillment_order_id ?? null,
+        replacementReason: input.currentParcel?.replacement_reason ?? null,
+        supersededParcels: input.supersededParcels.map((parcel) => ({
+            fulfillmentOrderId: parcel.id,
+            sequenceNo: parcelSequenceNo(parcel),
+            status: parcel.status ?? null,
+            replacementReason: parcel.replacement_reason ?? null,
+            handedOverAt: parcel.handed_over_at ?? null,
+            deliveredAt: parcel.delivered_at ?? null,
+            trackingReferences: input.shipmentExternalRefs
+                .filter((ref) => ref.fulfillment_order_id === parcel.id && ref.active !== false && Boolean(ref.provider_tracking_id))
+                .map((ref) => ({
+                providerKind: ref.provider_kind ?? "unknown",
+                trackingNumber: ref.provider_tracking_id,
+                trackingUrl: ref.tracking_url ?? null,
+                carrierKind: ref.carrier_kind ?? ref.provider_kind ?? null,
+                service: ref.service ?? null,
+                updatedAt: ref.updated_at ?? ref.created_at ?? null,
+            })),
+        })),
+    };
+}
+function buildOmsFulfillmentHealth(input) {
+    return input.fulfillmentHealth ?? {
+        healthStatus: "ok",
+        attentionReasons: [],
+        oldestAgeSeconds: null,
+        opaqueIds: {
+            orderId: input.orderId,
+            fulfillmentOrderId: null,
+            outboxEventId: null,
+            dispatchRefFulfillmentOrderId: null,
+            latestEvidenceFulfillmentOrderId: null,
+        },
+    };
+}

package/dist/commerce/model/omsReadModelCommunication.d.ts

@@ -0,0 +1,3 @@
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import type { OmsCommunicationDeliveryRow } from "./omsReadModelRows.js";
+export declare function mapCommunicationDelivery(row: OmsCommunicationDeliveryRow): OmsOrderDetail["communicationDeliveries"][number];

package/dist/commerce/model/omsReadModelCommunication.js

@@ -0,0 +1,29 @@
+export function mapCommunicationDelivery(row) {
+    return {
+        id: row.id,
+        purpose: row.purpose,
+        templateSlug: row.template_slug,
+        triggerSource: row.trigger_source,
+        triggerEvent: row.trigger_event,
+        aggregateType: row.aggregate_type,
+        aggregateId: row.aggregate_id,
+        dedupeKey: row.dedupe_key,
+        status: row.status,
+        providerKind: row.provider_kind,
+        providerMessageId: row.provider_message_id,
+        scheduledDueAt: row.scheduled_due_at,
+        expectedSendAt: row.expected_send_at,
+        queuedAt: row.queued_at,
+        firstAttemptAt: row.first_attempt_at,
+        sentAt: row.sent_at,
+        deliveredAt: row.delivered_at,
+        terminalAt: row.terminal_at,
+        lastErrorCode: row.last_error_code,
+        outboxEventId: row.outbox_event_id,
+        platformJobRunId: row.platform_job_run_id,
+        emailSendId: row.email_send_id,
+        metadata: row.metadata ?? {},
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}

package/dist/commerce/model/omsReadModelHelpers.d.ts

@@ -0,0 +1,125 @@
+import type { OmsActionAvailabilityFlags, OmsOrderIdentity } from "../contracts/omsTypes.js";
+import type { OmsAccountingStatus, OmsInventoryStatus, OmsOrderDetail, OmsOrderPaymentStatus } from "../oms/omsContracts.js";
+import type { OmsPaymentMethodSummary } from "./omsPaymentMethodSummary.js";
+import type { OmsAddressRow, OmsCustomerRow, OmsInventoryReservationRow, OmsOrderItemRow, OmsOrderRow, OmsPaymentIntentRow } from "./omsReadModelRows.js";
+import type { CanonicalOrderMoney } from "../orderMoney.js";
+export type { OmsActionAvailabilityFlags, OmsOrderIdentity } from "../contracts/omsTypes.js";
+export { buildOmsDeliveryContactProjection, deliveryContactAddress } from "./omsReadModelRowCore.js";
+export declare function findCustomer(order: OmsOrderRow, customers: OmsCustomerRow[]): OmsOrderDetail["customer"];
+export declare function mapCustomer(row: OmsCustomerRow | null): OmsOrderDetail["customer"];
+export declare function mapAddress(row: OmsAddressRow | null): OmsOrderDetail["shippingAddress"];
+export declare function evaluateOperationalState(input: {
+    order: OmsOrderRow;
+    paymentStatus: OmsOrderPaymentStatus;
+    activeHoldCount: number;
+    inventoryStatus: OmsInventoryStatus;
+    fulfillmentStatus: OmsOrderDetail["fulfillmentStatus"];
+    fulfillmentEligibility?: {
+        allowed: boolean;
+        reason: string | null;
+    };
+    accountingStatus: OmsAccountingStatus;
+}): Pick<OmsOrderDetail, "attentionReason" | "nextAction">;
+export declare function actionEligibility(input: {
+    fulfillmentEligibility: {
+        allowed: boolean;
+        reason: string | null;
+    };
+    activeHoldCount: number;
+    fulfillmentStatus: OmsOrderDetail["fulfillmentStatus"];
+    hasFulfillmentOrder: boolean;
+    hasShippingAddress: boolean;
+    deliveryContact?: NonNullable<OmsOrderDetail["deliveryContact"]>;
+    orderStatus: OmsOrderDetail["status"];
+    orderMode: "one_time" | "subscription_cycle";
+    providerCancellationConfirmed?: boolean;
+    flags?: OmsActionAvailabilityFlags;
+}): OmsOrderDetail["actionEligibility"];
+export declare function inventorySummary(reservations: OmsInventoryReservationRow[], orderItems: OmsOrderItemRow[]): OmsOrderDetail["inventory"];
+export declare function baseOrder(input: {
+    order: OmsOrderRow;
+    paymentStatus: OmsOrderPaymentStatus;
+    paymentMethod: OmsPaymentMethodSummary;
+    activeHoldCount: number;
+    identity: OmsOrderIdentity;
+    inventoryStatus: OmsInventoryStatus;
+    fulfillmentStatus: OmsOrderDetail["fulfillmentStatus"];
+    customerFulfillmentStep: OmsOrderDetail["customerFulfillmentStep"];
+    accountingStatus: OmsAccountingStatus;
+    providerOpsStatus: OmsOrderDetail["providerOpsStatus"];
+    providerOpsSla: OmsOrderDetail["providerOpsSla"];
+    providerOrderId: OmsOrderDetail["providerOrderId"];
+    attentionReason: OmsOrderDetail["attentionReason"];
+    nextAction: OmsOrderDetail["nextAction"];
+    orderItems?: OmsOrderItemRow[];
+    orderMoney?: CanonicalOrderMoney;
+}): {
+    status: "draft" | "expired" | "pending_payment" | "paid" | "failed" | "fulfillment_pending" | "cancelled" | "fulfilled" | "refunded";
+    mode: "one_time" | "subscription_cycle";
+    sourceKind: string | undefined;
+    sourceChannelSlug: string | undefined;
+    sourceOrderRef: string | undefined;
+    paymentMethodLabel: string | null;
+    paymentProvider: string | null;
+    paymentStatus: OmsOrderPaymentStatus;
+    fulfillmentStatus: "created" | "cancelled" | "delivered" | "packed" | "label_pending" | "label_created" | "handed_over" | "in_transit" | "exception" | null;
+    customerFulfillmentStep: "paid" | "cancelled" | "delivered" | "exception" | "accepted" | "packing" | "transit";
+    inventoryStatus: "expired" | "not_checked" | "reserved" | "missing" | "released" | "consumed" | "review_required";
+    accountingStatus: string;
+    providerOpsStatus: string;
+    providerOpsSla: {
+        status: "ok" | "watch" | "breached" | "paused_non_shipping_day";
+        dispatchedAt: null | string;
+        deadlineAt: null | string;
+        remainingOperationalMinutes: null | number;
+    } | null;
+    providerOrderId: string | null;
+    attentionReason: import("../contracts/omsTypes.js").AdminOmsAttentionReason;
+    nextAction: import("../contracts/omsTypes.js").AdminOmsNextAction;
+    activeHoldCount: number;
+    total: {
+        amountMinor: number;
+        currency: string;
+    };
+    pricingSummary: {
+        subtotal: {
+            amountMinor: number;
+            currency: string;
+        };
+        productDiscount: {
+            amountMinor: number;
+            currency: string;
+        };
+        shipping: {
+            amountMinor: number;
+            currency: string;
+        };
+        shippingDiscount: {
+            amountMinor: number;
+            currency: string;
+        };
+        discountTotal: {
+            amountMinor: number;
+            currency: string;
+        };
+        finalTotal: {
+            amountMinor: number;
+            currency: string;
+        };
+        source: "order_columns";
+    };
+    createdAt: string;
+    updatedAt: string;
+    customer: null | {
+        id: string;
+        email: string;
+        firstName: null | string;
+        lastName: null | string;
+        phone: null | string;
+        lifecycleStage: null | string;
+    };
+    orderId: string;
+    orderNumber: string | null;
+    clientId: string | null;
+};
+export declare function paymentStatusForOrder(orderId: string, paymentIntents: OmsPaymentIntentRow[]): OmsOrderPaymentStatus;

package/dist/commerce/model/omsReadModelHelpers.js

@@ -0,0 +1,212 @@
+import { canCancelFulfillment } from "./fulfillmentCancellationEligibility.js";
+import { resolveOmsOperationalState } from "./omsOperationalLadder.js";
+import { pricingSummaryForOrder } from "./omsReadModelPricing.js";
+import { mapOmsPaymentStatus } from "../fulfillmentEligibility.js";
+export { buildOmsDeliveryContactProjection, deliveryContactAddress } from "./omsReadModelRowCore.js";
+// Who the row is about. One pair rather than two loose fields, so the row core
+// forwards it untouched and neither builder can supply half of it.
+export function findCustomer(order, customers) {
+    return mapCustomer(customers.find((customer) => customer.id === order.client_id) ?? null);
+}
+export function mapCustomer(row) {
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        email: row.email,
+        firstName: row.first_name,
+        lastName: row.last_name,
+        phone: row.phone,
+        lifecycleStage: row.lifecycle_stage,
+    };
+}
+export function mapAddress(row) {
+    if (!row)
+        return null;
+    return {
+        id: row.id,
+        label: row.label ?? null,
+        line1: row.line1 ?? null,
+        line2: row.line2 ?? null,
+        city: row.city ?? null,
+        postalCode: row.postal_code ?? null,
+        country: row.country ?? null,
+        recipientName: row.recipient_name ?? null,
+        contactPhone: row.contact_phone ?? null,
+        companyName: row.company_name ?? null,
+        taxId: row.tax_id ?? null,
+        deliveryNotes: row.delivery_notes ?? null,
+        courierInstructions: row.courier_instructions ?? null,
+    };
+}
+export function evaluateOperationalState(input) {
+    // The rungs themselves live in omsOperationalLadder.ts, next to the live SQL
+    // arms they mirror, so the parity test can compare the two ladders directly.
+    // This function only adapts the row shapes onto the ladder's flat input.
+    return resolveOmsOperationalState({
+        orderStatus: input.order.status,
+        activeHoldCount: input.activeHoldCount,
+        paymentStatus: input.paymentStatus,
+        hasShippingAddress: Boolean(input.order.shipping_address_id),
+        inventoryStatus: input.inventoryStatus,
+        fulfillmentStatus: input.fulfillmentStatus,
+        // An absent eligibility evaluation never blocked: the old cascade consulted
+        // it only when it was supplied. `true` reproduces that exactly.
+        fulfillmentAllowed: input.fulfillmentEligibility ? input.fulfillmentEligibility.allowed : true,
+        accountingStatus: input.accountingStatus,
+    });
+}
+export function actionEligibility(input) {
+    const flags = {
+        holdMutationsEnabled: true,
+        supportMutationsEnabled: true,
+        fulfillmentMutationsEnabled: true,
+        refundMutationsEnabled: true,
+        orderCancellationEnabled: true,
+        ...input.flags,
+    };
+    const canCreateFulfillment = input.fulfillmentEligibility.allowed && !input.hasFulfillmentOrder;
+    const canRecordLabel = input.fulfillmentStatus === "created" || input.fulfillmentStatus === "packed" || input.fulfillmentStatus === "label_pending";
+    const base = {
+        addNote: { allowed: true, reason: null },
+        createHold: input.activeHoldCount > 0 ? { allowed: false, reason: "order_already_on_hold" } : { allowed: true, reason: null },
+        releaseHold: input.activeHoldCount > 0 ? { allowed: true, reason: null } : { allowed: false, reason: "no_active_hold" },
+        createFulfillment: canCreateFulfillment ? { allowed: true, reason: null } : { allowed: false, reason: input.fulfillmentEligibility.reason ?? "fulfillment_order_exists" },
+        updateShippingAddress: input.deliveryContact
+            ? !input.deliveryContact.effective
+                ? { allowed: false, reason: "missing_shipping_address" }
+                : input.deliveryContact.correctionAllowed
+                    ? { allowed: true, reason: null }
+                    : { allowed: false, reason: deliveryContactRefusalReason(input.deliveryContact) }
+            : !input.hasShippingAddress
+                ? { allowed: false, reason: "missing_shipping_address" }
+                : canUpdateShippingAddress(input.fulfillmentStatus)
+                    ? { allowed: true, reason: null }
+                    : { allowed: false, reason: "address_locked_after_label" },
+        recordLabel: canRecordLabel ? { allowed: true, reason: null } : { allowed: false, reason: "fulfillment_not_ready_for_label" },
+        handOff: input.fulfillmentStatus === "label_created" ? { allowed: true, reason: null } : { allowed: false, reason: "label_required_before_handoff" },
+        recordTrackingEvent: canRecordTrackingEvent(input.fulfillmentStatus) ? { allowed: true, reason: null } : { allowed: false, reason: "tracking_not_ready" },
+        cancelFulfillment: input.fulfillmentStatus
+            ? canCancelFulfillment(input.fulfillmentStatus, {
+                activeHoldCount: input.activeHoldCount,
+                orderMode: input.orderMode,
+                orderStatus: input.orderStatus,
+                providerCancellationConfirmed: input.providerCancellationConfirmed ?? false,
+            })
+                ? { allowed: true, reason: null }
+                : { allowed: false, reason: "fulfillment_not_cancellable" }
+            : { allowed: false, reason: "no_fulfillment_order" },
+        cancelOrder: input.orderStatus === "pending_payment"
+            ? { allowed: true, reason: null }
+            : { allowed: false, reason: "order_not_pending_payment" },
+        markRefunded: input.orderStatus === "paid"
+            ? { allowed: true, reason: null }
+            : input.orderStatus === "refunded"
+                ? { allowed: false, reason: "already_refunded" }
+                : { allowed: false, reason: "order_not_paid" },
+    };
+    return {
+        addNote: flagGate(base.addNote, flags.supportMutationsEnabled, "oms_support_mutations_disabled"),
+        createHold: flagGate(base.createHold, flags.holdMutationsEnabled, "oms_hold_mutations_disabled"),
+        releaseHold: flagGate(base.releaseHold, flags.holdMutationsEnabled, "oms_hold_mutations_disabled"),
+        createFulfillment: flagGate(base.createFulfillment, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+        updateShippingAddress: flagGate(base.updateShippingAddress, flags.supportMutationsEnabled, "oms_support_mutations_disabled"),
+        recordLabel: flagGate(base.recordLabel, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+        handOff: flagGate(base.handOff, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+        recordTrackingEvent: flagGate(base.recordTrackingEvent, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+        cancelFulfillment: flagGate(base.cancelFulfillment, flags.fulfillmentMutationsEnabled, "commerce_fulfillment_mutations_disabled"),
+        cancelOrder: flagGate(base.cancelOrder, flags.orderCancellationEnabled, "oms_order_cancellation_disabled"),
+        markRefunded: flagGate(base.markRefunded, flags.refundMutationsEnabled, "oms_refund_mutations_disabled"),
+    };
+}
+function deliveryContactRefusalReason(projection) {
+    return ["submitting", "created", "uncertain", "failed", "cancel_requested", "cancelled", "unknown"]
+        .includes(projection.providerSubmissionState)
+        ? "delivery_contact_submission_started"
+        : "address_locked_after_label";
+}
+export function inventorySummary(reservations, orderItems) {
+    const reservation = reservations[0] ?? null;
+    if (!reservation)
+        return emptyInventory();
+    const base = {
+        reservationId: reservation.id,
+        reservationStatus: reservation.status,
+        expiresAt: reservation.expires_at,
+        locationId: reservation.location_id,
+        locationCode: reservation.inventory_locations?.code ?? null,
+    };
+    if (orderItems.length > 0 && !hasCoverageReservation(reservations) && reservation.status !== "consumed") {
+        return { status: reservation.status === "reserved" ? "reserved" : reservation.status, ...base };
+    }
+    if (orderItems.length > 0 && !allOrderItemsCovered(orderItems, reservations))
+        return { status: "missing", ...base };
+    return { status: reservation.status === "reserved" ? "reserved" : reservation.status, ...base };
+}
+export function baseOrder(input) {
+    const pricingSummary = pricingSummaryForOrder(input.order, input.orderItems, input.orderMoney);
+    return {
+        orderId: input.order.id,
+        orderNumber: input.order.order_number,
+        clientId: input.order.client_id,
+        ...input.identity,
+        status: input.order.status,
+        mode: input.order.mode,
+        // undefined, not null: "no source axis read" is not "storefront order".
+        sourceKind: input.order.source_kind ?? undefined,
+        sourceChannelSlug: input.order.sales_channels?.slug ?? undefined,
+        sourceOrderRef: input.order.source_order_ref ?? undefined,
+        paymentMethodLabel: input.paymentMethod.label,
+        paymentProvider: input.paymentMethod.provider,
+        paymentStatus: input.paymentStatus,
+        fulfillmentStatus: input.fulfillmentStatus,
+        customerFulfillmentStep: input.customerFulfillmentStep,
+        inventoryStatus: input.inventoryStatus,
+        accountingStatus: input.accountingStatus,
+        providerOpsStatus: input.providerOpsStatus,
+        providerOpsSla: input.providerOpsSla,
+        providerOrderId: input.providerOrderId,
+        attentionReason: input.attentionReason,
+        nextAction: input.nextAction,
+        activeHoldCount: input.activeHoldCount,
+        total: pricingSummary.finalTotal,
+        pricingSummary,
+        createdAt: input.order.created_at,
+        updatedAt: input.order.updated_at,
+    };
+}
+export function paymentStatusForOrder(orderId, paymentIntents) {
+    const intent = paymentIntents.find((candidate) => candidate.id && candidate.order_id === orderId);
+    return mapOmsPaymentStatus(intent?.status ?? null);
+}
+function canUpdateShippingAddress(status) {
+    return !status || status === "created" || status === "packed" || status === "label_pending";
+}
+function canRecordTrackingEvent(status) {
+    return status === "handed_over" || status === "in_transit";
+}
+function flagGate(eligibility, enabled, reason) {
+    return enabled ? eligibility : { allowed: false, reason };
+}
+function allOrderItemsCovered(orderItems, reservations) {
+    const reservedQtyByItem = new Map();
+    for (const reservation of reservations) {
+        if ((reservation.status !== "reserved" && reservation.status !== "consumed") || !reservation.order_item_id)
+            continue;
+        reservedQtyByItem.set(reservation.order_item_id, (reservedQtyByItem.get(reservation.order_item_id) ?? 0) + reservation.quantity);
+    }
+    return orderItems.every((item) => (reservedQtyByItem.get(item.id) ?? 0) >= item.quantity);
+}
+function hasCoverageReservation(reservations) {
+    return reservations.some((reservation) => reservation.status === "reserved" || reservation.status === "consumed");
+}
+function emptyInventory() {
+    return {
+        status: "missing",
+        reservationId: null,
+        reservationStatus: null,
+        expiresAt: null,
+        locationId: null,
+        locationCode: null,
+    };
+}

package/dist/commerce/model/omsReadModelList.d.ts

@@ -0,0 +1,33 @@
+import type { SubscriptionCycleStatus } from "@openlup/core/subscription";
+import { type AdminCommerceOrdersListResponse, type AdminOmsOrderSearchMatch, type AdminOmsOrderListItem as OmsOrderListItem } from "../oms/omsContracts.js";
+import type { OmsFulfillmentOperationRow, OmsFulfillmentOrderRow, OmsProviderDispatchRefRow, OmsProviderStatusEvidenceRow, OmsReleasedProviderExceptionHoldRow, OmsShipmentExternalRefRow } from "./omsFulfillmentSummary.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import type { OmsAccountingInvoiceRow, OmsAccountingOutboxRow, OmsCustomerRow, OmsInventoryReservationRow, OmsOrderItemRow, OmsOrderRow, OmsPaymentAttemptRow, OmsPaymentIntentRow } from "./omsReadModelRows.js";
+export declare 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;