@final-commerce/common 2.2.0-beta.2 → 2.2.0-staging.2

package/dist/index.d.mts

@@ -189,7 +189,8 @@ declare enum Platform {
 }
 declare enum OrderPlatform {
     POS = "in-store",
-    WOO_COMMERCE = "woo-commerce"
+    WOO_COMMERCE = "woo-commerce",
+    PUBLIC_API = "public-api"
 }
 declare enum CustomerPlatform {
     POS = "in-store",
@@ -1030,6 +1031,40 @@ declare function setOrderState(order: OrderStateWritable, paymentState: PaymentS
 
 declare function inferStatesFromLegacyStatus(order: OrderLikeForLegacyInference): StatePair;
 
+interface OrderMutationData extends OrderStateWritable {
+    total?: number;
+    balance?: number;
+    paymentMethods?: {
+        amount?: number;
+        [key: string]: unknown;
+    }[];
+    refunds?: {
+        quantity?: number;
+        [key: string]: unknown;
+    }[];
+    refund?: {
+        quantity?: number;
+        [key: string]: unknown;
+    }[];
+    lineItems?: {
+        quantity?: number;
+        fulfilledQuantity?: number;
+        returnedQuantity?: number;
+        [key: string]: unknown;
+    }[];
+}
+interface OrderWriteStrategy {
+    applyState(order: OrderMutationData): void;
+}
+declare class LegacyWriteStrategy implements OrderWriteStrategy {
+    applyState(_order: OrderMutationData): void;
+}
+declare class DualWriteStrategy implements OrderWriteStrategy {
+    private readonly config;
+    constructor(config: StoredStateConfig);
+    applyState(order: OrderMutationData): void;
+}
+
 interface ResolveTemplateResult {
     fragment: StateConfigFragment;
     resolvedValues: Record<string, unknown>;
@@ -1145,40 +1180,6 @@ interface ConfigUpdatedPayload {
 }
 type OrderStateEventPayload = StateTransitionCompletedPayload | StateTransitionBlockedPayload | ConfigUpdatedPayload;
 
-interface OrderMutationData extends OrderStateWritable {
-    total?: number;
-    balance?: number;
-    paymentMethods?: {
-        amount?: number;
-        [key: string]: unknown;
-    }[];
-    refunds?: {
-        quantity?: number;
-        [key: string]: unknown;
-    }[];
-    refund?: {
-        quantity?: number;
-        [key: string]: unknown;
-    }[];
-    lineItems?: {
-        quantity?: number;
-        fulfilledQuantity?: number;
-        returnedQuantity?: number;
-        [key: string]: unknown;
-    }[];
-}
-interface OrderWriteStrategy {
-    applyState(order: OrderMutationData): void;
-}
-declare class LegacyWriteStrategy implements OrderWriteStrategy {
-    applyState(_order: OrderMutationData): void;
-}
-declare class DualWriteStrategy implements OrderWriteStrategy {
-    private readonly config;
-    constructor(config: StoredStateConfig);
-    applyState(order: OrderMutationData): void;
-}
-
 interface CurrencyRate {
     rate: number;
     country: string;

package/dist/index.d.ts

@@ -189,7 +189,8 @@ declare enum Platform {
 }
 declare enum OrderPlatform {
     POS = "in-store",
-    WOO_COMMERCE = "woo-commerce"
+    WOO_COMMERCE = "woo-commerce",
+    PUBLIC_API = "public-api"
 }
 declare enum CustomerPlatform {
     POS = "in-store",
@@ -1030,6 +1031,40 @@ declare function setOrderState(order: OrderStateWritable, paymentState: PaymentS
 
 declare function inferStatesFromLegacyStatus(order: OrderLikeForLegacyInference): StatePair;
 
+interface OrderMutationData extends OrderStateWritable {
+    total?: number;
+    balance?: number;
+    paymentMethods?: {
+        amount?: number;
+        [key: string]: unknown;
+    }[];
+    refunds?: {
+        quantity?: number;
+        [key: string]: unknown;
+    }[];
+    refund?: {
+        quantity?: number;
+        [key: string]: unknown;
+    }[];
+    lineItems?: {
+        quantity?: number;
+        fulfilledQuantity?: number;
+        returnedQuantity?: number;
+        [key: string]: unknown;
+    }[];
+}
+interface OrderWriteStrategy {
+    applyState(order: OrderMutationData): void;
+}
+declare class LegacyWriteStrategy implements OrderWriteStrategy {
+    applyState(_order: OrderMutationData): void;
+}
+declare class DualWriteStrategy implements OrderWriteStrategy {
+    private readonly config;
+    constructor(config: StoredStateConfig);
+    applyState(order: OrderMutationData): void;
+}
+
 interface ResolveTemplateResult {
     fragment: StateConfigFragment;
     resolvedValues: Record<string, unknown>;
@@ -1145,40 +1180,6 @@ interface ConfigUpdatedPayload {
 }
 type OrderStateEventPayload = StateTransitionCompletedPayload | StateTransitionBlockedPayload | ConfigUpdatedPayload;
 
-interface OrderMutationData extends OrderStateWritable {
-    total?: number;
-    balance?: number;
-    paymentMethods?: {
-        amount?: number;
-        [key: string]: unknown;
-    }[];
-    refunds?: {
-        quantity?: number;
-        [key: string]: unknown;
-    }[];
-    refund?: {
-        quantity?: number;
-        [key: string]: unknown;
-    }[];
-    lineItems?: {
-        quantity?: number;
-        fulfilledQuantity?: number;
-        returnedQuantity?: number;
-        [key: string]: unknown;
-    }[];
-}
-interface OrderWriteStrategy {
-    applyState(order: OrderMutationData): void;
-}
-declare class LegacyWriteStrategy implements OrderWriteStrategy {
-    applyState(_order: OrderMutationData): void;
-}
-declare class DualWriteStrategy implements OrderWriteStrategy {
-    private readonly config;
-    constructor(config: StoredStateConfig);
-    applyState(order: OrderMutationData): void;
-}
-
 interface CurrencyRate {
     rate: number;
     country: string;

package/dist/index.js

@@ -369,6 +369,7 @@ var Platform = /* @__PURE__ */ ((Platform2) => {
 var OrderPlatform = /* @__PURE__ */ ((OrderPlatform2) => {
   OrderPlatform2["POS"] = "in-store";
   OrderPlatform2["WOO_COMMERCE"] = "woo-commerce";
+  OrderPlatform2["PUBLIC_API"] = "public-api";
   return OrderPlatform2;
 })(OrderPlatform || {});
 var CustomerPlatform = /* @__PURE__ */ ((CustomerPlatform2) => {
@@ -1446,10 +1447,7 @@ function negateAtPaths(value, path, paths) {
 function padHex(value, length) {
   return value.toString(16).padStart(length, "0");
 }
-var PROCESS_RANDOM = Array.from(
-  { length: 5 },
-  () => padHex(Math.floor(Math.random() * 256), 2)
-).join("");
+var PROCESS_RANDOM = Array.from({ length: 5 }, () => padHex(Math.floor(Math.random() * 256), 2)).join("");
 var objectIdCounter = Math.floor(Math.random() * 16777215);
 function generateMongoID() {
   const timestamp = padHex(Math.floor(Date.now() / 1e3), 8);
@@ -1594,6 +1592,8 @@ var STATE_SCHEMA = Object.freeze({
 // order-state-machine/financial-invariants.ts
 var REFUND_ALLOWED_FULFILLMENT = /* @__PURE__ */ new Set(["fulfilled", "returned", "partially_returned", "cancelled"]);
 var PAYMENT_COLLECTION_ORDER = ["unpaid", "partially_paid", "paid"];
+var UNRETURNED_MONEY_STATES = /* @__PURE__ */ new Set(["partially_paid", "paid", "partially_refunded"]);
+var REFUNDED_FULFILLMENT_LANDINGS = /* @__PURE__ */ new Set(["returned", "cancelled"]);
 var FINANCIAL_INVARIANTS = [
   {
     id: "no-leave-refunded",
@@ -1624,6 +1624,26 @@ var FINANCIAL_INVARIANTS = [
       const toIdx = PAYMENT_COLLECTION_ORDER.indexOf(to.payment);
       return fromIdx !== -1 && toIdx !== -1 && fromIdx > toIdx;
     }
+  },
+  {
+    id: "no-cancel-with-unreturned-payments",
+    description: "Fulfillment cannot enter cancelled while the payment state carries unreturned captured money (paid / partially_paid / partially_refunded) \u2014 return the money first: a full refund of an unfulfilled order lands refunded \xD7 cancelled, a void lands voided \xD7 cancelled. Scoped to the cancelling MOVE (from.fulfillment !== cancelled) so payment-axis edges evaluated against an already-cancelled fulfillment do not trip it",
+    check: (from, to) => from !== null && from.fulfillment !== "cancelled" && to.fulfillment === "cancelled" && UNRETURNED_MONEY_STATES.has(to.payment)
+  },
+  {
+    id: "no-draft-regression-with-captured-payments",
+    description: "Fulfillment cannot regress to draft once money has been captured \u2014 a money-carrying order is no longer a cart (bug #31: resume lands deposit orders on in_progress for the same reason). New orders and draft-to-draft moves are exempt, so partially_paid \xD7 draft remains declarable as an initial state",
+    check: (from, to) => from !== null && from.fulfillment !== "draft" && to.fulfillment === "draft" && to.payment !== "unpaid"
+  },
+  {
+    id: "no-reopen-voided-fulfillment",
+    description: "A voided order exists only at cancelled fulfillment: a voided order cannot re-enter fulfillment, and a voided \xD7 non-cancelled pair cannot be materialized from nothing (complements no-leave-voided, which only freezes the payment axis). Moves INTO voided from a live payment state are the void flow\u2019s concern, not this rule\u2019s",
+    check: (from, to) => (from === null || from.payment === "voided") && to.payment === "voided" && to.fulfillment !== "cancelled"
+  },
+  {
+    id: "no-reopen-refunded-fulfillment",
+    description: "A fully refunded order cannot re-enter fulfillment \u2014 it may only relabel between its canonical landings, returned and cancelled (complements no-leave-refunded, which only freezes the payment axis)",
+    check: (from, to) => from?.payment === "refunded" && !REFUNDED_FULFILLMENT_LANDINGS.has(to.fulfillment)
   }
 ];
 function getFinancialInvariantViolations(from, to) {
@@ -1711,24 +1731,17 @@ var DISPLAY_LABEL_OVERRIDES = {
   "paid|on_hold": "Parked - Paid",
   "paid|fulfilled": "Completed",
   "partially_refunded|fulfilled": "Partially Refunded",
-  "partially_refunded|partially_returned": "Partially Refunded",
-  "refunded|fulfilled": "Refunded",
-  "refunded|returned": "Refunded",
-  // Full refund of a never-fulfilled order (kaching refund op lands on
-  // cancelled when nothing was delivered). Terminal payment states emit no
-  // generic rows, so without this the pair fell through to the raw
-  // "refunded / cancelled" engine fallback.
-  "refunded|cancelled": "Refunded",
-  "voided|cancelled": "Cancelled"
+  "partially_refunded|partially_returned": "Partially Refunded"
+};
+var TERMINAL_LABEL_OVERRIDES = {
+  voided: "Cancelled"
 };
 function buildDefaultDisplayStateMap() {
   const rules = [];
   for (const p of PAYMENT_STATES) {
+    const terminalLabel = TERMINAL_PAYMENT_STATES.has(p) ? TERMINAL_LABEL_OVERRIDES[p] ?? PAYMENT_LABELS.get(p) : void 0;
     for (const f of FULFILLMENT_STATES) {
-      const key = `${p}|${f}`;
-      const override = DISPLAY_LABEL_OVERRIDES[key];
-      if (TERMINAL_PAYMENT_STATES.has(p) && !override) continue;
-      const label = override ?? `${PAYMENT_LABELS.get(p)} / ${FULFILLMENT_LABELS.get(f)}`;
+      const label = DISPLAY_LABEL_OVERRIDES[`${p}|${f}`] ?? terminalLabel ?? `${PAYMENT_LABELS.get(p)} / ${FULFILLMENT_LABELS.get(f)}`;
       rules.push({ paymentState: p, fulfillmentState: f, label });
     }
   }
@@ -1851,6 +1864,9 @@ function buildOrderContext(order, extras) {
 }
 
 // order-state-machine/display-state.ts
+function atomLabel(atom, defs) {
+  return defs.find((d) => d.id === atom)?.label ?? atom;
+}
 function matchesOptional(actual, rule) {
   if (rule === void 0) return true;
   return Array.isArray(rule) ? rule.includes(actual) : rule === actual;
@@ -1861,7 +1877,9 @@ function deriveDisplayState(payment, fulfillment, config) {
       return { label: rule.label, color: rule.color, icon: rule.icon };
     }
   }
-  return { label: `${payment} / ${fulfillment}` };
+  return {
+    label: `${atomLabel(payment, STATE_SCHEMA.paymentStates)} / ${atomLabel(fulfillment, STATE_SCHEMA.fulfillmentStates)}`
+  };
 }
 function displayRuleMatchesPair(rule, payment, fulfillment) {
   return matchesOptional(payment, rule.paymentState) && matchesOptional(fulfillment, rule.fulfillmentState);
@@ -2097,13 +2115,11 @@ function labelForFulfillment(id, config) {
   return config.fulfillmentStates.find((s) => s.id === id)?.label ?? id;
 }
 function transitionDisplayLabel(to, config) {
-  const pay = labelForPayment(to.payment, config);
-  const ful = labelForFulfillment(to.fulfillment, config);
   const derived = deriveDisplayState(to.payment, to.fulfillment, config).label;
-  if (derived && derived !== `${to.payment} / ${to.fulfillment}`) {
+  if (derived) {
     return derived;
   }
-  return `${pay} \xB7 ${ful}`;
+  return `${labelForPayment(to.payment, config)} \xB7 ${labelForFulfillment(to.fulfillment, config)}`;
 }
 function conditionMetLines(config, from, to, context) {
   const lines = [];
@@ -2132,20 +2148,12 @@ function conditionMetLines(config, from, to, context) {
 }
 function getAvailableTransitions(current, config, context) {
   const candidates = [];
-  for (const s of config.paymentStates) {
-    if (s.id === current.payment) continue;
-    candidates.push({ payment: s.id, fulfillment: current.fulfillment });
-  }
   for (const s of config.fulfillmentStates) {
     if (s.id === current.fulfillment) continue;
     candidates.push({ payment: current.payment, fulfillment: s.id });
   }
   const out = [];
-  const seen = /* @__PURE__ */ new Set();
   for (const to of candidates) {
-    const key = `${to.payment}:${to.fulfillment}`;
-    if (seen.has(key)) continue;
-    seen.add(key);
     const result = canTransition({
       from: current,
       to,
@@ -2594,6 +2602,27 @@ function inferStatesFromLegacyStatus(order) {
   return { payment: "unpaid", fulfillment: "pending" };
 }
 
+// order-state-machine/write-strategy.ts
+var LegacyWriteStrategy = class {
+  applyState(_order) {
+  }
+};
+var DualWriteStrategy = class {
+  constructor(config) {
+    this.config = config;
+  }
+  applyState(order) {
+    if (order.paymentState && order.fulfillmentState) {
+      setOrderState(order, order.paymentState, order.fulfillmentState, this.config);
+      return;
+    }
+    if (order.status) {
+      const inferred = inferStatesFromLegacyStatus(order);
+      setOrderState(order, inferred.payment, inferred.fulfillment, this.config);
+    }
+  }
+};
+
 // order-state-machine/resolve-template.ts
 function resolveTemplate(templateJson, params, values = {}) {
   const resolvedValues = {};
@@ -2895,27 +2924,6 @@ var ORDER_STATE_EVENTS = {
   stateTransitionBlocked: "state-transition-blocked",
   configUpdated: "config-updated"
 };
-
-// order-state-machine/write-strategy.ts
-var LegacyWriteStrategy = class {
-  applyState(_order) {
-  }
-};
-var DualWriteStrategy = class {
-  constructor(config) {
-    this.config = config;
-  }
-  applyState(order) {
-    if (order.paymentState && order.fulfillmentState) {
-      setOrderState(order, order.paymentState, order.fulfillmentState, this.config);
-      return;
-    }
-    if (order.status) {
-      const inferred = inferStatesFromLegacyStatus(order);
-      setOrderState(order, inferred.payment, inferred.fulfillment, this.config);
-    }
-  }
-};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AttributeType,