@openlup/platform 0.25.0 → 0.27.0

package/dist/commerce/errors.js

@@ -0,0 +1,36 @@
+export class CommerceNotEnabledError extends Error {
+    constructor(feature) {
+        super(`Commerce ${feature} is not enabled yet`);
+        this.name = "CommerceNotEnabledError";
+    }
+}
+export class CommerceOrderDraftConflictError extends Error {
+    details;
+    constructor(message = "Commerce order draft idempotency conflict", details = {}) {
+        super(message);
+        this.name = "CommerceOrderDraftConflictError";
+        this.details = details;
+    }
+}
+export class CommerceOrderDraftInvalidResponseError extends Error {
+    constructor() {
+        super("Commerce order draft returned invalid response");
+        this.name = "CommerceOrderDraftInvalidResponseError";
+    }
+}
+export class CommerceOrderDraftPersistenceError extends Error {
+    details;
+    constructor(message = "Commerce order draft persistence failed", details = {}) {
+        super(message);
+        this.name = "CommerceOrderDraftPersistenceError";
+        this.details = details;
+    }
+}
+export class CommerceCheckoutResumePersistenceError extends Error {
+    details;
+    constructor(message = "Commerce checkout resume persistence failed", details = {}) {
+        super(message);
+        this.name = "CommerceCheckoutResumePersistenceError";
+        this.details = details;
+    }
+}

package/dist/commerce/fulfillmentEligibility.d.ts

@@ -0,0 +1,6 @@
+import type { CommerceFulfillmentEligibilityInput, OmsFulfillmentBlockReason } from "./contracts/state.js";
+export declare function evaluateCommerceFulfillmentEligibility(input: CommerceFulfillmentEligibilityInput): {
+    allowed: boolean;
+    reason: OmsFulfillmentBlockReason | null;
+};
+export declare function mapOmsPaymentStatus(status: string | null): string;

package/dist/commerce/fulfillmentEligibility.js

@@ -0,0 +1,31 @@
+export function evaluateCommerceFulfillmentEligibility(input) {
+    if (input.activeHoldCount > 0)
+        return { allowed: false, reason: "active_hold" };
+    if (!input.hasShippingAddress)
+        return { allowed: false, reason: "missing_shipping_address" };
+    if (input.riskReviewRequired)
+        return { allowed: false, reason: "risk_review" };
+    if (!["paid", "fulfillment_pending", "fulfilled"].includes(input.orderStatus)) {
+        return { allowed: false, reason: "order_not_paid" };
+    }
+    if (input.paymentStatus !== "succeeded") {
+        return { allowed: false, reason: "payment_not_succeeded" };
+    }
+    if (input.orderMode === "subscription_cycle" && input.subscriptionCycleStatus !== "paid") {
+        return { allowed: false, reason: "subscription_cycle_not_paid" };
+    }
+    if (input.inventoryReviewRequired ||
+        ["missing", "released", "expired", "review_required"].includes(input.inventoryStatus ?? "not_checked")) {
+        return { allowed: false, reason: "inventory_review" };
+    }
+    return { allowed: true, reason: null };
+}
+export function mapOmsPaymentStatus(status) {
+    if (!status)
+        return "not_started";
+    if (status === "pending")
+        return "processing";
+    if (status === "paid")
+        return "succeeded";
+    return status;
+}

package/dist/commerce/index.d.ts

