@openlup/platform 0.26.0 → 0.27.0

package/src/commerce/model/omsFulfillmentSummary.ts

@@ -0,0 +1,225 @@
+import { rowsForParcel } from "@openlup/core/fulfillment";
+import type { OmsFulfillmentOperationRow,OmsFulfillmentOrderRow,OmsProviderAttemptRow,OmsProviderDispatchRefRow,OmsProviderStatusEvidenceRow,OmsReleasedProviderExceptionHoldRow,OmsShipmentExternalRefRow } from "../contracts/omsTypes.js";
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import {
+customerSafeEvidenceToken,
+customerStepFromTimedSignals,
+resolveProviderExceptionRecovery,stepForToken,type CustomerFulfillmentStep,
+type ReleasedProviderExceptionHold
+} from "./customerFulfillmentRecovery.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+export type { OmsFulfillmentOperationRow,OmsFulfillmentOrderRow,OmsProviderAttemptRow,OmsProviderDispatchRefRow,OmsProviderStatusEvidenceRow,OmsReleasedProviderExceptionHoldRow,OmsShipmentExternalRefRow } from "../contracts/omsTypes.js";
+
+export function buildOmsFulfillmentSummary(input: {
+  projections?: OmsReadModelProjections;
+  fulfillmentOrders: OmsFulfillmentOrderRow[];
+  fulfillmentOperations: OmsFulfillmentOperationRow[];
+  shipmentExternalRefs: OmsShipmentExternalRefRow[];
+  providerAttempts?: OmsProviderAttemptRow[];
+  providerDispatchRefs?: OmsProviderDispatchRefRow[];
+  providerStatusEvidence?: OmsProviderStatusEvidenceRow[];
+}): OmsOrderDetail["fulfillment"] {
+  const fulfillmentOrder = input.fulfillmentOrders[0] ?? null;
+  if (!fulfillmentOrder) {
+    return {
+      fulfillmentOrderId: null,
+      status: null,
+      providerKind: null,
+      latestOperationType: null,
+      latestOperationAt: null,
+      providerTrackingId: null,
+      trackingUrl: null,
+      carrierKind: null,
+      service: null,
+      trackingReferences: [],
+      trackingTimeline: [],
+      providerEvidence: [],
+    };
+  }
+
+  // Every other companion below is already narrowed to this parcel by `fulfillment_order_id`;
+  // tracking references only joined them once the column existed. An unattributed row still
+  // answers for any parcel, so a one-parcel order reads exactly as it did before.
+  const parcelRefs = rowsForParcel(input.shipmentExternalRefs, fulfillmentOrder.id);
+  const trackingReferences = parcelRefs
+    .filter((row) => row.active !== false)
+    .filter((row) => Boolean(row.provider_tracking_id))
+    .map((row) => ({
+      providerKind: row.provider_kind ?? "unknown",
+      trackingNumber: row.provider_tracking_id,
+      trackingUrl: row.tracking_url ?? null,
+      carrierKind: row.carrier_kind ?? row.provider_kind ?? null,
+      service: row.service ?? null,
+      updatedAt: row.updated_at ?? row.created_at ?? null,
+    }))
+    .sort((a, b) => parseTimestampOrZero(b.updatedAt) - parseTimestampOrZero(a.updatedAt));
+  const fulfillmentTimeline = input.fulfillmentOperations
+    .filter((operation) => operation.fulfillment_order_id === fulfillmentOrder.id)
+    .map((operation) => ({
+      eventType: operation.operation_type,
+      label: labelForOperation(operation.operation_type, input.projections),
+      occurredAt: operation.occurred_at,
+      source: "fulfillment" as const,
+    }));
+  const providerStatusTimeline = (input.providerStatusEvidence ?? [])
+    .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+    .map((row) => {
+      const eventType = row.customer_status ?? row.local_status ?? row.provider_status ?? "provider_status";
+      return {
+        eventType,
+        label: labelForOperation(eventType, input.projections),
+        occurredAt: row.occurred_at ?? null,
+        source: sourceForEvidenceKind(row.evidence_kind),
+      };
+    });
+  const dispatchTimeline = (input.providerDispatchRefs ?? [])
+    .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+    .map((row) => ({
+      eventType: `dispatch_${row.status ?? "recorded"}`,
+      label: input.projections?.dispatchLabel?.(row.status) ?? "Provider dispatch recorded",
+      occurredAt: row.updated_at ?? row.created_at ?? null,
+      source: "dispatch" as const,
+    }));
+  const trackingTimeline = [...fulfillmentTimeline, ...providerStatusTimeline, ...dispatchTimeline]
+    .sort((a, b) => parseTimestampOrZero(b.occurredAt) - parseTimestampOrZero(a.occurredAt))
+    .slice(0, 12);
+  const providerEvidence = [
+    ...(input.providerDispatchRefs ?? [])
+      .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+      .map((row) => ({
+        evidenceType: "dispatch_ref" as const,
+        status: row.status ?? null,
+        providerStatus: null,
+        providerOrderId: row.provider_order_id ?? null,
+        evidenceKind: row.dispatch_mode ?? null,
+        occurredAt: row.created_at ?? null,
+        updatedAt: row.updated_at ?? row.created_at ?? null,
+        summary: row.error ? "dispatch_error_present" : null,
+      })),
+    ...(input.providerAttempts ?? [])
+      .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+      .map((row) => ({
+        evidenceType: "provider_attempt" as const,
+        status: row.status ?? null,
+        providerStatus: row.provider_kind ?? null,
+        providerOrderId: null,
+        evidenceKind: "provider_attempt",
+        occurredAt: row.created_at ?? null,
+        updatedAt: row.created_at ?? null,
+        summary: row.error ? "provider_attempt_error_present" : null,
+      })),
+    ...(input.providerStatusEvidence ?? [])
+      .filter((row) => row.fulfillment_order_id === fulfillmentOrder.id)
+      .map((row) => ({
+        evidenceType: "status_evidence" as const,
+        status: row.local_status ?? null,
+        providerStatus: row.provider_status ?? null,
+        providerOrderId: null,
+        evidenceKind: row.evidence_kind ?? null,
+        occurredAt: row.occurred_at ?? null,
+        updatedAt: row.created_at ?? null,
+        summary: row.provider_sub_status ?? null,
+      })),
+  ].sort((a, b) => parseTimestampOrZero(b.updatedAt ?? b.occurredAt) - parseTimestampOrZero(a.updatedAt ?? a.occurredAt));
+  const latestOperation = input.fulfillmentOperations
+    .find((operation) => operation.fulfillment_order_id === fulfillmentOrder.id) ?? null;
+  const tracking = parcelRefs.find((ref) => ref.order_id === fulfillmentOrder.order_id && ref.active) ?? null;
+
+  return {
+    fulfillmentOrderId: fulfillmentOrder.id,
+    status: fulfillmentOrder.status,
+    providerKind: trackingReferences[0]?.providerKind ?? fulfillmentOrder.provider_kind ?? null,
+    latestOperationType: latestOperation?.operation_type ?? null,
+    latestOperationAt: latestOperation?.occurred_at ?? null,
+    providerTrackingId: trackingReferences[0]?.trackingNumber ?? tracking?.provider_tracking_id ?? null,
+    trackingUrl: trackingReferences[0]?.trackingUrl ?? null,
+    carrierKind: trackingReferences[0]?.carrierKind ?? null,
+    service: trackingReferences[0]?.service ?? null,
+    trackingReferences,
+    trackingTimeline,
+    providerEvidence,
+  };
+}
+
+export function deriveOmsCustomerFulfillmentStep(
+  orderStatus: string | null | undefined,
+  fulfillment: OmsOrderDetail["fulfillment"],
+  deliveredAt?: string | null,
+  releasedProviderExceptionHolds: OmsReleasedProviderExceptionHoldRow[] = [],
+  providerStatusEvidence: OmsProviderStatusEvidenceRow[] = [],
+  activeHoldCount = 0,
+  projections?: OmsReadModelProjections,
+): CustomerFulfillmentStep {
+  if (activeHoldCount > 0) return "exception";
+  const recovery = resolveProviderExceptionRecovery({
+    automaticHoldSource: projections?.automaticExceptionHoldSource,
+    automaticReleaseSource: projections?.automaticExceptionReleaseSource,
+    fulfillmentOrderId: fulfillment.fulfillmentOrderId,
+    releasedHolds: releasedProviderExceptionHolds.map(toReleasedProviderExceptionHold),
+    statusEvidence: providerStatusEvidence.map((row) => ({
+      id: row.id,
+      fulfillmentOrderId: row.fulfillment_order_id,
+      providerStatus: row.provider_status,
+      localStatus: row.local_status,
+      occurredAt: row.occurred_at,
+      token: customerSafeEvidenceToken(row.local_status, row.provider_status),
+    })),
+  });
+  return customerStepFromTimedSignals(
+    [orderStatus, fulfillment.status],
+    [
+      ...(deliveredAt ? [{ token: "delivered", occurredAt: deliveredAt }] : []),
+      ...providerStatusEvidence
+        .filter((row) => row.fulfillment_order_id === fulfillment.fulfillmentOrderId)
+        .map((row) => ({
+          id: row.id,
+          token: customerSafeEvidenceToken(row.local_status, row.provider_status),
+          occurredAt: row.occurred_at,
+        })),
+      ...fulfillment.trackingTimeline
+        .filter((event) => event.source === "fulfillment")
+        .map((event) => ({
+          token: event.eventType,
+          occurredAt: event.occurredAt,
+        })),
+    ],
+    recovery,
+  );
+}
+
+function toReleasedProviderExceptionHold(
+  row: OmsReleasedProviderExceptionHoldRow,
+): ReleasedProviderExceptionHold {
+  return {
+    orderId: row.order_id,
+    status: row.status ?? null,
+    reason: row.reason ?? null,
+    createdBy: row.created_by ?? null,
+    releasedBy: row.released_by ?? null,
+    metadata: row.metadata,
+  };
+}
+
+/** Resolve the same canonical step as the customer timeline, without choosing
+ * a locale. Hosts supply presentation through the existing projection; the
+ * neutral default is the step key, with the generic fallback for unknown tokens.
+ * This is not another status-to-label table. */
+function labelForOperation(operationType: string, projections?: OmsReadModelProjections): string {
+  const step = stepForToken(operationType);
+  return projections?.timelineLabel?.(step) ?? step ?? "Delivery status updated";
+}
+
+function sourceForEvidenceKind(kind: string | null | undefined): "webhook" | "reconciliation" | "provider" {
+  if (kind === "webhook") return "webhook";
+  if (kind === "reconciliation") return "reconciliation";
+  return "provider";
+}
+
+// Shared with the two sibling read-model modules that sorted the same evidence
+// rows through a byte-identical private copy of this function. Not merged with
+// omsAccountingVisibility's `timestampOrNull`: that one answers null for a
+// missing instant so the outbox comparator can rank "unknown" apart from the
+// epoch, which this zero-defaulting sort must not do.
+export function parseTimestampOrZero(value: string | null | undefined): number {
+  return value ? Date.parse(value) || 0 : 0;
+}

