@openlup/platform 0.26.0 → 0.27.0

package/dist/commerce/adapters/managed/oms/accounting.js

@@ -0,0 +1,13 @@
+import { CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+export async function readAccountingOutbox(client, invoices) {
+    const result = invoices.length
+        ? await client
+            .query("accounting_invoice_issue_outbox")
+            .select("invoice_id, status, attempt_count, next_attempt_at, last_error, created_at")
+            .in("invoice_id", invoices.map((invoice) => invoice.id))
+            .order("created_at", { ascending: false })
+        : { data: [], error: null };
+    if (result.error)
+        throw new CommerceOmsPersistenceError("Commerce OMS accounting outbox list read failed");
+    return (result.data ?? []);
+}

package/dist/commerce/adapters/managed/oms/fulfillmentReads.d.ts

@@ -0,0 +1,17 @@
+import type { CommerceOmsStore, RpcError } from "./types.js";
+export declare function readShipmentRefsByOrderIds(client: CommerceOmsStore, orderIds: string[]): Promise<import("./types.js").ManagedQueryResult>;
+export declare function readShipmentRefsByOrderId(client: CommerceOmsStore, orderId: string): Promise<import("./types.js").ManagedQueryResult>;
+export declare function isOptionalProviderEvidenceColumnError(error: {
+    code?: string;
+    message?: string;
+    details?: string;
+    hint?: string;
+} | null): boolean;
+export declare function readFulfillmentParcelsByOrderId(client: CommerceOmsStore, orderId: string): Promise<{
+    data: unknown[];
+    error: RpcError | null;
+}>;
+export declare function readFulfillmentOrdersByOrderIds(client: CommerceOmsStore, orderIds: string[]): Promise<{
+    data: unknown[];
+    error: RpcError | null;
+}>;

package/dist/commerce/adapters/managed/oms/fulfillmentReads.js

@@ -0,0 +1,81 @@
+import { currentParcelFirst } from "@openlup/core/fulfillment";
+const SHIPMENT_EXTERNAL_REF_BASE_COLUMNS = "order_id, provider_tracking_id, active";
+// `fulfillment_order_id` rides the rich list: it is what narrows an order's references to the
+// parcel currently representing it, and a deployment that predates the column falls back to the
+// base list, where every reference answers for every parcel exactly as it did before.
+const SHIPMENT_EXTERNAL_REF_COLUMNS = `${SHIPMENT_EXTERNAL_REF_BASE_COLUMNS}, fulfillment_order_id, provider_kind, tracking_url, carrier_kind, service, created_at, updated_at`;
+// Kept out of the shared provider-evidence matcher on purpose: that one also guards the
+// fulfillment-order reads, and `fulfillment_order_id` is a column half the schema carries, so
+// folding it in there would silently downgrade an unrelated read on any error naming it.
+function isMissingParcelAttributionError(error) {
+    if (!error)
+        return false;
+    return `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`.toLowerCase().includes("fulfillment_order_id");
+}
+function shipmentRefReadDegrades(error) {
+    return isOptionalProviderEvidenceColumnError(error) || isMissingParcelAttributionError(error);
+}
+export async function readShipmentRefsByOrderIds(client, orderIds) {
+    if (!orderIds.length)
+        return { data: [], error: null };
+    const result = await client.query("shipment_external_refs").select(SHIPMENT_EXTERNAL_REF_COLUMNS).in("order_id", orderIds).eq("active", true);
+    if (!shipmentRefReadDegrades(result.error))
+        return result;
+    return client.query("shipment_external_refs").select(SHIPMENT_EXTERNAL_REF_BASE_COLUMNS).in("order_id", orderIds).eq("active", true);
+}
+export async function readShipmentRefsByOrderId(client, orderId) {
+    const result = await client.query("shipment_external_refs").select(SHIPMENT_EXTERNAL_REF_COLUMNS).eq("order_id", orderId).eq("active", true);
+    if (!shipmentRefReadDegrades(result.error))
+        return result;
+    return client.query("shipment_external_refs").select(SHIPMENT_EXTERNAL_REF_BASE_COLUMNS).eq("order_id", orderId).eq("active", true);
+}
+// `sequence_no` rides the BASE list, not the rich one: it is what resolves which parcel
+// currently represents an order, so the degraded read that drops provider evidence must still
+// be able to answer that question deterministically.
+const FULFILLMENT_ORDER_BASE_COLUMNS = "id, order_id, sequence_no, status, shipping_address_snapshot, handed_over_at, delivered_at, created_at, updated_at";
+// `handed_over_at` rides the query that already reads the row, and is the only durable witness of
+// which side of handover a provider exception happened on - the FSM's `exception` no longer says.
+// `replaces_fulfillment_order_id` and `replacement_reason` ride the rich list with
+// `provider_kind`: they are what tells an operator that the parcel on their screen IS a
+// replacement and why, and a deployment that predates them degrades to the base list, where
+// every parcel reads as the original exactly as it did before the columns existed.
+const FULFILLMENT_ORDER_COLUMNS = `${FULFILLMENT_ORDER_BASE_COLUMNS}, provider_kind, replaces_fulfillment_order_id, replacement_reason`;
+// A deployment that predates the optional provider-evidence columns answers the rich select with
+// a missing-column error; every read here retries on the base list rather than failing.
+export function isOptionalProviderEvidenceColumnError(error) {
+    if (!error)
+        return false;
+    const text = `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`.toLowerCase();
+    return ["fulfillment_provider_stock_current", "provider_kind", "tracking_url", "carrier_kind", "service", "replaces_fulfillment_order_id", "replacement_reason"].some((column) => text.includes(column)); // Only columns the BASE list OMITS belong here: created_at/updated_at are in it, so they could never be recovered - they only widened the silent downgrade.
+}
+// Deliberately no `.maybeSingle()`: PostgREST *errors* (PGRST116) when a single-object read
+// matches two rows, and an order carrying a replacement parcel holds two.
+//
+// ⚠️ This returns EVERY parcel of the order, current one first, where it used to return the
+// current one alone. That is what stopped the original parcel's tracking from vanishing from
+// the operator's screen the moment a replacement existed. Callers that need exactly one row
+// take `[0]`, which `currentParcelFirst` guarantees is the current parcel; nothing downstream
+// widens its attribution, because the provider-evidence reads are still keyed on that one id.
+export async function readFulfillmentParcelsByOrderId(client, orderId) {
+    const rich = await client.query("commerce_fulfillment_orders").select(FULFILLMENT_ORDER_COLUMNS).eq("order_id", orderId);
+    const result = isOptionalProviderEvidenceColumnError(rich.error)
+        ? await client.query("commerce_fulfillment_orders").select(FULFILLMENT_ORDER_BASE_COLUMNS).eq("order_id", orderId)
+        : rich;
+    if (result.error)
+        return { data: [], error: result.error };
+    return { data: currentParcelFirst((result.data ?? [])), error: null };
+}
+// The list read hands every order's rows to one builder, which narrows per order and then takes
+// the first of what is left (`omsReadModelList.ts` filter -> `omsFulfillmentSummary.ts` [0]), so
+// each order's rows must arrive with its current parcel first.
+export async function readFulfillmentOrdersByOrderIds(client, orderIds) {
+    if (!orderIds.length)
+        return { data: [], error: null };
+    const rich = await client.query("commerce_fulfillment_orders").select(FULFILLMENT_ORDER_COLUMNS).in("order_id", orderIds);
+    const result = isOptionalProviderEvidenceColumnError(rich.error)
+        ? await client.query("commerce_fulfillment_orders").select(FULFILLMENT_ORDER_BASE_COLUMNS).in("order_id", orderIds)
+        : rich;
+    if (result.error)
+        return { data: [], error: result.error };
+    return { data: currentParcelFirst((result.data ?? [])), error: null };
+}

package/dist/commerce/adapters/managed/oms/inboundEvents.d.ts

@@ -0,0 +1,9 @@
+import type { OmsInboundProviderEventRow } from "../../../model/omsFulfillmentDebug.js";
+import type { OmsProviderDispatchRefRow } from "../../../model/omsFulfillmentSummary.js";
+import type { OmsOrderRow } from "../../../model/omsReadModel.js";
+import { type CommerceOmsStore } from "./types.js";
+export declare function readOmsInboundEvents(client: CommerceOmsStore, input: {
+    order: OmsOrderRow;
+    dispatchRefs: OmsProviderDispatchRefRow[];
+    providerKind: string;
+}): Promise<OmsInboundProviderEventRow[]>;

package/dist/commerce/adapters/managed/oms/inboundEvents.js

@@ -0,0 +1,40 @@
+import { CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+import { distinctIds } from "./types.js";
+const INBOUND_EVENT_COLUMNS = "id, provider, provider_event_id, event_type, processing_status, payload, error, created_at, processed_at";
+export async function readOmsInboundEvents(client, input) {
+    const needles = distinctIds([
+        input.order.order_number,
+        input.order.id,
+        ...input.dispatchRefs.map((row) => row.provider_order_id ?? null),
+    ]);
+    if (!needles.length)
+        return [];
+    const result = await client
+        .query("inbound_provider_events")
+        .select(INBOUND_EVENT_COLUMNS)
+        .eq("provider", input.providerKind)
+        .order("created_at", { ascending: false })
+        .range(0, 49);
+    if (isOptionalInboundEventError(result.error))
+        return [];
+    if (result.error)
+        throw new CommerceOmsPersistenceError("Commerce OMS provider inbound events read failed");
+    return (result.data ?? []).filter((row) => matchesNeedle(row, needles));
+}
+function matchesNeedle(row, needles) {
+    const haystack = JSON.stringify({
+        providerEventId: row.provider_event_id,
+        eventType: row.event_type,
+        payload: row.payload,
+        error: row.error,
+    });
+    return needles.some((needle) => haystack.includes(needle));
+}
+function isOptionalInboundEventError(error) {
+    if (!error)
+        return false;
+    if (error.code === "42P01" || error.code === "42703")
+        return true;
+    const text = `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`.toLowerCase();
+    return text.includes("inbound_provider_events");
+}

package/dist/commerce/adapters/managed/oms/outboxEvents.d.ts

@@ -0,0 +1,2 @@
+import type { CommerceOmsStore } from "./types.js";
+export declare function readOrderPaidOutboxEvents(client: CommerceOmsStore, orderId: string): Promise<import("./types.js").ManagedQueryResult>;

package/dist/commerce/adapters/managed/oms/outboxEvents.js

@@ -0,0 +1,23 @@
+import { COMMERCE_ORDER_PAID_EVENT_TYPE } from "../../../outboxEventSchemas.js";
+const ORDER_PAID_OUTBOX_COLUMNS = "id,event_type,status,aggregate_id,created_at,available_at,attempts";
+const ORDER_PAID_OUTBOX_BASE_COLUMNS = "id,event_type,status,aggregate_id,created_at,available_at";
+export async function readOrderPaidOutboxEvents(client, orderId) {
+    const primary = await selectOrderPaidOutboxEvents(client, orderId, ORDER_PAID_OUTBOX_COLUMNS);
+    if (!isMissingAttemptsColumn(primary.error))
+        return primary;
+    return selectOrderPaidOutboxEvents(client, orderId, ORDER_PAID_OUTBOX_BASE_COLUMNS);
+}
+function selectOrderPaidOutboxEvents(client, orderId, columns) {
+    return client
+        .query("outbox_events")
+        .select(columns)
+        .eq("event_type", COMMERCE_ORDER_PAID_EVENT_TYPE)
+        .eq("aggregate_id", orderId)
+        .order("created_at", { ascending: false });
+}
+function isMissingAttemptsColumn(error) {
+    if (!error)
+        return false;
+    const text = `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`.toLowerCase();
+    return text.includes("attempts");
+}

package/dist/commerce/adapters/managed/oms/paymentAttempts.d.ts

@@ -0,0 +1,3 @@
+import type { OmsPaymentAttemptRow, OmsPaymentIntentRow } from "../../../model/omsReadModel.js";
+import type { CommerceOmsStore } from "./types.js";
+export declare function readActivePaymentAttempts(client: CommerceOmsStore, paymentIntents: OmsPaymentIntentRow[]): Promise<OmsPaymentAttemptRow[]>;

package/dist/commerce/adapters/managed/oms/paymentAttempts.js

@@ -0,0 +1,15 @@
+import { CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+export async function readActivePaymentAttempts(client, paymentIntents) {
+    const attemptIds = paymentIntents
+        .map((intent) => intent.active_attempt_id)
+        .filter((id) => Boolean(id));
+    if (attemptIds.length === 0)
+        return [];
+    const result = await client
+        .query("commerce_payment_attempts")
+        .select("id, payment_intent_id, status, provider, provider_attempt_id, next_action_kind, updated_at")
+        .in("id", attemptIds);
+    if (result.error)
+        throw new CommerceOmsPersistenceError("Commerce OMS payment attempt list read failed");
+    return (result.data ?? []);
+}

package/dist/commerce/adapters/managed/oms/queueSelection.d.ts

@@ -0,0 +1,12 @@
+import type { OmsManagedReadProjections } from "../../../contracts/omsTypes.js";
+type MatchSchema = NonNullable<OmsManagedReadProjections["queueMatchSchema"]>;
+import type { QueueSelection } from "../../../contracts/omsTypes.js";
+import { type OmsCurrencyPolicy } from "../../../model/omsCurrency.js";
+import type { AdminCommerceOrdersListRequest } from "../../../oms/omsContracts.js";
+import type { CommerceOmsStore } from "./types.js";
+export type { QueueSelection } from "../../../contracts/omsTypes.js";
+export declare function readQueueSelection(client: CommerceOmsStore, request: AdminCommerceOrdersListRequest, options?: {
+    currency?: OmsCurrencyPolicy;
+    matchSchema?: MatchSchema;
+    projectResult?(data: unknown): unknown;
+}): Promise<QueueSelection>;

package/dist/commerce/adapters/managed/oms/queueSelection.js

@@ -0,0 +1,109 @@
+import { neutralOmsCurrencyPolicy } from "../../../model/omsCurrency.js";
+import { omsOrderListSummaryCountsSchema, omsOrderListSummaryTotalsSchema, omsOrderSearchMatchSchema } from "../../../oms/omsContracts.js";
+import { CommerceOmsPersistenceError } from "../../../oms/omsPorts.js";
+/** The refusal the queue RPC raises when the paid set spans several currencies. */
+const MIXED_CURRENCY_REFUSAL = "commerce_oms_summary_mixed_currency";
+export async function readQueueSelection(client, request, options = {}) {
+    const { data, error } = await client.rpc("commerce_oms_admin_list_queue", {
+        p_page: request.page,
+        p_page_size: request.pageSize,
+        p_search: request.search ?? null,
+        p_status: request.status ?? null,
+        p_mode: request.mode ?? null,
+        p_payment_status: request.paymentStatus ?? null,
+        p_fulfillment_status: request.fulfillmentStatus ?? null,
+        p_inventory_status: request.inventoryStatus ?? null,
+        p_accounting_status: request.accountingStatus ?? null,
+        p_provider_ops_status: request.providerOpsStatus ?? null,
+        p_attention_reason: request.attentionReason ?? null,
+        p_attention_only: request.attentionOnly ?? false,
+        p_next_action: request.nextAction ?? null,
+        p_from: request.from ?? null,
+        p_to: request.to ?? null,
+        p_sort: request.sort,
+        // Default false: the queue hides withdrawn rows unless the operator asks.
+        // The RPC declares no parameter defaults, so this must always be sent.
+        p_include_withdrawn: request.includeWithdrawn ?? false,
+    });
+    if (error)
+        throw queueSelectionError(error);
+    return parseQueueSelection(options.projectResult?.(data) ?? data, options.currency ?? neutralOmsCurrencyPolicy, options.matchSchema);
+}
+// A cross-currency paid set is a refusal the RPC raises on purpose, not a
+// generic read failure: it names an operator-visible condition (two currencies
+// in one dashboard total) that a retry will not clear. Keep it distinguishable.
+function queueSelectionError(error) {
+    const raised = `${error.message ?? ""} ${error.details ?? ""} ${error.hint ?? ""}`;
+    if (raised.includes(MIXED_CURRENCY_REFUSAL)) {
+        return new CommerceOmsPersistenceError("Commerce OMS queue summary spans more than one currency", { reason: MIXED_CURRENCY_REFUSAL });
+    }
+    return new CommerceOmsPersistenceError("Commerce OMS queue selection read failed");
+}
+function parseQueueSelection(data, currency, matchSchema = omsOrderSearchMatchSchema) {
+    const record = isRecord(data) ? data : {};
+    const orderIds = Array.isArray(record.orderIds)
+        ? record.orderIds.filter((id) => typeof id === "string")
+        : [];
+    const totalCount = Number(record.totalCount ?? 0);
+    const summaryCounts = omsOrderListSummaryCountsSchema.parse({
+        ...ZERO_SUMMARY_COUNTS,
+        ...(isRecord(record.summaryCounts) ? record.summaryCounts : {}),
+    });
+    const summaryTotals = omsOrderListSummaryTotalsSchema.parse({
+        gmv: { amountMinor: 0, currency: currency.defaultCurrency },
+        aov: { amountMinor: 0, currency: currency.defaultCurrency },
+        orderCount: 0, paidSubscriptionCycleCount: 0,
+        ...normalizeSummaryTotals(isRecord(record.summaryTotals) ? record.summaryTotals : {}, currency),
+    });
+    const matches = parseMatches(record.matches, matchSchema);
+    if (!Number.isInteger(totalCount) || totalCount < 0) {
+        throw new CommerceOmsPersistenceError("Commerce OMS queue selection count invalid");
+    }
+    return { orderIds, totalCount, matches, summaryCounts, summaryTotals };
+}
+function parseMatches(value, schema) {
+    if (!isRecord(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).flatMap(([orderId, match]) => {
+        const parsed = schema.safeParse(match);
+        return parsed.success ? [[orderId, parsed.data]] : [];
+    }));
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+// The queue RPC still emits the legacy `newSubscriptionCount` JSON key. It counts
+// PAID subscription cycles (the initial checkout cycle #1 plus every paid renewal),
+// so map it onto the accurately-named `paidSubscriptionCycleCount` contract field.
+// The new key is accepted too, so a future RPC rename is a no-op here.
+function normalizeSummaryTotals(raw, currency) {
+    const { newSubscriptionCount, gmv, aov, ...rest } = raw;
+    const normalized = { ...rest };
+    if (gmv !== undefined)
+        normalized.gmv = withDefaultCurrency(gmv, currency);
+    if (aov !== undefined)
+        normalized.aov = withDefaultCurrency(aov, currency);
+    if (newSubscriptionCount !== undefined) {
+        normalized.paidSubscriptionCycleCount = normalized.paidSubscriptionCycleCount ?? newSubscriptionCount;
+    }
+    return normalized;
+}
+// The queue RPC no longer names a currency: `min(currency)` over an EMPTY paid
+// set is NULL by design, so the schema stays currency-agnostic. Labelling a
+// zero total is a platform-policy decision, and policy has exactly one home.
+function withDefaultCurrency(money, currency) {
+    if (!isRecord(money) || money.currency != null)
+        return money;
+    return { ...money, currency: currency.defaultCurrency };
+}
+const ZERO_SUMMARY_COUNTS = {
+    needsAttention: 0,
+    activeHold: 0,
+    readyForFulfillment: 0,
+    paymentIssues: 0,
+    inventoryRisk: 0,
+    fulfillmentBlocked: 0,
+    fulfillmentExceptions: 0,
+    invoiceIssues: 0,
+    providerDispatchedNotPicked: 0,
+};

package/dist/commerce/adapters/managed/oms/readProjections.d.ts

@@ -0,0 +1,18 @@
+export type { OmsManagedReadProjections } from "../../../contracts/omsTypes.js";
+import type { OmsOrderDetail } from "../../../oms/omsContracts.js";
+import type { OmsOrderRow, OmsAccountingInvoiceRow } from "../../../model/omsReadModelRows.js";
+export declare const emptyOmsManagedReadProjections: {
+    readIdentity: () => Promise<Record<string, Record<string, unknown>>>;
+    mapInvoice: (value: unknown) => OmsAccountingInvoiceRow;
+    readFulfillmentOperations: () => Promise<never[]>;
+    readProviderDispatchRefs: () => Promise<never[]>;
+    readProviderStatusEvidence: () => Promise<never[]>;
+    readProviderAttempts: () => Promise<never[]>;
+    readReleasedProviderExceptionHolds: () => Promise<never[]>;
+    readProviderStockCurrent: () => Promise<never[]>;
+    readInboundEvents: () => Promise<never[]>;
+    buildHealth: (input: {
+        order: OmsOrderRow;
+    }) => OmsOrderDetail["fulfillmentHealth"];
+    buildHealthDigests: () => {};
+};

package/dist/commerce/adapters/managed/oms/readProjections.js

@@ -0,0 +1,13 @@
+export const emptyOmsManagedReadProjections = {
+    readIdentity: async () => ({}),
+    mapInvoice: (value) => value,
+    readFulfillmentOperations: async () => [],
+    readProviderDispatchRefs: async () => [],
+    readProviderStatusEvidence: async () => [],
+    readProviderAttempts: async () => [],
+    readReleasedProviderExceptionHolds: async () => [],
+    readProviderStockCurrent: async () => [],
+    readInboundEvents: async () => [],
+    buildHealth: (input) => ({ healthStatus: "ok", attentionReasons: [], oldestAgeSeconds: null, opaqueIds: { orderId: input.order.id, fulfillmentOrderId: null, outboxEventId: null, dispatchRefFulfillmentOrderId: null, latestEvidenceFulfillmentOrderId: null } }),
+    buildHealthDigests: () => ({}),
+};

package/dist/commerce/adapters/managed/oms/readQueries.d.ts

@@ -0,0 +1,16 @@
+import { type OmsActionAvailabilityFlags } from "../../../model/omsReadModelHelpers.js";
+import { type AdminCommerceOrderDetailRequest, type AdminCommerceOrderDetailResponse, type AdminCommerceOrdersListRequest, type AdminCommerceOrdersListResponse } from "../../../oms/omsContracts.js";
+import { type OmsManagedReadProjections } from "./readProjections.js";
+import { type CommerceOmsStore } from "./types.js";
+export declare function listCommerceOmsOrders(client: CommerceOmsStore, request: AdminCommerceOrdersListRequest, options?: {
+    projections?: OmsManagedReadProjections;
+}): Promise<AdminCommerceOrdersListResponse>;
+export declare function getCommerceOmsOrderDetail(client: CommerceOmsStore, request: AdminCommerceOrderDetailRequest, options?: {
+    actionFlags?: OmsActionAvailabilityFlags;
+    projections?: OmsManagedReadProjections;
+}): Promise<AdminCommerceOrderDetailResponse | null>;
+/** Hydrate a bounded selection without repeating its canonical header query. */
+export declare function getCommerceOmsOrderDetails(client: CommerceOmsStore, orderIds: string[], options?: {
+    actionFlags?: OmsActionAvailabilityFlags;
+    projections?: OmsManagedReadProjections;
+}): Promise<Array<AdminCommerceOrderDetailResponse | null>>;