@@ -0,0 +1,72 @@
+export type * from "./contracts/index.js";
+export { createOfferAvailabilitySchemas, offerAvailabilityRequestItems } from "./offerAvailabilitySchemas.js";
+export { hasSubscriptionRecoveryContext, resolveRecoveryDestination } from "./recoveryDestination.js";
+export * from "./errors.js";
+export * from "./orderDraftErrors.js";
+export { buildOrderDeliveryContact, uuidFromOrderRef, messageOf } from "./checkoutHelpers.js";
+export type { OrderDeliveryContactInput } from "./checkoutHelpers.js";
+export { CART_STATUSES, CHECKOUT_STATUSES, ORDER_DRAFT_STATUSES, ORDER_STATUSES, PAYMENT_STATUSES, OMS_FULFILLMENT_BLOCK_REASONS, OMS_INVENTORY_STATUSES } from "./contracts/state.js";
+export { evaluateCommerceFulfillmentEligibility, mapOmsPaymentStatus } from "./fulfillmentEligibility.js";
+export * from "./contractPrimitives.js";
+export { createCommerceSchemas } from "./schemas.js";
+export * from "./checkoutResumeSchemas.js";
+export * from "./customerDefaultsSnapshotSchemas.js";
+export * from "./configuratorIntentSchemas.js";
+export * from "./configuratorIntentPersistenceSchemas.js";
+export { CHECKOUT_CONTRACT_VERSION, ASYNC_CHECKOUT_STATUSES, checkoutKindSchema, checkoutActivationStatusSchema, asyncCheckoutStatusSchema, subscriptionActivationStatusSchema, invoiceBuyerSnapshotAddressCoreSchema, checkoutRequestCoreSchema, createCheckoutResponseSchemas, createCheckoutQuoteSchemas } from "./checkoutSchemas.js";
+export * from "./runtimeErrors.js";
+export type { CreateQuoteOptions, CommerceQuotePort } from "./ports.js";
+export * from "./orderMoney.js";
+export * from "./outboxEventSchemas.js";
+export * from "./model/omsAccountingVisibility.js";
+export * from "./model/omsBillingInvoiceBuyer.js";
+export * from "./model/omsOrderLineMoney.js";
+export * from "./model/omsPaymentMethodSummary.js";
+export * from "./model/omsReadModelCommunication.js";
+export * from "./model/omsReadModelHelpers.js";
+export * from "./model/omsReadModelList.js";
+export * from "./model/omsReadModelListSummary.js";
+export * from "./model/omsReadModelPricing.js";
+export * from "./model/omsReadModelRows.js";
+export * from "./model/omsFulfillmentDebug.js";
+export * from "./model/omsOperationalLadder.js";
+export * from "./model/omsFulfillmentSummary.js";
+export * from "./model/omsListTotals.js";
+export * from "./model/omsReadModelRowCore.js";
+export * from "./model/fulfillmentCancellationEligibility.js";
+export * from "./oms/omsContractBase.js";
+export * from "./oms/omsContractReadAuxSchemas.js";
+export * from "./oms/omsContractReadSchemas.js";
+export * from "./oms/omsContractRequests.js";
+export * from "./oms/omsContracts.js";
+export * from "./oms/omsFulfillmentContractSchemas.js";
+export * from "./oms/omsFulfillmentDebugSchemas.js";
+export * from "./oms/omsFulfillmentHealthSchemas.js";
+export * from "./oms/omsProviderEvidenceSchemas.js";
+export * from "./oms/omsControlPlane.js";
+export * from "./oms/omsPorts.js";
+export * from "./model/omsReadModelProjections.js";
+export * from "./model/omsCurrency.js";
+export declare const COMMERCE_CONTRACT_VERSION = "commerce.v0";
+export * from "./model/customerFulfillmentRecovery.js";
+export * from "./commerceReturnsPort.js";
+export * from "./orderReviewContracts.js";
+export type * from "./orderReviewPorts.js";
+export * from "./orderFeedbackContracts.js";
+export * from "./salesChannelEnvelope.js";
+export * from "./orderEmailEligibility.js";
+export * from "./orderEmailLines.js";
+export * from "./outboxDispatchContracts.js";
+export * from "./outboxOrderDraftEmailPorts.js";
+/** @consumer src/domains/commerce/checkoutCommandContracts.ts */
+export { createCheckoutCommandSchemas, CHECKOUT_COMMAND_V1, REFERENCE_CHECKOUT_V1 } from "./checkoutCommandSchemas.js";
+export type { CheckoutCommandPersistenceResult } from "./checkoutCommandSchemas.js";
+/** @consumer src/domains/commerce/paymentContinuationContracts.ts */
+export { checkoutContinuationJourneyIdSchema, CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS } from "./paymentContinuation.js";
+/** @consumer server/domains/commerce/checkoutOfferPolicyPort.ts */
+export { commerceOfferEvidenceSchema } from "./offerEvidenceSchemas.js";
+export type { CommerceOfferEvidence } from "./offerEvidenceSchemas.js";
+/** @consumer src/domains/commerce/offerAvailability.ts */
+export { DEFAULT_LOW_STOCK_THRESHOLD, deriveOfferAvailability, defaultOfferAvailability, availabilityBySku, statusForSellableNow, reasonCodeFor } from "./offerAvailability.js";
+/** @consumer src/domains/commerce/offerAvailability.ts */
+export type { DeriveOfferAvailabilityInput } from "./offerAvailability.js";