package/src/commerce/model/omsListTotals.ts

@@ -0,0 +1,38 @@
+import type { AdminCommerceOrdersListResponse } from "../oms/omsContracts.js";
+import { neutralOmsCurrencyPolicy,type OmsCurrencyPolicy } from "./omsCurrency.js";
+
+/**
+ * A paid set that spans more than one currency has no single GMV and no single
+ * average order value. Adding the minor units across currencies produces a
+ * figure that is money in none of them, and labelling it with one of the codes
+ * makes it look actionable. The operator gets a named refusal instead.
+ */
+export class CommerceOmsMixedCurrencyTotalsError extends Error {
+  readonly currencies: readonly string[];
+
+  constructor(currencies: readonly string[]) {
+    super("commerce_oms_summary_mixed_currency");
+    this.name = "CommerceOmsMixedCurrencyTotalsError";
+    this.currencies = currencies;
+  }
+}
+
+export function summarizeOmsListTotals(
+  orders: AdminCommerceOrdersListResponse["orders"],
+  policy: OmsCurrencyPolicy = neutralOmsCurrencyPolicy,
+): AdminCommerceOrdersListResponse["summaryTotals"] {
+  const paidOrders = orders.filter((order) => order.paymentStatus === "succeeded");
+  const currencies = [...new Set(paidOrders.map((order) => order.total.currency))].sort();
+  if (currencies.length > 1) throw new CommerceOmsMixedCurrencyTotalsError(currencies);
+  const amountMinor = paidOrders.reduce((sum, order) => sum + order.total.amountMinor, 0);
+  const orderCount = paidOrders.length;
+  // No paid order means no order named a currency, so the platform default is
+  // the only honest label for a zero total - and it is read from one module.
+  const currency = currencies[0] ?? policy.defaultCurrency;
+  return {
+    gmv: { amountMinor, currency },
+    aov: { amountMinor: orderCount > 0 ? Math.round(amountMinor / orderCount) : 0, currency },
+    orderCount,
+    paidSubscriptionCycleCount: paidOrders.filter((order) => order.mode === "subscription_cycle").length,
+  };
+}

