@final-commerce/command-frame 0.9.0-preprod.3 → 0.9.0-preprod.4

package/dist/actions/get-order-statuses/types.d.ts

@@ -1,7 +1,7 @@
 import type { CFOrderStatusDefinition } from '../../common-types/order-state';
 export interface GetOrderStatusesResponse {
     success: boolean;
-    /** The company's order statuses, in the order they were defined. Empty when none are defined. */
+    /** The running flow's order statuses, in the order they were defined. Empty when it defines none. */
     statuses: CFOrderStatusDefinition[];
     timestamp: string;
 }

package/dist/actions/get-orders/mock.js

@@ -5,7 +5,7 @@ export const mockGetOrders = async (params) => {
     let orders = safeSerialize([...MOCK_ORDERS, ...MOCK_PARKED_ORDERS]);
     // Filter simulation
     if (params) {
-        const { customerId, status, sessionId, paymentState, fulfillmentState, outletId, assignedUserId, inCart, orderType, customStatusId, scheduled, scheduledFrom, scheduledTo, searchValue, limit, offset, sortBy, sortDirection, } = params;
+        const { customerId, status, sessionId, paymentState, fulfillmentState, outletId, assignedUserId, inCart, orderType, customStatusId, customStatusKey, scheduled, scheduledFrom, scheduledTo, searchValue, limit, offset, sortBy, sortDirection, } = params;
         // 1. Filtering
         if (customerId) {
             orders = orders.filter((o) => o.customer && '_id' in o.customer && o.customer._id === customerId);
@@ -38,10 +38,17 @@ export const mockGetOrders = async (params) => {
             if (types.length)
                 orders = orders.filter((o) => types.includes(o.orderType ?? ''));
         }
+        if (customStatusKey !== undefined) {
+            const keys = Array.isArray(customStatusKey) ? customStatusKey : [customStatusKey];
+            if (keys.length)
+                orders = orders.filter((o) => !!o.customStatus?.key && keys.includes(o.customStatus.key));
+        }
         if (customStatusId !== undefined) {
             const ids = Array.isArray(customStatusId) ? customStatusId : [customStatusId];
-            if (ids.length)
-                orders = orders.filter((o) => !!o.customStatus && ids.includes(o.customStatus.id));
+            if (ids.length) {
+                orders = orders.filter((o) => !!o.customStatus &&
+                    (ids.includes(o.customStatus.id) || (!!o.customStatus.key && ids.includes(o.customStatus.key))));
+            }
         }
         // Requested time (setScheduledFor). ISO strings in UTC compare correctly as strings.
         const scheduledOf = (o) => o.scheduledFor ?? null;

package/dist/actions/get-orders/types.d.ts

@@ -22,7 +22,12 @@ export interface GetOrdersParams {
     inCart?: boolean;
     /** Order type label(s) set with setOrderType, e.g. 'delivery' or ['pickup', 'takeout']. Exact match; a list matches any. */
     orderType?: string | string[];
-    /** Custom status id(s) set with setOrderStatus, e.g. 'in-kitchen'. A list matches any of them. */
+    /** Custom status key(s) set with setOrderStatus, e.g. 'in-kitchen'. A list matches any of them. */
+    customStatusKey?: string | string[];
+    /**
+     * Durable custom status id(s) (getOrderStatuses `id`). Also matches a status's key, for
+     * flows written before keys — prefer `customStatusKey`. A list matches any of them.
+     */
     customStatusId?: string | string[];
     /** true: only orders with a time (setScheduledFor); false: only "as soon as possible" orders (no time). */
     scheduled?: boolean;

package/dist/actions/set-order-status/mock.js

@@ -10,20 +10,25 @@ export const mockSetOrderStatus = async (params) => {
         throw new Error(`Order with ID ${params.orderId} not found`);
     }
     const from = { payment: order.paymentState ?? 'unpaid', fulfillment: order.fulfillmentState ?? 'draft' };
-    if (params.statusId === null) {
+    const requested = params.key !== undefined ? params.key : params.statusId;
+    if (requested === undefined) {
+        throw new Error('setOrderStatus: pass a status key, or null to clear the status');
+    }
+    if (requested === null) {
         order.customStatus = null;
     }
     else {
-        const def = MOCK_ORDER_STATUSES.find((s) => s.id === params.statusId);
+        const def = MOCK_ORDER_STATUSES.find((s) => s.key === requested) ??
+            (params.key === undefined ? MOCK_ORDER_STATUSES.find((s) => s.id === requested) : undefined);
         if (!def) {
-            throw new Error(`setOrderStatus: unknown status "${params.statusId}"`);
+            throw new Error(`setOrderStatus: unknown status "${requested}"`);
         }
         if (def.requiresPaymentState && !def.requiresPaymentState.includes(from.payment)) {
             throw new Error(`setOrderStatus: "${def.label}" requires payment state ${def.requiresPaymentState.join(' or ')} (order is ${from.payment})`);
         }
         if (def.fulfillmentState)
             order.fulfillmentState = def.fulfillmentState;
-        order.customStatus = { id: def.id, label: def.label, setAt: new Date().toISOString(), setBy: null };
+        order.customStatus = { id: def.id, key: def.key, label: def.label, setAt: new Date().toISOString(), setBy: null };
     }
     mockPublishEvent('orders', 'order-updated', { order });
     const to = { payment: order.paymentState ?? 'unpaid', fulfillment: order.fulfillmentState ?? 'draft' };

package/dist/actions/set-order-status/types.d.ts

@@ -3,8 +3,13 @@ import type { CFStatePair } from '../../common-types/order-state';
 export interface SetOrderStatusParams {
     /** Order to set the status on. Omit for the live cart's order. */
     orderId?: string;
-    /** Id of one of the company's statuses (see getOrderStatuses), or null to clear the status. */
-    statusId: string | null;
+    /** Key of one of the flow's statuses (see getOrderStatuses), or null to clear the status. */
+    key?: string | null;
+    /**
+     * @deprecated Use `key`. Kept for flows written before keys: matched against a status's
+     * key, then its id. Ignored when `key` is given.
+     */
+    statusId?: string | null;
 }
 export interface SetOrderStatusResponse {
     success: boolean;

package/dist/common-types/order-state.d.ts

@@ -31,13 +31,18 @@ export interface CFAvailableTransition {
     conditions: CFConditionStatus[];
 }
 /**
- * A merchant-defined order status (per company). Mirrors common's OrderStatusDefinition.
- * `fulfillmentState`: setting the status moves the order there (normal state-machine
- * rules). `requiresPaymentState`: setting it fails unless the order's payment state is
- * one of these — a status never moves money. Neither set = a label-only status.
+ * An order status the running flow defines (authored in the flow builder, shipped with
+ * each deployed version). `fulfillmentState`: setting the status moves the order there
+ * (normal state-machine rules). `requiresPaymentState`: setting it fails unless the
+ * order's payment state is one of these — a status never moves money. Neither set = a
+ * label-only status.
  */
 export interface CFOrderStatusDefinition {
+    /** Durable id; survives a renamed key or label. */
     id: string;
+    /** What flow code passes to setOrderStatus and getOrders({ customStatusKey }), e.g. 'in-kitchen'. */
+    key: string;
+    /** What staff see. */
     label: string;
     color?: string;
     icon?: string;

package/dist/demo/database.d.ts

@@ -77,7 +77,7 @@ export declare let MOCK_ACTIVE_PRODUCT: CFActiveProduct;
 export declare const setMockActiveProduct: (activeProduct: CFActiveProduct) => void;
 export declare const MOCK_SMART_GRID_LAYOUTS: Record<string, CFSmartGridLayout>;
 export declare const resetMockCart: () => void;
-/** The demo company's order statuses (getOrderStatuses / setOrderStatus). */
+/** The demo flow's order statuses (getOrderStatuses / setOrderStatus). */
 export declare const MOCK_ORDER_STATUSES: CFOrderStatusDefinition[];
 /**
  * Replace in-memory mock data used by default mock handlers. Arrays are mutated in place

package/dist/demo/database.js

@@ -722,13 +722,31 @@ function resolveMockOrderCurrency() {
     }
     return CurrencyCode.USD;
 }
-/** The demo company's order statuses (getOrderStatuses / setOrderStatus). */
+/** The demo flow's order statuses (getOrderStatuses / setOrderStatus). */
 export const MOCK_ORDER_STATUSES = [
-    { id: 'in-kitchen', label: 'In kitchen', color: '#f59e0b', fulfillmentState: 'pending' },
-    { id: 'ready-for-pickup', label: 'Ready for pickup', color: '#10b981', fulfillmentState: 'in_progress' },
-    { id: 'out-for-delivery', label: 'Out for delivery', color: '#3b82f6', fulfillmentState: 'partially_fulfilled' },
-    { id: 'delivered', label: 'Delivered', fulfillmentState: 'fulfilled', requiresPaymentState: ['paid'] },
-    { id: 'driver-called', label: 'Driver called' },
+    { id: 'status_1', key: 'in-kitchen', label: 'In kitchen', color: '#f59e0b', fulfillmentState: 'pending' },
+    {
+        id: 'status_2',
+        key: 'ready-for-pickup',
+        label: 'Ready for pickup',
+        color: '#10b981',
+        fulfillmentState: 'in_progress',
+    },
+    {
+        id: 'status_3',
+        key: 'out-for-delivery',
+        label: 'Out for delivery',
+        color: '#3b82f6',
+        fulfillmentState: 'partially_fulfilled',
+    },
+    {
+        id: 'status_4',
+        key: 'delivered',
+        label: 'Delivered',
+        fulfillmentState: 'fulfilled',
+        requiresPaymentState: ['paid'],
+    },
+    { id: 'status_5', key: 'driver-called', label: 'Driver called' },
 ];
 /**
  * Replace in-memory mock data used by default mock handlers. Arrays are mutated in place

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.9.0-preprod.3",
+  "version": "0.9.0-preprod.4",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -57,7 +57,7 @@
     "ignoreBranchesMissingTickets": true
   },
   "dependencies": {
-    "@final-commerce/common": "2.5.1-preprod.6"
+    "@final-commerce/common": "2.5.1-preprod.8"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.0.0",