package/dist/commerce/index.js

@@ -0,0 +1,67 @@
+export { createOfferAvailabilitySchemas, offerAvailabilityRequestItems } from "./offerAvailabilitySchemas.js";
+export { hasSubscriptionRecoveryContext, resolveRecoveryDestination } from "./recoveryDestination.js";
+export * from "./errors.js";
+export * from "./orderDraftErrors.js";
+export { buildOrderDeliveryContact, uuidFromOrderRef, messageOf } from "./checkoutHelpers.js";
+export { CART_STATUSES, CHECKOUT_STATUSES, ORDER_DRAFT_STATUSES, ORDER_STATUSES, PAYMENT_STATUSES, OMS_FULFILLMENT_BLOCK_REASONS, OMS_INVENTORY_STATUSES } from "./contracts/state.js";
+export { evaluateCommerceFulfillmentEligibility, mapOmsPaymentStatus } from "./fulfillmentEligibility.js";
+export * from "./contractPrimitives.js";
+export { createCommerceSchemas } from "./schemas.js";
+export * from "./checkoutResumeSchemas.js";
+export * from "./customerDefaultsSnapshotSchemas.js";
+export * from "./configuratorIntentSchemas.js";
+export * from "./configuratorIntentPersistenceSchemas.js";
+export { CHECKOUT_CONTRACT_VERSION, ASYNC_CHECKOUT_STATUSES, checkoutKindSchema, checkoutActivationStatusSchema, asyncCheckoutStatusSchema, subscriptionActivationStatusSchema, invoiceBuyerSnapshotAddressCoreSchema, checkoutRequestCoreSchema, createCheckoutResponseSchemas, createCheckoutQuoteSchemas } from "./checkoutSchemas.js";
+export * from "./runtimeErrors.js";
+export * from "./orderMoney.js";
+export * from "./outboxEventSchemas.js";
+// M11 K3a OMS runtime surface.
+export * from "./model/omsAccountingVisibility.js";
+export * from "./model/omsBillingInvoiceBuyer.js";
+export * from "./model/omsOrderLineMoney.js";
+export * from "./model/omsPaymentMethodSummary.js";
+export * from "./model/omsReadModelCommunication.js";
+export * from "./model/omsReadModelHelpers.js";
+export * from "./model/omsReadModelList.js";
+export * from "./model/omsReadModelListSummary.js";
+export * from "./model/omsReadModelPricing.js";
+export * from "./model/omsReadModelRows.js";
+export * from "./model/omsFulfillmentDebug.js";
+export * from "./model/omsOperationalLadder.js";
+export * from "./model/omsFulfillmentSummary.js";
+export * from "./model/omsListTotals.js";
+export * from "./model/omsReadModelRowCore.js";
+export * from "./model/fulfillmentCancellationEligibility.js";
+export * from "./oms/omsContractBase.js";
+export * from "./oms/omsContractReadAuxSchemas.js";
+export * from "./oms/omsContractReadSchemas.js";
+export * from "./oms/omsContractRequests.js";
+export * from "./oms/omsContracts.js";
+export * from "./oms/omsFulfillmentContractSchemas.js";
+export * from "./oms/omsFulfillmentDebugSchemas.js";
+export * from "./oms/omsFulfillmentHealthSchemas.js";
+export * from "./oms/omsProviderEvidenceSchemas.js";
+export * from "./oms/omsControlPlane.js";
+export * from "./oms/omsPorts.js";
+export * from "./model/omsReadModelProjections.js";
+export * from "./model/omsCurrency.js";
+import { COMMERCE_CONTRACT_VERSION as contractVersion } from "../pricing/contracts/index.js";
+export const COMMERCE_CONTRACT_VERSION = contractVersion;
+export * from "./model/customerFulfillmentRecovery.js";
+export * from "./commerceReturnsPort.js";
+export * from "./orderReviewContracts.js";
+export * from "./orderFeedbackContracts.js";
+// Experimental browser-safe event contracts, projections and ports.
+export * from "./salesChannelEnvelope.js";
+export * from "./orderEmailEligibility.js";
+export * from "./orderEmailLines.js";
+export * from "./outboxDispatchContracts.js";
+export * from "./outboxOrderDraftEmailPorts.js";
+/** @consumer src/domains/commerce/checkoutCommandContracts.ts */
+export { createCheckoutCommandSchemas, CHECKOUT_COMMAND_V1, REFERENCE_CHECKOUT_V1 } from "./checkoutCommandSchemas.js";
+/** @consumer src/domains/commerce/paymentContinuationContracts.ts */
+export { checkoutContinuationJourneyIdSchema, CHECKOUT_PAYMENT_CONTINUATION_TTL_SECONDS } from "./paymentContinuation.js";
+/** @consumer server/domains/commerce/checkoutOfferPolicyPort.ts */
+export { commerceOfferEvidenceSchema } from "./offerEvidenceSchemas.js";
+/** @consumer src/domains/commerce/offerAvailability.ts */
+export { DEFAULT_LOW_STOCK_THRESHOLD, deriveOfferAvailability, defaultOfferAvailability, availabilityBySku, statusForSellableNow, reasonCodeFor } from "./offerAvailability.js";

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