package/src/commerce/model/omsOperationalLadder.ts

@@ -0,0 +1,181 @@
+import type { OmsOperationalLadderInput,OmsOperationalRung } from "../contracts/omsTypes.js";
+import type {
+AdminOmsAttentionReason,
+AdminOmsNextAction
+} from "../oms/omsContracts.js";
+export type { OmsOperationalLadderInput,OmsOperationalRung } from "../contracts/omsTypes.js";
+
+/**
+ * The operator attention/next-action ladder, declared once.
+ *
+ * The same ladder is implemented a second time in SQL, inside the live queue
+ * RPC `public.commerce_oms_admin_list_queue`
+ * (the live queue migration `20260903190000_oms_queue_hides_withdrawn_checkout_rows`,
+ * the `operational` CTE and the `attention_priority_desc` rank arm). Both run on
+ * the same admin request: SQL decides which orders are selected, what the
+ * summary counters say and in what order the rows arrive; this module labels the
+ * rows that come back. Nothing in the type system makes them agree.
+ *
+ * So the agreement is written down instead: every rung carries the live SQL
+ * CASE-arm condition it mirrors, verbatim modulo whitespace, and
+ * `omsOperationalLadder.test.ts` parses those arms out of the migration and
+ * compares them rung for rung, in order. Editing one side without the other
+ * turns that test red, which is the only thing standing between the two
+ * implementations and a silent divergence.
+ *
+ * ⛔ Changing a rung here is a behaviour change to the OMS queue. It must be
+ * made on both sides in the same change, or not at all.
+ */
+
+/** The facts the ladder reads. Flat on purpose: it is the join between the row
+ * shapes this codebase carries and the columns the SQL `operational` CTE has. */
+
+export const OMS_OPERATIONAL_LADDER: readonly OmsOperationalRung[] = [
+  {
+    id: "terminal_order",
+    sqlPredicate: "order_status IN ('refunded', 'cancelled')",
+    attentionReason: "none",
+    nextAction: "none",
+    // A refunded/cancelled order is done, even though its payment_status is no
+    // longer 'succeeded'. Without this rung the payment rung below would flag
+    // every refunded order as needing payment review.
+    matches: (input) => input.orderStatus === "refunded" || input.orderStatus === "cancelled",
+  },
+  {
+    id: "active_hold",
+    sqlPredicate: "active_hold_count > 0",
+    attentionReason: "active_hold",
+    nextAction: "release_hold",
+    matches: (input) => input.activeHoldCount > 0,
+  },
+  {
+    id: "payment_not_succeeded",
+    sqlPredicate: "payment_status <> 'succeeded'",
+    attentionReason: "payment_required",
+    nextAction: "review_payment",
+    matches: (input) => input.paymentStatus !== "succeeded",
+  },
+  {
+    id: "missing_shipping_address",
+    sqlPredicate:
+      "EXISTS ( SELECT 1 FROM base_orders orders WHERE orders.id = derived.id AND orders.shipping_address_id IS NULL )",
+    attentionReason: "missing_shipping_address",
+    nextAction: "review_address",
+    matches: (input) => !input.hasShippingAddress,
+  },
+  {
+    id: "inventory_not_held",
+    sqlPredicate: "inventory_status NOT IN ('reserved', 'consumed')",
+    attentionReason: "inventory_missing",
+    nextAction: "review_inventory",
+    matches: (input) => input.inventoryStatus !== "reserved" && input.inventoryStatus !== "consumed",
+  },
+  {
+    id: "fulfillment_absent_and_blocked",
+    sqlPredicate: "fulfillment_status IS NULL AND fulfillment_allowed = false",
+    attentionReason: "fulfillment_blocked",
+    nextAction: "review_fulfillment",
+    matches: (input) => !input.fulfillmentStatus && !input.fulfillmentAllowed,
+  },
+  {
+    id: "fulfillment_absent",
+    sqlPredicate: "fulfillment_status IS NULL",
+    attentionReason: "fulfillment_pending",
+    nextAction: "create_fulfillment",
+    matches: (input) => !input.fulfillmentStatus,
+  },
+  {
+    id: "fulfillment_before_label",
+    sqlPredicate: "fulfillment_status IN ('created', 'packed', 'label_pending')",
+    attentionReason: "fulfillment_pending",
+    nextAction: "record_label",
+    matches: (input) =>
+      input.fulfillmentStatus === "created" ||
+      input.fulfillmentStatus === "packed" ||
+      input.fulfillmentStatus === "label_pending",
+  },
+  {
+    id: "fulfillment_label_created",
+    sqlPredicate: "fulfillment_status = 'label_created'",
+    attentionReason: "fulfillment_pending",
+    nextAction: "hand_off",
+    matches: (input) => input.fulfillmentStatus === "label_created",
+  },
+  {
+    id: "fulfillment_exception",
+    sqlPredicate: "fulfillment_status = 'exception'",
+    attentionReason: "fulfillment_exception",
+    nextAction: "review_tracking",
+    matches: (input) => input.fulfillmentStatus === "exception",
+  },
+  // The three accounting rungs carry three distinct attention reasons but one
+  // shared next action. The SQL next-action ladder therefore collapses them into
+  // a single arm over the union of their literals; the parity test asserts that
+  // collapse explicitly rather than letting the arm counts differ unremarked.
+  {
+    id: "accounting_missing",
+    sqlPredicate: "accounting_status = 'missing'",
+    attentionReason: "invoice_missing",
+    nextAction: "review_invoice",
+    matches: (input) => input.accountingStatus === "missing",
+  },
+  {
+    id: "accounting_blocked",
+    sqlPredicate: "accounting_status = 'blocked'",
+    attentionReason: "invoice_buyer_data_invalid",
+    nextAction: "review_invoice",
+    matches: (input) => input.accountingStatus === "blocked",
+  },
+  {
+    id: "accounting_issue_failed",
+    sqlPredicate: "accounting_status IN ('rejected', 'outbox_failed')",
+    attentionReason: "invoice_issue_failed",
+    nextAction: "review_invoice",
+    matches: (input) => input.accountingStatus === "rejected" || input.accountingStatus === "outbox_failed",
+  },
+];
+
+/** The `ELSE` of both SQL CASE expressions, and the fall-through of the loop. */
+export const OMS_OPERATIONAL_LADDER_FALLBACK: {
+  readonly attentionReason: AdminOmsAttentionReason;
+  readonly nextAction: AdminOmsNextAction;
+} = { attentionReason: "none", nextAction: "none" };
+
+/**
+ * The `attention_priority_desc` sort ranks, in SQL arm order. Lower sorts first.
+ *
+ * Nothing in TypeScript consumes this today - the queue arrives pre-sorted from
+ * SQL, and the fixture bundle does not offer that sort. It is declared here
+ * because the ranking is part of the same ladder: an attention reason added
+ * above without a rank silently sorts to the bottom of the operator's queue.
+ * The parity test binds it to the live migration arm for arm.
+ */
+export const OMS_ATTENTION_PRIORITY_LADDER: readonly {
+  readonly attentionReason: AdminOmsAttentionReason;
+  readonly rank: number;
+}[] = [
+  { attentionReason: "active_hold", rank: 1 },
+  { attentionReason: "payment_required", rank: 2 },
+  { attentionReason: "missing_shipping_address", rank: 3 },
+  { attentionReason: "inventory_missing", rank: 4 },
+  { attentionReason: "fulfillment_blocked", rank: 5 },
+  { attentionReason: "fulfillment_exception", rank: 6 },
+  { attentionReason: "invoice_issue_failed", rank: 7 },
+  { attentionReason: "invoice_buyer_data_invalid", rank: 8 },
+  { attentionReason: "invoice_missing", rank: 9 },
+  // Deliberately the same rank as invoice_missing in the live body.
+  { attentionReason: "fulfillment_pending", rank: 9 },
+];
+
+export const OMS_ATTENTION_PRIORITY_FALLBACK_RANK = 99;
+
+/** Walks the ladder once and returns the first rung that matches. */
+export function resolveOmsOperationalState(input: OmsOperationalLadderInput): {
+  attentionReason: AdminOmsAttentionReason;
+  nextAction: AdminOmsNextAction;
+} {
+  for (const rung of OMS_OPERATIONAL_LADDER) {
+    if (rung.matches(input)) return { attentionReason: rung.attentionReason, nextAction: rung.nextAction };
+  }
+  return { ...OMS_OPERATIONAL_LADDER_FALLBACK };
+}

