@openlup/platform 0.26.0 → 0.27.0

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

@@ -0,0 +1,69 @@
+import { z } from "zod";
+import type { OmsFulfillmentDebug } from "../contracts/omsTypes.js";
+export type { OmsFulfillmentDebug } from "../contracts/omsTypes.js";
+export declare const omsFulfillmentDebugStepSchema: z.ZodObject<{
+    key: z.ZodEnum<{
+        stock: "stock";
+        payment: "payment";
+        provider: "provider";
+        fulfillment: "fulfillment";
+        dispatch: "dispatch";
+        provider_stock: "provider_stock";
+        tracking: "tracking";
+        communication: "communication";
+    }>;
+    status: z.ZodEnum<{
+        ok: "ok";
+        missing: "missing";
+        pending: "pending";
+        blocked: "blocked";
+        warning: "warning";
+    }>;
+    label: z.ZodString;
+    value: z.ZodNullable<z.ZodString>;
+    evidenceAt: z.ZodNullable<z.ZodString>;
+    details: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const omsFulfillmentDebugSchema: z.ZodObject<{
+    summary: z.ZodString;
+    severity: z.ZodEnum<{
+        ok: "ok";
+        action_required: "action_required";
+        watch: "watch";
+    }>;
+    nextAction: z.ZodEnum<{
+        review_payment: "review_payment";
+        create_fulfillment: "create_fulfillment";
+        wait: "wait";
+        retry_dispatch: "retry_dispatch";
+        reconcile: "reconcile";
+        review_stock: "review_stock";
+        review_provider: "review_provider";
+        contact_support: "contact_support";
+    }>;
+    blockers: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    steps: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        key: z.ZodEnum<{
+            stock: "stock";
+            payment: "payment";
+            provider: "provider";
+            fulfillment: "fulfillment";
+            dispatch: "dispatch";
+            provider_stock: "provider_stock";
+            tracking: "tracking";
+            communication: "communication";
+        }>;
+        status: z.ZodEnum<{
+            ok: "ok";
+            missing: "missing";
+            pending: "pending";
+            blocked: "blocked";
+            warning: "warning";
+        }>;
+        label: z.ZodString;
+        value: z.ZodNullable<z.ZodString>;
+        evidenceAt: z.ZodNullable<z.ZodString>;
+        details: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+export declare const defaultOmsFulfillmentDebug: OmsFulfillmentDebug;

package/dist/commerce/oms/omsFulfillmentDebugSchemas.js

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { datetimeSchema, nullableTextSchema } from "./omsContractBase.js";
+export const omsFulfillmentDebugStepSchema = z.object({
+    key: z.enum(["payment", "stock", "provider_stock", "fulfillment", "dispatch", "provider", "tracking", "communication"]),
+    status: z.enum(["ok", "pending", "missing", "warning", "blocked"]),
+    label: z.string().min(1),
+    value: nullableTextSchema,
+    evidenceAt: datetimeSchema.nullable(),
+    details: z.array(z.string()).default([]),
+}).strict();
+export const omsFulfillmentDebugSchema = z.object({
+    summary: z.string().min(1),
+    severity: z.enum(["ok", "watch", "action_required"]),
+    nextAction: z.enum([
+        "wait",
+        "create_fulfillment",
+        "retry_dispatch",
+        "reconcile",
+        "review_payment",
+        "review_stock",
+        "review_provider",
+        "contact_support",
+    ]),
+    blockers: z.array(z.string()).default([]),
+    steps: z.array(omsFulfillmentDebugStepSchema).default([]),
+}).strict();
+export const defaultOmsFulfillmentDebug = {
+    summary: "No fulfillment data.",
+    severity: "watch",
+    nextAction: "wait",
+    blockers: [],
+    steps: [],
+};

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

@@ -0,0 +1,67 @@
+import { z } from "zod";
+export declare const omsFulfillmentHealthSchema: z.ZodObject<{
+    healthStatus: z.ZodEnum<{
+        ok: "ok";
+        needs_attention: "needs_attention";
+        blocked_uncertain: "blocked_uncertain";
+        local_ahead: "local_ahead";
+        provider_ahead: "provider_ahead";
+        missing_local_commitment: "missing_local_commitment";
+    }>;
+    attentionReasons: z.ZodArray<z.ZodEnum<{
+        paid_order_missing_fulfillment: "paid_order_missing_fulfillment";
+        paid_order_missing_dispatch_ref: "paid_order_missing_dispatch_ref";
+        dispatch_submission_stale: "dispatch_submission_stale";
+        dispatch_outcome_uncertain: "dispatch_outcome_uncertain";
+        dispatch_failed: "dispatch_failed";
+        dispatch_created_without_provider_order_id: "dispatch_created_without_provider_order_id";
+        dispatch_terminal_without_progress: "dispatch_terminal_without_progress";
+        dispatch_status_unknown: "dispatch_status_unknown";
+        provider_exception_after_delivery: "provider_exception_after_delivery";
+        provider_exception_after_handover: "provider_exception_after_handover";
+        provider_exception_before_handover: "provider_exception_before_handover";
+        local_status_ahead_of_provider: "local_status_ahead_of_provider";
+        provider_accepted_local_label_ack_missing: "provider_accepted_local_label_ack_missing";
+        order_paid_outbox_discarded: "order_paid_outbox_discarded";
+        order_paid_outbox_processed_without_fulfillment: "order_paid_outbox_processed_without_fulfillment";
+        order_paid_outbox_missing: "order_paid_outbox_missing";
+    }>>;
+    oldestAgeSeconds: z.ZodNullable<z.ZodNumber>;
+    dispatchRefId: z.ZodOptional<z.ZodNullable<z.ZodGUID>>;
+    dispatchStatus: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    opaqueIds: z.ZodObject<{
+        orderId: z.ZodGUID;
+        fulfillmentOrderId: z.ZodNullable<z.ZodGUID>;
+        outboxEventId: z.ZodNullable<z.ZodGUID>;
+        dispatchRefFulfillmentOrderId: z.ZodNullable<z.ZodGUID>;
+        latestEvidenceFulfillmentOrderId: z.ZodNullable<z.ZodGUID>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const omsFulfillmentHealthDigestSchema: z.ZodObject<{
+    healthStatus: z.ZodEnum<{
+        ok: "ok";
+        needs_attention: "needs_attention";
+        blocked_uncertain: "blocked_uncertain";
+        local_ahead: "local_ahead";
+        provider_ahead: "provider_ahead";
+        missing_local_commitment: "missing_local_commitment";
+    }>;
+    attentionReasons: z.ZodArray<z.ZodEnum<{
+        paid_order_missing_fulfillment: "paid_order_missing_fulfillment";
+        paid_order_missing_dispatch_ref: "paid_order_missing_dispatch_ref";
+        dispatch_submission_stale: "dispatch_submission_stale";
+        dispatch_outcome_uncertain: "dispatch_outcome_uncertain";
+        dispatch_failed: "dispatch_failed";
+        dispatch_created_without_provider_order_id: "dispatch_created_without_provider_order_id";
+        dispatch_terminal_without_progress: "dispatch_terminal_without_progress";
+        dispatch_status_unknown: "dispatch_status_unknown";
+        provider_exception_after_delivery: "provider_exception_after_delivery";
+        provider_exception_after_handover: "provider_exception_after_handover";
+        provider_exception_before_handover: "provider_exception_before_handover";
+        local_status_ahead_of_provider: "local_status_ahead_of_provider";
+        provider_accepted_local_label_ack_missing: "provider_accepted_local_label_ack_missing";
+        order_paid_outbox_discarded: "order_paid_outbox_discarded";
+        order_paid_outbox_processed_without_fulfillment: "order_paid_outbox_processed_without_fulfillment";
+        order_paid_outbox_missing: "order_paid_outbox_missing";
+    }>>;
+}, z.core.$strict>;

package/dist/commerce/oms/omsFulfillmentHealthSchemas.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { uuidSchema } from "./omsContractBase.js";
+export const omsFulfillmentHealthSchema = z.object({
+    healthStatus: z.enum(["ok", "needs_attention", "blocked_uncertain", "local_ahead", "provider_ahead", "missing_local_commitment"]),
+    attentionReasons: z.array(z.enum([
+        "paid_order_missing_fulfillment",
+        "paid_order_missing_dispatch_ref",
+        "dispatch_submission_stale",
+        "dispatch_outcome_uncertain",
+        "dispatch_failed",
+        "dispatch_created_without_provider_order_id",
+        "dispatch_terminal_without_progress",
+        "dispatch_status_unknown",
+        "provider_exception_after_delivery",
+        "provider_exception_after_handover",
+        "provider_exception_before_handover",
+        "local_status_ahead_of_provider",
+        "provider_accepted_local_label_ack_missing",
+        "order_paid_outbox_discarded",
+        "order_paid_outbox_processed_without_fulfillment",
+        "order_paid_outbox_missing",
+    ])),
+    oldestAgeSeconds: z.number().int().nonnegative().nullable(),
+    dispatchRefId: uuidSchema.nullable().optional(),
+    dispatchStatus: z.string().nullable().optional(),
+    opaqueIds: z.object({
+        orderId: uuidSchema,
+        fulfillmentOrderId: uuidSchema.nullable(),
+        outboxEventId: uuidSchema.nullable(),
+        dispatchRefFulfillmentOrderId: uuidSchema.nullable(),
+        latestEvidenceFulfillmentOrderId: uuidSchema.nullable(),
+    }).strict(),
+}).strict();
+// The list-row projection of the health snapshot above: the two fields an
+// operator can act on, picked from the same schema so the vocabulary cannot
+// fork. The list path builds it from the provider evidence it already fetches
+// per page and never reads `outbox_events`, so a digest can never carry the
+// three `order_paid_outbox_*` reasons - the builder is told the outbox is
+// unread and answers `paid_order_missing_fulfillment` instead of naming an
+// outbox row it did not look at. The enum stays whole rather than being
+// narrowed here: the omission is a property of the input, not of the contract.
+export const omsFulfillmentHealthDigestSchema = omsFulfillmentHealthSchema
+    .pick({ healthStatus: true, attentionReasons: true })
+    .strict();

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

@@ -0,0 +1,84 @@
+import type { OmsReplacementRefusal } from "../contracts/omsTypes.js";
+import { type OmsCurrencyPolicy } from "../model/omsCurrency.js";
+export type { CommerceOmsHoldPort, CommerceOmsReadPort, OmsReplacementRefusal } from "../contracts/omsTypes.js";
+/**
+ * Every refusal `commerce_oms_request_replacement_shipment` can reach an operator with,
+ * as one closed vocabulary shared by the adapter that classifies it and the admin surface
+ * that renders a sentence for it. Two lists would drift, and the failure mode of drift is
+ * the operator reading advice about a hold when the warehouse is simply out of stock.
+ *
+ * The first group is the command's own `commerce_oms_replacement_*` names. The second is
+ * the reservation vocabulary raised THROUGH it: the command mints a fresh generation via
+ * `inventory_reserve_order`, and on a stock authority outside this system that call is the
+ * most likely legitimate refusal there is. Those errors never carried the command's prefix,
+ * so before this list they matched nothing, degraded to an upstream failure, and the
+ * operator was told to check holds that were not there.
+ *
+ * It stays an allowlist, not a translation table: a reason absent from it degrades to
+ * `unspecified_refusal`, so no database text can travel to a response, a log or a screen.
+ *
+ * ⛔ The exported names deliberately omit the `CommerceOms` prefix every other symbol in
+ * this file carries. `src/lib/commerceOmsBoundary.test.ts` forbids that token in production
+ * UI files outside a small allowlist, and the admin surface imports these three symbols.
+ * Renaming them is the honest way to keep that boundary guard intact; widening its allowlist
+ * to admit one more file would weaken the control instead of respecting it.
+ */
+export declare const OMS_REPLACEMENT_COMMAND_REFUSALS: readonly ["invalid_input", "idempotency_conflict", "order_not_found", "order_not_replaceable", "missing_client", "missing_shipping_address", "shipping_address_not_found", "payment_not_succeeded", "subscription_cycle_not_paid", "no_parcel_to_replace", "undispatched_replacement_exists", "missing_order_items", "missing_catalog_sku", "missing_inventory_reservation", "blocked_by_payment_not_succeeded_hold", "blocked_by_inventory_review_hold", "blocked_by_risk_review_hold", "blocked_by_address_review_hold", "blocked_by_manual_support_hold"];
+export declare const OMS_REPLACEMENT_RESERVATION_REFUSALS: readonly ["inventory_external_provider_insufficient_available_stock", "inventory_external_provider_stock_stale", "inventory_external_provider_stock_missing", "inventory_external_provider_sku_not_found", "inventory_external_provider_location_missing", "inventory_reservation_insufficient_available_stock", "inventory_reservation_allocation_incomplete", "inventory_reservation_payment_status_not_reservable", "inventory_reservation_invalid_quantity"];
+export declare const UNSPECIFIED_REPLACEMENT_REFUSAL = "unspecified_refusal";
+export declare const OMS_REPLACEMENT_REFUSALS: readonly ["invalid_input", "idempotency_conflict", "order_not_found", "order_not_replaceable", "missing_client", "missing_shipping_address", "shipping_address_not_found", "payment_not_succeeded", "subscription_cycle_not_paid", "no_parcel_to_replace", "undispatched_replacement_exists", "missing_order_items", "missing_catalog_sku", "missing_inventory_reservation", "blocked_by_payment_not_succeeded_hold", "blocked_by_inventory_review_hold", "blocked_by_risk_review_hold", "blocked_by_address_review_hold", "blocked_by_manual_support_hold", "inventory_external_provider_insufficient_available_stock", "inventory_external_provider_stock_stale", "inventory_external_provider_stock_missing", "inventory_external_provider_sku_not_found", "inventory_external_provider_location_missing", "inventory_reservation_insufficient_available_stock", "inventory_reservation_allocation_incomplete", "inventory_reservation_payment_status_not_reservable", "inventory_reservation_invalid_quantity", "unspecified_refusal"];
+/**
+ * Reads the refusal a replacement error carries, from any of the shapes a BFF error can
+ * legitimately arrive in. Returns null when the text names no refusal this vocabulary
+ * knows, which is the honest answer: the operator gets the generic sentence plus the raw
+ * detail to hand to the team, never a guess dressed as advice.
+ */
+export declare function readOmsReplacementRefusal(text: string): OmsReplacementRefusal | null;
+export declare class CommerceOmsInvalidResponseError extends Error {
+    constructor();
+}
+export declare class CommerceOmsPersistenceError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * An order row came back from the database in a currency this deployment does
+ * not accept. The channel ingest rail is deliberately multi-currency, so such a
+ * row can genuinely exist; what it cannot do is reach the read model, whose
+ * money nodes are pinned to the platform's accepted set.
+ *
+ * A subclass rather than a new error family, so it inherits the persistence
+ * error's HTTP mapping untouched: this is still an upstream read that could not
+ * be served, and the operator-facing status must not move. The gain is entirely
+ * diagnostic - the failure now names the orders and the codes instead of
+ * surfacing as an anonymous validation error fifteen frames later.
+ */
+export declare class CommerceOmsUnsupportedCurrencyError extends CommerceOmsPersistenceError {
+    readonly orderIds: readonly string[];
+    readonly currencies: readonly string[];
+    constructor(offenders: ReadonlyArray<{
+        orderId: string;
+        currency: string;
+    }>);
+}
+/**
+ * Guards the one field of an order row that can break the OMS read.
+ *
+ * This is deliberately not a schema for the whole row. Of that row's ~22
+ * columns exactly one - `currency` - is both able to fail the read model and
+ * something the platform holds an opinion about; the rest would cost a new
+ * contract surface parsed once per row per page, and would only be coherent if
+ * the other cast row kinds on this path were validated too.
+ *
+ * It also deliberately refuses rather than filtering. Dropping the offending
+ * row would keep the page rendering while hiding a real customer order from the
+ * operator handling it - a worse failure than a named refusal.
+ */
+export declare function assertOmsOrderRowCurrency(rows: ReadonlyArray<{
+    id: string;
+    currency: string;
+}>, currency?: OmsCurrencyPolicy): void;
+export declare class CommerceOmsConflictError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}

package/dist/commerce/oms/omsPorts.js

@@ -0,0 +1,148 @@
+import { neutralOmsCurrencyPolicy } from "../model/omsCurrency.js";
+/**
+ * Every refusal `commerce_oms_request_replacement_shipment` can reach an operator with,
+ * as one closed vocabulary shared by the adapter that classifies it and the admin surface
+ * that renders a sentence for it. Two lists would drift, and the failure mode of drift is
+ * the operator reading advice about a hold when the warehouse is simply out of stock.
+ *
+ * The first group is the command's own `commerce_oms_replacement_*` names. The second is
+ * the reservation vocabulary raised THROUGH it: the command mints a fresh generation via
+ * `inventory_reserve_order`, and on a stock authority outside this system that call is the
+ * most likely legitimate refusal there is. Those errors never carried the command's prefix,
+ * so before this list they matched nothing, degraded to an upstream failure, and the
+ * operator was told to check holds that were not there.
+ *
+ * It stays an allowlist, not a translation table: a reason absent from it degrades to
+ * `unspecified_refusal`, so no database text can travel to a response, a log or a screen.
+ *
+ * ⛔ The exported names deliberately omit the `CommerceOms` prefix every other symbol in
+ * this file carries. `src/lib/commerceOmsBoundary.test.ts` forbids that token in production
+ * UI files outside a small allowlist, and the admin surface imports these three symbols.
+ * Renaming them is the honest way to keep that boundary guard intact; widening its allowlist
+ * to admit one more file would weaken the control instead of respecting it.
+ */
+export const OMS_REPLACEMENT_COMMAND_REFUSALS = [
+    "invalid_input",
+    "idempotency_conflict",
+    "order_not_found",
+    "order_not_replaceable",
+    "missing_client",
+    "missing_shipping_address",
+    "shipping_address_not_found",
+    "payment_not_succeeded",
+    "subscription_cycle_not_paid",
+    "no_parcel_to_replace",
+    "undispatched_replacement_exists",
+    "missing_order_items",
+    "missing_catalog_sku",
+    "missing_inventory_reservation",
+    "blocked_by_payment_not_succeeded_hold",
+    "blocked_by_inventory_review_hold",
+    "blocked_by_risk_review_hold",
+    "blocked_by_address_review_hold",
+    "blocked_by_manual_support_hold",
+];
+export const OMS_REPLACEMENT_RESERVATION_REFUSALS = [
+    "inventory_external_provider_insufficient_available_stock",
+    "inventory_external_provider_stock_stale",
+    "inventory_external_provider_stock_missing",
+    "inventory_external_provider_sku_not_found",
+    "inventory_external_provider_location_missing",
+    "inventory_reservation_insufficient_available_stock",
+    "inventory_reservation_allocation_incomplete",
+    "inventory_reservation_payment_status_not_reservable",
+    "inventory_reservation_invalid_quantity",
+];
+export const UNSPECIFIED_REPLACEMENT_REFUSAL = "unspecified_refusal";
+export const OMS_REPLACEMENT_REFUSALS = [
+    ...OMS_REPLACEMENT_COMMAND_REFUSALS,
+    ...OMS_REPLACEMENT_RESERVATION_REFUSALS,
+    UNSPECIFIED_REPLACEMENT_REFUSAL,
+];
+/**
+ * Reads the refusal a replacement error carries, from any of the shapes a BFF error can
+ * legitimately arrive in. Returns null when the text names no refusal this vocabulary
+ * knows, which is the honest answer: the operator gets the generic sentence plus the raw
+ * detail to hand to the team, never a guess dressed as advice.
+ */
+export function readOmsReplacementRefusal(text) {
+    const named = /commerce_oms_replacement_([a-z0-9_]+)/.exec(text)?.[1];
+    if (named) {
+        return OMS_REPLACEMENT_COMMAND_REFUSALS.includes(named)
+            ? named
+            : UNSPECIFIED_REPLACEMENT_REFUSAL;
+    }
+    // Exact membership only. A transport or permission failure that merely quotes a table
+    // name such as `inventory_reservations` must stay an upstream failure, not become a
+    // refusal the operator is asked to act on.
+    return OMS_REPLACEMENT_RESERVATION_REFUSALS.find((reason) => text.includes(reason)) ?? null;
+}
+export class CommerceOmsInvalidResponseError extends Error {
+    constructor() {
+        super("Commerce OMS returned invalid response");
+        this.name = "CommerceOmsInvalidResponseError";
+    }
+}
+export class CommerceOmsPersistenceError extends Error {
+    details;
+    constructor(message = "Commerce OMS persistence failed", details = {}) {
+        super(message);
+        this.name = "CommerceOmsPersistenceError";
+        this.details = details;
+    }
+}
+/**
+ * An order row came back from the database in a currency this deployment does
+ * not accept. The channel ingest rail is deliberately multi-currency, so such a
+ * row can genuinely exist; what it cannot do is reach the read model, whose
+ * money nodes are pinned to the platform's accepted set.
+ *
+ * A subclass rather than a new error family, so it inherits the persistence
+ * error's HTTP mapping untouched: this is still an upstream read that could not
+ * be served, and the operator-facing status must not move. The gain is entirely
+ * diagnostic - the failure now names the orders and the codes instead of
+ * surfacing as an anonymous validation error fifteen frames later.
+ */
+export class CommerceOmsUnsupportedCurrencyError extends CommerceOmsPersistenceError {
+    orderIds;
+    currencies;
+    constructor(offenders) {
+        const orderIds = offenders.map((offender) => offender.orderId);
+        const currencies = [...new Set(offenders.map((offender) => offender.currency))];
+        const described = offenders
+            .map((offender) => `order ${offender.orderId} has currency ${offender.currency}`)
+            .join(", ");
+        super(`${described}, not accepted by this deployment`, { orderIds, currencies });
+        this.name = "CommerceOmsUnsupportedCurrencyError";
+        this.orderIds = orderIds;
+        this.currencies = currencies;
+    }
+}
+/**
+ * Guards the one field of an order row that can break the OMS read.
+ *
+ * This is deliberately not a schema for the whole row. Of that row's ~22
+ * columns exactly one - `currency` - is both able to fail the read model and
+ * something the platform holds an opinion about; the rest would cost a new
+ * contract surface parsed once per row per page, and would only be coherent if
+ * the other cast row kinds on this path were validated too.
+ *
+ * It also deliberately refuses rather than filtering. Dropping the offending
+ * row would keep the page rendering while hiding a real customer order from the
+ * operator handling it - a worse failure than a named refusal.
+ */
+export function assertOmsOrderRowCurrency(rows, currency = neutralOmsCurrencyPolicy) {
+    const offenders = rows
+        .filter((row) => !currency.accepts(row.currency))
+        .map((row) => ({ orderId: row.id, currency: row.currency }));
+    if (offenders.length)
+        throw new CommerceOmsUnsupportedCurrencyError(offenders);
+}
+export class CommerceOmsConflictError extends Error {
+    details;
+    constructor(message = "Commerce OMS conflict", details = {}) {
+        super(message);
+        this.name = "CommerceOmsConflictError";
+        this.details = details;
+    }
+}

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

@@ -0,0 +1,5 @@
+import { z } from "zod";
+export declare const commerceMoneySchema: z.ZodObject<{
+    amountMinor: z.ZodNumber;
+    currency: z.ZodString;
+}, z.core.$strict>;

package/dist/commerce/oms/omsPrimitives.js

@@ -0,0 +1,3 @@
+import { z } from "zod";
+// OMS read money permits signed adjustments and rejects unknown fields.
+export const commerceMoneySchema = z.object({ amountMinor: z.number().int(), currency: z.string().regex(/^[A-Z]{3}$/) }).strict();

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

@@ -0,0 +1,15 @@
+import { z } from "zod";
+export declare const omsProviderEvidenceSchema: 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>;

package/dist/commerce/oms/omsProviderEvidenceSchemas.js

@@ -0,0 +1,12 @@
+import { z } from "zod";
+import { datetimeSchema, nullableTextSchema } from "./omsContractBase.js";
+export const omsProviderEvidenceSchema = z.object({
+    evidenceType: z.enum(["dispatch_ref", "provider_attempt", "status_evidence"]),
+    status: nullableTextSchema,
+    providerStatus: nullableTextSchema,
+    providerOrderId: nullableTextSchema,
+    evidenceKind: nullableTextSchema,
+    occurredAt: datetimeSchema.nullable(),
+    updatedAt: datetimeSchema.nullable(),
+    summary: nullableTextSchema,
+}).strict();

package/dist/commerce/orderDraftErrors.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The quote was valid when read, but the atomic order write could no longer
+ * claim its promotion. Callers must re-quote and surface `price_changed`.
+ */
+export declare class CommerceOrderDraftPriceChangedError extends Error {
+    readonly details: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+export type CommerceOrderDraftUnsupportedMoneyReason = "line_promotion_unsupported" | "net_shipping_unsupported" | "zero_payable_unsupported";
+export declare class CommerceOrderDraftUnsupportedMoneyError extends Error {
+    readonly reason: CommerceOrderDraftUnsupportedMoneyReason;
+    constructor(reason: CommerceOrderDraftUnsupportedMoneyReason);
+}

package/dist/commerce/orderDraftErrors.js

@@ -0,0 +1,20 @@
+/**
+ * The quote was valid when read, but the atomic order write could no longer
+ * claim its promotion. Callers must re-quote and surface `price_changed`.
+ */
+export class CommerceOrderDraftPriceChangedError extends Error {
+    details;
+    constructor(message = "Commerce order draft promotion changed", details = {}) {
+        super(message);
+        this.name = "CommerceOrderDraftPriceChangedError";
+        this.details = details;
+    }
+}
+export class CommerceOrderDraftUnsupportedMoneyError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Commerce order draft money shape is unsupported: ${reason}`);
+        this.reason = reason;
+        this.name = "CommerceOrderDraftUnsupportedMoneyError";
+    }
+}

package/dist/commerce/orderEmailEligibility.d.ts

@@ -0,0 +1,54 @@
+import type { OrderPaymentLifecycleState } from "./outboxOrderDraftEmailPorts.js";
+/**
+ * Skip reason meaning "the payer is inside a live payment session right now".
+ * Exported because it is the one skip reason a caller must treat as TRANSIENT;
+ * every other reason in this module is a settled fact about the order.
+ */
+export declare const PAYMENT_SESSION_ACTIVE = "payment_session_active";
+export declare function shouldSkipOrderDraftConfirmation(state: OrderPaymentLifecycleState | null): string | null;
+/**
+ * Eligibility for the checkout-recovery NUDGE only.
+ *
+ * `payment_session_active` below is a politeness rule: do not remind someone to
+ * pay while they are paying. It is correct here and wrong for a decline notice
+ * — see {@link shouldSkipPaymentFailedNotice}. A caller acting on this reason
+ * must defer rather than drop, because the nudge's emit key is once-per-order.
+ */
+export declare function shouldSkipCheckoutRecovery(state: OrderPaymentLifecycleState | null): string | null;
+/**
+ * Eligibility for an OPERATOR-ISSUED recovery link.
+ *
+ * Deliberately not {@link shouldSkipCheckoutRecovery}. That gate is written for
+ * the cron nudge, and its first rule — leave `pending_payment` and we go quiet —
+ * is exactly wrong here. A human looked at the order and decided to send this
+ * link, and the orders they send it for are largely the ones that have ALREADY
+ * left `pending_payment`: `expired` is the ordinary case, and the redeem rail
+ * recreates such an order from its frozen quote when the customer opens the link.
+ * Reusing the cron gate would skip those as `order_not_pending_payment`, the
+ * operator would have promised an email that never arrives, and nothing anywhere
+ * would report a failure. The mint side has already run the full recovery
+ * eligibility for this order, so what is left here is only what can have changed
+ * between the mint and the send.
+ *
+ * What still suppresses: the order is gone, or the money is in. Both make the
+ * email actively wrong rather than merely late.
+ *
+ * `payment_session_active` behaves exactly as it does for the nudge, and for the
+ * same reason: do not tell someone to finish paying while they are paying. The
+ * caller must DEFER on it rather than drop, because a dropped operator link is
+ * the silent no-send this whole path is written to prevent.
+ */
+export declare function shouldSkipOperatorCheckoutRecovery(state: OrderPaymentLifecycleState | null): string | null;
+/**
+ * Eligibility for a recoverable payment-decline notice.
+ *
+ * Unlike a checkout reminder, a decline notice must not be suppressed by a live
+ * retry. Its producer key is once per order, so a later failed attempt cannot
+ * replace a notice that was consumed without sending.
+ *
+ * Suppress only when the order is unavailable, already paid, or no longer
+ * pending payment. The producer's claim delay lets successful retries settle
+ * before this lifecycle read; scheduling remains the producer/runtime's duty.
+ */
+export declare function shouldSkipPaymentFailedNotice(state: OrderPaymentLifecycleState | null): string | null;
+export declare function shouldSkipCheckoutExpired(state: OrderPaymentLifecycleState | null): string | null;