@@ -0,0 +1,40 @@
+import type { CustomerFulfillmentStep } from "@openlup/core/fulfillment";
+import type { ProviderStatusEvidence, ReleasedProviderExceptionHold, ResolvedProviderExceptionRecovery, TimedFulfillmentSignal } from "../contracts/fulfillmentRecovery.js";
+export { stepForToken } from "@openlup/core/fulfillment";
+export type { CustomerFulfillmentStep } from "@openlup/core/fulfillment";
+export type { ProviderStatusEvidence, ReleasedProviderExceptionHold, ResolvedProviderExceptionRecovery, TimedFulfillmentSignal } from "../contracts/fulfillmentRecovery.js";
+/** Server-only shape read from a released automatic provider-exception hold. */
+/**
+ * Finds only database-authored, trigger-created recovery links. The returned IDs
+ * stay server-side: the browser receives the resulting Layer C step, never hold
+ * metadata or provider evidence identifiers.
+ */
+export declare function resolveProviderExceptionRecovery(input: {
+    automaticHoldSource?: string;
+    automaticReleaseSource?: string;
+    fulfillmentOrderId: string | null | undefined;
+    releasedHolds: ReleasedProviderExceptionHold[];
+    statusEvidence: ProviderStatusEvidence[];
+}): ResolvedProviderExceptionRecovery;
+/**
+ * The customer step for an order that is terminal BY OUR OWN DECISION
+ * (`cancelled` / `refunded`), or `null` when normal rank resolution applies.
+ *
+ * Rank alone is not enough here: `delivered` (7) outranks `cancelled` (6), so a
+ * single provider `DELIVERED` evidence row on an order we cancelled would tell
+ * the customer "delivered". Carrier evidence is a fact and stays recorded, but
+ * it cannot un-cancel our own order, so the terminal order status wins.
+ *
+ * This is a ceiling, not a new opinion: `delivered` is the ONLY step ranking
+ * above `cancelled`, and the order's own status already contributes `cancelled`
+ * to the ranked signals, so every non-delivered outcome is unchanged. The canon's
+ * ranks stay untouched — they are shared with OMS health, observability and the
+ * admin timeline, where provider-versus-local divergence must remain visible.
+ * Single owner of this rule: the customer read model and the browser fallback
+ * resolver both call it instead of each keeping a copy.
+ */
+export declare function customerStepForTerminalOrder(orderStatus: string | null | undefined): CustomerFulfillmentStep | null;
+/** Resolve rank normally; only a uniquely newer canonical timed exception may cover delivered. */
+export declare function customerStepFromTimedSignals(baseTokens: Array<string | null | undefined>, evidence: TimedFulfillmentSignal[], recovery?: ResolvedProviderExceptionRecovery): CustomerFulfillmentStep;
+/** Keep legacy/provider-only Provider CANCELLED evidence customer-safe. */
+export declare function customerSafeEvidenceToken(localStatus: string | null | undefined, providerStatus: string | null | undefined): string | null;

package/dist/commerce/model/customerFulfillmentRecovery.js