package/src/commerce/model/omsOrderLineMoney.ts

@@ -0,0 +1,34 @@
+import type { OmsOrderDetail } from "../oms/omsContracts.js";
+import type { OmsOrderItemRow } from "./omsReadModelRows.js";
+import type { CanonicalOrderMoneyLine } from "../orderMoney.js";
+
+export function mapOmsOrderLine(
+  item: OmsOrderItemRow,
+  currency: OmsOrderDetail["total"]["currency"],
+  moneyLine: CanonicalOrderMoneyLine,
+): OmsOrderDetail["lines"][number] {
+  const productSnapshot = item.product_snapshot ?? {};
+  const variantSnapshot = item.variant_snapshot ?? null;
+  return {
+    id: item.id,
+    skuId: item.sku_id ?? null,
+    sku: item.sku ?? readSnapshotText(productSnapshot, "sku"),
+    title: item.title
+      ?? readSnapshotText(productSnapshot, "title")
+      ?? readSnapshotText(productSnapshot, "name"),
+    quantity: item.quantity,
+    unitPrice: { amountMinor: moneyLine.catalogUnit, currency },
+    total: { amountMinor: moneyLine.catalogTotal, currency },
+    discountAllocated: { amountMinor: moneyLine.discountAllocated, currency },
+    effectiveTotal: { amountMinor: moneyLine.effectiveGross, currency },
+    effectiveNet: { amountMinor: moneyLine.effectiveNet, currency },
+    vatRateBps: moneyLine.vatRateBps,
+    productSnapshot,
+    variantSnapshot,
+  };
+}
+
+function readSnapshotText(snapshot: Record<string, unknown>, key: string): string | null {
+  const value = snapshot[key];
+  return typeof value === "string" && value.trim() ? value : null;
+}