@@ -0,0 +1,144 @@
+import { canonicalStatusToken, customerStepFromSignals, stepForToken } from "@openlup/core/fulfillment";
+export { stepForToken } from "@openlup/core/fulfillment";
+/** Server-only shape read from a released automatic provider-exception hold. */
+/**
+ * Finds only database-authored, trigger-created recovery links. The returned IDs
+ * stay server-side: the browser receives the resulting Layer C step, never hold
+ * metadata or provider evidence identifiers.
+ */
+export function resolveProviderExceptionRecovery(input) {
+    const clearedExceptionEvidenceIds = new Set();
+    const recoveryEvidenceIds = new Set();
+    const fulfillmentOrderId = text(input.fulfillmentOrderId);
+    if (!fulfillmentOrderId)
+        return { clearedExceptionEvidenceIds, recoveryEvidenceIds };
+    const evidenceById = new Map(input.statusEvidence
+        .map((row) => [text(row.id), row])
+        .filter(([id]) => Boolean(id)));
+    for (const hold of input.releasedHolds) {
+        if (hold.status !== "released"
+            || hold.reason !== "fulfillment_exception"
+            || hold.createdBy !== null
+            || hold.releasedBy !== null) {
+            continue;
+        }
+        const metadata = record(hold.metadata);
+        const recovery = record(metadata.autoReleaseEvidence);
+        if ((!input.automaticHoldSource || metadata.source !== input.automaticHoldSource)
+            || metadata.autoReleased !== true
+            || (!input.automaticReleaseSource || metadata.autoReleaseSource !== input.automaticReleaseSource)
+            || (metadata.autoReleaseProof !== "provider_recovered" && metadata.autoReleaseProof !== "delivered")
+            || recovery.fulfillmentOrderId !== fulfillmentOrderId) {
+            continue;
+        }
+        const cleared = evidenceById.get(text(recovery.clearedStatusEvidenceId));
+        const recovered = evidenceById.get(text(recovery.statusEvidenceId));
+        if (!cleared || !recovered || text(cleared.fulfillmentOrderId) !== fulfillmentOrderId || text(recovered.fulfillmentOrderId) !== fulfillmentOrderId) {
+            continue;
+        }
+        const clearedStatus = canonicalStatusToken(cleared.providerStatus);
+        const recoveryStatus = canonicalStatusToken(recovered.localStatus);
+        if (canonicalStatusToken(cleared.localStatus) !== "exception"
+            || (clearedStatus !== "suspended" && clearedStatus !== "shipping_failed")
+            || !sameInstant(recovery.clearedOccurredAt, cleared.occurredAt)
+            || !sameInstant(recovery.occurredAt, recovered.occurredAt)
+            || !isStrictlyNewer(recovered.occurredAt, cleared.occurredAt)
+            || canonicalStatusToken(text(recovery.clearedProviderStatus)) !== clearedStatus
+            || canonicalStatusToken(text(recovery.localStatus)) !== recoveryStatus
+            || !isApprovedRecovery(clearedStatus, recoveryStatus, metadata.autoReleaseProof)) {
+            continue;
+        }
+        const clearedId = text(cleared.id);
+        const recoveredId = text(recovered.id);
+        if (!clearedId || !recoveredId)
+            continue;
+        clearedExceptionEvidenceIds.add(clearedId);
+        recoveryEvidenceIds.add(recoveredId);
+    }
+    return { clearedExceptionEvidenceIds, recoveryEvidenceIds };
+}
+/**
+ * The customer step for an order that is terminal BY OUR OWN DECISION
+ * (`cancelled` / `refunded`), or `null` when normal rank resolution applies.
+ *
+ * Rank alone is not enough here: `delivered` (7) outranks `cancelled` (6), so a
+ * single provider `DELIVERED` evidence row on an order we cancelled would tell
+ * the customer "delivered". Carrier evidence is a fact and stays recorded, but
+ * it cannot un-cancel our own order, so the terminal order status wins.
+ *
+ * This is a ceiling, not a new opinion: `delivered` is the ONLY step ranking
+ * above `cancelled`, and the order's own status already contributes `cancelled`
+ * to the ranked signals, so every non-delivered outcome is unchanged. The canon's
+ * ranks stay untouched — they are shared with OMS health, observability and the
+ * admin timeline, where provider-versus-local divergence must remain visible.
+ * Single owner of this rule: the customer read model and the browser fallback
+ * resolver both call it instead of each keeping a copy.
+ */
+export function customerStepForTerminalOrder(orderStatus) {
+    return stepForToken(orderStatus) === "cancelled" ? "cancelled" : null;
+}
+/** Resolve rank normally; only a uniquely newer canonical timed exception may cover delivered. */
+export function customerStepFromTimedSignals(baseTokens, evidence, recovery) {
+    const recovered = recovery?.clearedExceptionEvidenceIds.size;
+    const effectiveBaseTokens = recovered
+        ? baseTokens.filter((token) => stepForToken(token) !== "exception")
+        : baseTokens;
+    const effectiveEvidence = recovery
+        ? evidence.filter((signal) => !recovery.clearedExceptionEvidenceIds.has(text(signal.id)))
+        : evidence;
+    const ranked = customerStepFromSignals([...effectiveBaseTokens, ...effectiveEvidence.map((signal) => signal.token)]);
+    if (ranked !== "delivered")
+        return ranked;
+    const timedOccurrences = effectiveEvidence
+        .map((signal) => ({ step: stepForToken(signal.token), time: validTimestamp(signal.occurredAt) }))
+        .filter((signal) => signal.time !== null);
+    const timed = [...new Map(timedOccurrences.map((signal) => [
+            `${signal.step ?? "unknown"}:${signal.time}`,
+            signal,
+        ])).values()];
+    const latestTime = Math.max(...timed.map((signal) => signal.time));
+    const latest = timed.filter((signal) => signal.time === latestTime);
+    const deliveryTimes = timed.filter((signal) => signal.step === "delivered").map((signal) => signal.time);
+    const latestDeliveryTime = deliveryTimes.length ? Math.max(...deliveryTimes) : null;
+    return latest.length === 1 && latest[0].step === "exception"
+        && latestDeliveryTime !== null && latestTime > latestDeliveryTime ? "exception" : ranked;
+}
+/** Keep legacy/provider-only Provider CANCELLED evidence customer-safe. */
+export function customerSafeEvidenceToken(localStatus, providerStatus) {
+    const local = canonicalStatusToken(localStatus);
+    const provider = canonicalStatusToken(providerStatus);
+    if (provider === "cancelled" && (local === null || local === "cancelled"))
+        return "exception";
+    return local ?? provider;
+}
+function validTimestamp(value) {
+    if (!value || !/(?:[Zz]|[+-]\d{2}:\d{2})$/.test(value))
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+function isApprovedRecovery(clearedStatus, recoveryStatus, proof) {
+    if (proof === "delivered")
+        return recoveryStatus === "delivered";
+    return clearedStatus === "suspended"
+        && proof === "provider_recovered"
+        && ["provider_received", "picking", "packed", "in_transit"].includes(recoveryStatus ?? "");
+}
+function isStrictlyNewer(candidate, previous) {
+    const candidateTime = validTimestamp(candidate);
+    const previousTime = validTimestamp(previous);
+    return candidateTime !== null && previousTime !== null && candidateTime > previousTime;
+}
+function sameInstant(metadataValue, evidenceValue) {
+    if (typeof metadataValue !== "string")
+        return false;
+    const metadataTime = validTimestamp(metadataValue);
+    const evidenceTime = validTimestamp(evidenceValue);
+    return metadataTime !== null && evidenceTime !== null && metadataTime === evidenceTime;
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}

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

@@ -0,0 +1,7 @@
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+export declare function canCancelFulfillment(status: OmsOrderDetail["fulfillmentStatus"], providerCancellation: {
+    activeHoldCount: number;
+    orderMode: "one_time" | "subscription_cycle";
+    orderStatus: OmsOrderDetail["status"];
+    providerCancellationConfirmed: boolean;
+}): boolean;

package/dist/commerce/model/fulfillmentCancellationEligibility.js

@@ -0,0 +1,9 @@
+export function canCancelFulfillment(status, providerCancellation) {
+    if (status === "created" || status === "packed" || status === "label_pending")
+        return true;
+    return status === "exception"
+        && providerCancellation.activeHoldCount === 0
+        && providerCancellation.orderMode === "one_time"
+        && (providerCancellation.orderStatus === "paid" || providerCancellation.orderStatus === "fulfillment_pending")
+        && providerCancellation.providerCancellationConfirmed;
+}

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

@@ -0,0 +1,12 @@
+import type { OmsAccountingRecoveryGuidance } from "../contracts/omsTypes.js";
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import type { OmsAccountingInvoiceRow, OmsAccountingOutboxRow } from "./omsReadModelRows.js";
+export type { OmsAccountingRecoveryGuidance } from "../contracts/omsTypes.js";
+export declare function accountingSummary(invoice: OmsAccountingInvoiceRow | null, outboxRows: OmsAccountingOutboxRow[], projections?: OmsReadModelProjections): OmsOrderDetail["accounting"];
+export declare function accountingRecoveryGuidance(outboxStatus: string | null, invoiceStatus?: string | null): OmsAccountingRecoveryGuidance;
+export declare function sanitizeAccountingLastError(value: unknown): {
+    code: string | null;
+    message: string | null;
+    retryable: boolean | null;
+} | null;

package/dist/commerce/model/omsAccountingVisibility.js

@@ -0,0 +1,118 @@
+export function accountingSummary(invoice, outboxRows, projections) {
+    if (!invoice) {
+        return {
+            status: "missing",
+            invoiceId: null,
+            invoiceRef: null,
+            providerKind: null,
+            providerInvoiceNumber: null,
+            fiscalStatus: null,
+            outboxStatus: null,
+            outboxAttemptCount: null,
+            outboxNextAttemptAt: null,
+            outboxLastError: null,
+            recoveryGuidance: "not_requested",
+            updatedAt: null,
+        };
+    }
+    const outbox = selectAccountingOutbox(invoice.id, outboxRows);
+    return {
+        status: outbox?.status === "failed" ? "outbox_failed" : normalizeAccountingStatus(invoice.status, projections?.additionalAccountingStatuses),
+        invoiceId: invoice.id,
+        invoiceRef: invoice.invoice_ref,
+        providerKind: invoice.provider_kind,
+        providerInvoiceNumber: invoice.provider_invoice_number,
+        fiscalStatus: invoice.fiscal_status,
+        outboxStatus: outbox?.status ?? null,
+        outboxAttemptCount: outbox?.attempt_count ?? null,
+        outboxNextAttemptAt: outbox?.next_attempt_at ?? null,
+        outboxLastError: sanitizeAccountingLastError(outbox?.last_error),
+        recoveryGuidance: accountingRecoveryGuidance(outbox?.status ?? null, invoice.status),
+        updatedAt: invoice.updated_at,
+    };
+}
+function selectAccountingOutbox(invoiceId, outboxRows) {
+    return outboxRows
+        .filter((row) => row.invoice_id === invoiceId)
+        .sort(compareAccountingOutboxRows)[0] ?? null;
+}
+function compareAccountingOutboxRows(a, b) {
+    const priority = outboxStatusPriority(a.status) - outboxStatusPriority(b.status);
+    if (priority !== 0)
+        return priority;
+    const aCreatedAt = timestampOrNull(a.created_at);
+    const bCreatedAt = timestampOrNull(b.created_at);
+    if (aCreatedAt !== null && bCreatedAt !== null && aCreatedAt !== bCreatedAt) {
+        return bCreatedAt - aCreatedAt;
+    }
+    if (aCreatedAt !== null && bCreatedAt === null)
+        return -1;
+    if (aCreatedAt === null && bCreatedAt !== null)
+        return 1;
+    return 0;
+}
+function timestampOrNull(value) {
+    if (!value)
+        return null;
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) ? timestamp : null;
+}
+function outboxStatusPriority(status) {
+    if (status === "failed")
+        return 0;
+    if (status === "processing")
+        return 1;
+    if (status === "pending" || status === "queued")
+        return 2;
+    if (status === "succeeded")
+        return 3;
+    if (status === "cancelled")
+        return 4;
+    return 5;
+}
+export function accountingRecoveryGuidance(outboxStatus, invoiceStatus = null) {
+    if (outboxStatus === "failed")
+        return "review_and_retry";
+    if (outboxStatus === "pending" || outboxStatus === "processing" || outboxStatus === "queued") {
+        return "wait_for_retry";
+    }
+    if (invoiceStatus === "blocked" || invoiceStatus === "rejected")
+        return "review_and_retry";
+    if (invoiceStatus === "issued" || invoiceStatus === "accepted" || invoiceStatus === "corrected" || invoiceStatus === "voided") {
+        return "none";
+    }
+    return outboxStatus ? "none" : "not_requested";
+}
+export function sanitizeAccountingLastError(value) {
+    if (!isRecord(value))
+        return null;
+    const code = readSafeText(value, "code", 80) ??
+        readSafeText(value, "errorCode", 80) ??
+        readSafeText(value, "reason", 80) ??
+        readSafeText(value, "type", 80);
+    const message = readSafeText(value, "operatorMessage", 240) ??
+        readSafeText(value, "message", 240);
+    const retryable = typeof value.retryable === "boolean" ? value.retryable : null;
+    if (!code && !message && retryable === null)
+        return null;
+    return { code, message, retryable };
+}
+function readSafeText(record, key, maxLength) {
+    const value = record[key];
+    if (typeof value !== "string")
+        return null;
+    const normalized = redactSensitiveText(value.trim().replace(/\s+/g, " "));
+    return normalized ? normalized.slice(0, maxLength) : null;
+}
+function redactSensitiveText(value) {
+    return value
+        .replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "[redacted-email]")
+        .replace(/\b(?:bearer|token|secret|api[_-]?key|authorization)\s*[:=]?\s+[A-Za-z0-9._~+/=-]{8,}/gi, "[redacted-secret]");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeAccountingStatus(status, additional = []) {
+    const valid = ["draft", "issue_requested", "blocked", "issued", "accepted", "rejected", "correction_requested", "corrected", "voided"];
+    return [...valid, ...additional].includes(status) ? status : "missing";
+}

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

@@ -0,0 +1,2 @@
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+export declare function enrichBillingWithInvoiceBuyer(billing: OmsOrderDetail["billingAddress"], orderMetadata: Record<string, unknown> | null): OmsOrderDetail["billingAddress"];

package/dist/commerce/model/omsBillingInvoiceBuyer.js

@@ -0,0 +1,15 @@
+export function enrichBillingWithInvoiceBuyer(billing, orderMetadata) {
+    if (!billing)
+        return billing;
+    const snapshot = orderMetadata && typeof orderMetadata === "object"
+        ? orderMetadata.invoiceBuyerSnapshot
+        : null;
+    if (!snapshot || typeof snapshot !== "object")
+        return billing;
+    const buyer = snapshot;
+    const companyName = billing.companyName ?? (typeof buyer.companyName === "string" && buyer.companyName.trim() ? buyer.companyName : null);
+    const taxId = billing.taxId ?? (typeof buyer.taxId === "string" && buyer.taxId.trim() ? buyer.taxId : null);
+    if (companyName === billing.companyName && taxId === billing.taxId)
+        return billing;
+    return { ...billing, companyName, taxId };
+}

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

@@ -0,0 +1,4 @@
+import type { OmsCurrencyPolicy } from "../contracts/omsTypes.js";
+export type { OmsCurrencyPolicy } from "../contracts/omsTypes.js";
+/** Settlement policy is supplied by the host; the neutral default checks format only. */
+export declare const neutralOmsCurrencyPolicy: OmsCurrencyPolicy;