package/src/commerce/model/omsPaymentMethodSummary.ts

@@ -0,0 +1,19 @@
+import type { OmsPaymentMethodSummary } from "../contracts/omsTypes.js";
+import type { OmsReadModelProjections } from "./omsReadModelProjections.js";
+import type { OmsPaymentAttemptRow,OmsPaymentIntentRow } from "./omsReadModelRows.js";
+export type { OmsPaymentMethodSummary } from "../contracts/omsTypes.js";
+
+export function paymentMethodForOrder(
+  orderId: string,
+  paymentIntents: OmsPaymentIntentRow[],
+  paymentAttempts: OmsPaymentAttemptRow[],
+  projections?: OmsReadModelProjections,
+): OmsPaymentMethodSummary {
+  const intent = paymentIntents.find((candidate) => candidate.id && candidate.order_id === orderId) ?? null;
+  if (!intent) return { provider: null, label: null };
+  const attempt = paymentAttempts.find((candidate) => candidate.id === intent.active_attempt_id)
+    ?? paymentAttempts.find((candidate) => candidate.payment_intent_id === intent.id)
+    ?? null;
+  if (!attempt) return { provider: null, label: null };
+  return { provider: attempt.provider, label: projections?.paymentMethodLabel?.(attempt) ?? attempt.provider };
+}