package/dist/commerce/model/omsCurrency.js

@@ -0,0 +1,5 @@
+/** Settlement policy is supplied by the host; the neutral default checks format only. */
+export const neutralOmsCurrencyPolicy = {
+    defaultCurrency: "XXX",
+    accepts: currency => /^[A-Z]{3}$/.test(currency),
+};

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

@@ -0,0 +1,20 @@
+import type { OmsFulfillmentProviderStockCurrentRow, OmsInboundProviderEventRow } from "../contracts/omsTypes.js";
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import { type OmsProviderAttemptRow, type OmsProviderDispatchRefRow, type OmsProviderStatusEvidenceRow } from "./omsFulfillmentSummary.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import type { OmsCommunicationDeliveryRow, OmsInventoryReservationRow } from "./omsReadModelRows.js";
+export type { OmsFulfillmentProviderStockCurrentRow, OmsInboundProviderEventRow } from "../contracts/omsTypes.js";
+type Debug = OmsOrderDetail["fulfillmentDebug"];
+export declare function buildOmsFulfillmentDebug(input: {
+    projections?: OmsReadModelProjections;
+    paymentStatus: OmsOrderDetail["paymentStatus"];
+    inventory: OmsOrderDetail["inventory"];
+    fulfillment: OmsOrderDetail["fulfillment"];
+    reservations: OmsInventoryReservationRow[];
+    communicationDeliveries: OmsCommunicationDeliveryRow[];
+    providerAttempts: OmsProviderAttemptRow[];
+    providerDispatchRefs: OmsProviderDispatchRefRow[];
+    providerStatusEvidence: OmsProviderStatusEvidenceRow[];
+    inboundProviderEvents: OmsInboundProviderEventRow[];
+    providerStockCurrent?: OmsFulfillmentProviderStockCurrentRow[];
+}): Debug;