@final-commerce/command-frame 0.10.0 → 0.11.0-preprod.1

package/dist/actions/resume-order/action.js

@@ -0,0 +1,8 @@
+/**
+ * Resume order action
+ * Calls the resumeOrder action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const resumeOrder = async (params) => {
+    return await commandFrameClient.call('resumeOrder', params);
+};

package/dist/actions/resume-order/mock.d.ts

@@ -0,0 +1,2 @@
+import type { ResumeOrder } from './types';
+export declare const mockResumeOrder: ResumeOrder;

package/dist/actions/resume-order/mock.js

@@ -0,0 +1,55 @@
+import { MOCK_ORDERS, MOCK_PARKED_ORDERS, mockPublishEvent } from '../../demo/database';
+import { restoreMockCartFromOrder } from '../resume-parked-order/mock';
+// Mirrors the host's rule (see README): anything not already in a cart and not finished.
+const BLOCKED_PAYMENT = new Set(['refunded', 'partially_refunded', 'voided', 'payment_pending']);
+const FINISHED_FULFILLMENT = new Set(['cancelled', 'returned', 'partially_returned']);
+export const mockResumeOrder = async (params) => {
+    console.log('[Mock] resumeOrder called', params);
+    const orderId = params?.orderId;
+    if (!orderId) {
+        throw new Error('Order ID is required');
+    }
+    const order = [...MOCK_PARKED_ORDERS, ...MOCK_ORDERS].find((o) => o._id === orderId);
+    if (!order) {
+        throw new Error(`Order with ID ${orderId} not found`);
+    }
+    const from = { payment: order.paymentState ?? 'unpaid', fulfillment: order.fulfillmentState ?? 'draft' };
+    const inCart = order.inCart != null ? order.inCart.active : from.fulfillment === 'draft';
+    if (inCart) {
+        throw new Error(`Order ${orderId} is already in a cart`);
+    }
+    if (BLOCKED_PAYMENT.has(from.payment) ||
+        FINISHED_FULFILLMENT.has(from.fulfillment) ||
+        (from.payment === 'paid' && from.fulfillment === 'fulfilled')) {
+        throw new Error(`Order ${orderId} cannot be resumed from ${from.payment} × ${from.fulfillment}`);
+    }
+    // Keeps the state; only parked (on_hold) / draft move.
+    const leavesParked = from.fulfillment === 'on_hold' || from.fulfillment === 'draft';
+    const to = {
+        payment: from.payment,
+        fulfillment: !leavesParked ? from.fulfillment : from.payment === 'unpaid' ? 'draft' : 'in_progress',
+    };
+    restoreMockCartFromOrder(order);
+    const parkedIndex = MOCK_PARKED_ORDERS.findIndex((o) => o._id === orderId);
+    if (parkedIndex !== -1)
+        MOCK_PARKED_ORDERS.splice(parkedIndex, 1);
+    mockPublishEvent('cart', 'cart-created', { orderId });
+    mockPublishEvent('order-state', 'state-transition-completed', {
+        orderId,
+        from,
+        to,
+        timestamp: new Date().toISOString(),
+    });
+    return {
+        success: true,
+        order: {
+            ...order,
+            paymentState: to.payment,
+            fulfillmentState: to.fulfillment,
+            inCart: { active: true, stationId: null, since: new Date().toISOString() },
+        },
+        from,
+        to,
+        timestamp: new Date().toISOString(),
+    };
+};

package/dist/actions/resume-order/types.d.ts

@@ -0,0 +1,17 @@
+import { CFOrder } from '../../CommonTypes';
+import type { CFStatePair } from '../../common-types/order-state';
+export interface ResumeOrderParams {
+    /** The order to load back into the cart. Must be open — see the README for which states resume. */
+    orderId: string;
+}
+export interface ResumeOrderResponse {
+    success: boolean;
+    /** The resumed order, re-read after the transition. */
+    order: CFOrder;
+    /** State before resuming. */
+    from: CFStatePair;
+    /** State after resuming — `draft` when nothing was paid, otherwise the order stays out of the cart states. */
+    to: CFStatePair;
+    timestamp: string;
+}
+export type ResumeOrder = (params: ResumeOrderParams) => Promise<ResumeOrderResponse>;

package/dist/actions/resume-order/types.js

@@ -0,0 +1 @@
+export {};

package/dist/actions/resume-parked-order/mock.d.ts

@@ -1,2 +1,7 @@
 import { ResumeParkedOrder } from './types';
+import type { CFActiveOrder } from '../../CommonTypes';
+/**
+ * Best-effort Order -> MOCK_CART mapping shared by the resume mocks.
+ */
+export declare const restoreMockCartFromOrder: (orderToResume: CFActiveOrder) => void;
 export declare const mockResumeParkedOrder: ResumeParkedOrder;

package/dist/actions/resume-parked-order/mock.js

@@ -1,4 +1,28 @@
 import { MOCK_PARKED_ORDERS, MOCK_CART, MOCK_PRODUCTS, resetMockCart, mockPublishEvent } from '../../demo/database';
+/**
+ * Best-effort Order -> MOCK_CART mapping shared by the resume mocks.
+ */
+export const restoreMockCartFromOrder = (orderToResume) => {
+    resetMockCart();
+    MOCK_CART.customer = orderToResume.customer; // Cast if needed
+    MOCK_CART.products = orderToResume.lineItems.map((li) => ({
+        id: li.productId,
+        name: li.name,
+        quantity: li.quantity,
+        price: li.price,
+        internalId: li.internalId || li.productId,
+        variantId: li.variantId,
+        sku: li.sku,
+        images: [li.image],
+        stock: 100,
+        taxTableId: '',
+        attributes: li.attributes,
+    }));
+    MOCK_CART.subtotal = orderToResume.summary.subtotalAfterFees;
+    MOCK_CART.total = orderToResume.summary.total;
+    MOCK_CART.amountToBeCharged = MOCK_CART.total;
+    MOCK_CART.remainingBalance = MOCK_CART.total;
+};
 export const mockResumeParkedOrder = async (params) => {
     console.log('[Mock] resumeParkedOrder called', params);
     const orderId = params?.orderId;
@@ -25,30 +49,7 @@ export const mockResumeParkedOrder = async (params) => {
         .map((li) => li.name);
     if (notSoldNames.length)
         throw new Error(`${notSoldNames.join(', ')} is not sold in POS`);
-    // Restore to MOCK_CART
-    // Logic to convert Order back to Cart (simplified)
-    resetMockCart();
-    // Copy properties back
-    MOCK_CART.customer = orderToResume.customer; // Cast if needed
-    // MOCK_CART.products = orderToResume.lineItems... (Mapping needed)
-    // For Mock demo, we'll do a best effort mapping
-    MOCK_CART.products = orderToResume.lineItems.map((li) => ({
-        id: li.productId,
-        name: li.name,
-        quantity: li.quantity,
-        price: li.price,
-        internalId: li.internalId || li.productId,
-        variantId: li.variantId,
-        sku: li.sku,
-        images: [li.image],
-        stock: 100,
-        taxTableId: '',
-        attributes: li.attributes,
-    }));
-    MOCK_CART.subtotal = orderToResume.summary.subtotalAfterFees;
-    MOCK_CART.total = orderToResume.summary.total;
-    MOCK_CART.amountToBeCharged = MOCK_CART.total;
-    MOCK_CART.remainingBalance = MOCK_CART.total;
+    restoreMockCartFromOrder(orderToResume);
     // Remove from parked
     MOCK_PARKED_ORDERS.splice(index, 1);
     // Refresh the restored cart and the order lists.

package/dist/actions/set-order-metadata/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Set order metadata action
+ * Calls the setOrderMetadata action on the parent window
+ */
+import type { SetOrderMetadata } from './types';
+export declare const setOrderMetadata: SetOrderMetadata;

package/dist/actions/set-order-metadata/action.js

@@ -0,0 +1,8 @@
+/**
+ * Set order metadata action
+ * Calls the setOrderMetadata action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const setOrderMetadata = async (params) => {
+    return await commandFrameClient.call('setOrderMetadata', params);
+};

package/dist/actions/set-order-metadata/mock.d.ts

@@ -0,0 +1,5 @@
+import type { CFMetadataItem } from '../../CommonTypes';
+import type { SetOrderMetadata } from './types';
+/** Set/remove keys; untouched items (and extra fields such as `externalId`) are kept as-is. */
+export declare const mergeMetadata: <T extends CFMetadataItem>(current: T[] | undefined, changes: Record<string, string | null>) => T[];
+export declare const mockSetOrderMetadata: SetOrderMetadata;

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

@@ -0,0 +1,38 @@
+import { MOCK_ORDERS, MOCK_PARKED_ORDERS, mockPublishEvent } from '../../demo/database';
+/** Metadata for the demo's live cart, which has no order until it is paid or parked. */
+let mockCartMetadata = [];
+/** Set/remove keys; untouched items (and extra fields such as `externalId`) are kept as-is. */
+export const mergeMetadata = (current, changes) => {
+    const byKey = new Map((current ?? []).map((m) => [m.key, m]));
+    for (const [key, value] of Object.entries(changes)) {
+        if (value === null)
+            byKey.delete(key);
+        else
+            byKey.set(key, { ...byKey.get(key), key, value });
+    }
+    return [...byKey.values()];
+};
+export const mockSetOrderMetadata = async (params) => {
+    console.log('[Mock] setOrderMetadata called', params);
+    if (!params?.metadata || Object.keys(params.metadata).length === 0) {
+        throw new Error('setOrderMetadata: metadata must set or remove at least one key');
+    }
+    for (const [key, value] of Object.entries(params.metadata)) {
+        if (!key.trim())
+            throw new Error('setOrderMetadata: metadata keys must be non-empty');
+        if (value !== null && typeof value !== 'string') {
+            throw new Error(`setOrderMetadata: value for "${key}" must be a string or null`);
+        }
+    }
+    if (!params.orderId) {
+        mockCartMetadata = mergeMetadata(mockCartMetadata, params.metadata);
+        return { success: true, orderId: null, metadata: mockCartMetadata, timestamp: new Date().toISOString() };
+    }
+    const order = [...MOCK_ORDERS, ...MOCK_PARKED_ORDERS].find((o) => o._id === params.orderId);
+    if (!order) {
+        throw new Error(`Order with ID ${params.orderId} not found`);
+    }
+    order.metadata = mergeMetadata(order.metadata, params.metadata);
+    mockPublishEvent('orders', 'order-updated', { order });
+    return { success: true, orderId: order._id, metadata: order.metadata, timestamp: new Date().toISOString() };
+};

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

@@ -0,0 +1,20 @@
+import type { CFMetadataItem } from '../../CommonTypes';
+export interface SetOrderMetadataParams {
+    /**
+     * Order to update. Omit to target the live cart's order — including a cart
+     * that hasn't become an order yet (the metadata is carried onto the order
+     * when it is created).
+     */
+    orderId?: string;
+    /** Keys to set (string) or remove (null). Keys not listed are left as they are. */
+    metadata: Record<string, string | null>;
+}
+export interface SetOrderMetadataResponse {
+    success: boolean;
+    /** The order that was updated, or null when the live cart has no order yet. */
+    orderId: string | null;
+    /** The full metadata after the update. */
+    metadata: CFMetadataItem[];
+    timestamp: string;
+}
+export type SetOrderMetadata = (params: SetOrderMetadataParams) => Promise<SetOrderMetadataResponse>;

package/dist/actions/set-order-metadata/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * Set order status action
+ * Calls the setOrderStatus action on the parent window
+ */
+import type { SetOrderStatus } from './types';
+export declare const setOrderStatus: SetOrderStatus;

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

@@ -0,0 +1,8 @@
+/**
+ * Set order status action
+ * Calls the setOrderStatus action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const setOrderStatus = async (params) => {
+    return await commandFrameClient.call('setOrderStatus', params);
+};

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

@@ -0,0 +1,3 @@
+import type { SetOrderStatus } from './types';
+/** Best-effort mock: no state-machine guards beyond the status's payment requirement. */
+export declare const mockSetOrderStatus: SetOrderStatus;

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

@@ -0,0 +1,44 @@
+import { MOCK_ORDERS, MOCK_ORDER_STATUSES, MOCK_PARKED_ORDERS, mockPublishEvent } from '../../demo/database';
+/** Best-effort mock: no state-machine guards beyond the status's payment requirement. */
+export const mockSetOrderStatus = async (params) => {
+    console.log('[Mock] setOrderStatus called', params);
+    if (!params?.orderId) {
+        throw new Error('setOrderStatus: the demo has no live-cart order — pass an orderId');
+    }
+    const order = [...MOCK_ORDERS, ...MOCK_PARKED_ORDERS].find((o) => o._id === params.orderId);
+    if (!order) {
+        throw new Error(`Order with ID ${params.orderId} not found`);
+    }
+    const from = { payment: order.paymentState ?? 'unpaid', fulfillment: order.fulfillmentState ?? 'draft' };
+    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.key === requested) ??
+            (params.key === undefined ? MOCK_ORDER_STATUSES.find((s) => s.id === requested) : undefined);
+        if (!def) {
+            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, 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' };
+    return {
+        success: true,
+        orderId: order._id,
+        customStatus: order.customStatus ?? null,
+        from,
+        to,
+        order,
+        timestamp: new Date().toISOString(),
+    };
+};

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

@@ -0,0 +1,25 @@
+import type { CFOrder, CFOrderCustomStatus } from '../../CommonTypes';
+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;
+    /** 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;
+    orderId: string;
+    /** The order's status after the call; null when cleared. */
+    customStatus: CFOrderCustomStatus | null;
+    /** State before and after — they differ only when the status is bound to a fulfillment state the order wasn't in. */
+    from: CFStatePair | null;
+    to: CFStatePair | null;
+    order: CFOrder;
+    timestamp: string;
+}
+export type SetOrderStatus = (params: SetOrderStatusParams) => Promise<SetOrderStatusResponse>;

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

@@ -0,0 +1 @@
+export {};

package/dist/actions/set-order-type/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Set order type action
+ * Calls the setOrderType action on the parent window
+ */
+import type { SetOrderType } from './types';
+export declare const setOrderType: SetOrderType;

package/dist/actions/set-order-type/action.js

@@ -0,0 +1,8 @@
+/**
+ * Set order type action
+ * Calls the setOrderType action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const setOrderType = async (params) => {
+    return await commandFrameClient.call('setOrderType', params);
+};

package/dist/actions/set-order-type/mock.d.ts

@@ -0,0 +1,3 @@
+import type { SetOrderType } from './types';
+export declare const normalizeOrderType: (value: unknown) => string | null;
+export declare const mockSetOrderType: SetOrderType;

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

@@ -0,0 +1,27 @@
+import { MOCK_ORDERS, MOCK_PARKED_ORDERS, mockPublishEvent } from '../../demo/database';
+/** Type for the demo's live cart, which has no order until it is paid or parked. */
+let mockCartOrderType = null;
+export const normalizeOrderType = (value) => {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error('setOrderType: orderType must be a non-empty string or null');
+    }
+    return value.trim();
+};
+export const mockSetOrderType = async (params) => {
+    console.log('[Mock] setOrderType called', params);
+    const orderType = normalizeOrderType(params?.orderType);
+    const timestamp = new Date().toISOString();
+    if (!params.orderId) {
+        mockCartOrderType = orderType;
+        return { success: true, orderId: null, orderType: mockCartOrderType, timestamp };
+    }
+    const order = [...MOCK_ORDERS, ...MOCK_PARKED_ORDERS].find((o) => o._id === params.orderId);
+    if (!order) {
+        throw new Error(`Order with ID ${params.orderId} not found`);
+    }
+    order.orderType = orderType;
+    mockPublishEvent('orders', 'order-updated', { order });
+    return { success: true, orderId: order._id, orderType, timestamp };
+};

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

@@ -0,0 +1,17 @@
+export interface SetOrderTypeParams {
+    /**
+     * Order to label. Omit to target the live cart — including a cart that isn't an
+     * order yet; the type is carried onto the order when it's created.
+     */
+    orderId?: string;
+    /** Any non-empty label (e.g. 'takeout', 'pickup', 'delivery'), or null to clear it. */
+    orderType: string | null;
+}
+export interface SetOrderTypeResponse {
+    success: boolean;
+    /** The order that was updated, or null when the live cart has no order yet. */
+    orderId: string | null;
+    orderType: string | null;
+    timestamp: string;
+}
+export type SetOrderType = (params: SetOrderTypeParams) => Promise<SetOrderTypeResponse>;

package/dist/actions/set-order-type/types.js

@@ -0,0 +1 @@
+export {};

package/dist/actions/set-scheduled-for/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Set scheduled-for action
+ * Calls the setScheduledFor action on the parent window
+ */
+import type { SetScheduledFor } from './types';
+export declare const setScheduledFor: SetScheduledFor;

package/dist/actions/set-scheduled-for/action.js

@@ -0,0 +1,8 @@
+/**
+ * Set scheduled-for action
+ * Calls the setScheduledFor action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const setScheduledFor = async (params) => {
+    return await commandFrameClient.call('setScheduledFor', params);
+};

package/dist/actions/set-scheduled-for/mock.d.ts

@@ -0,0 +1,4 @@
+import type { SetScheduledFor } from './types';
+/** ISO 8601 in, UTC ISO 8601 out; null stays null (as soon as possible). */
+export declare const normalizeScheduledFor: (value: unknown) => string | null;
+export declare const mockSetScheduledFor: SetScheduledFor;

package/dist/actions/set-scheduled-for/mock.js

@@ -0,0 +1,45 @@
+import { MOCK_ORDERS, MOCK_PARKED_ORDERS, mockPublishEvent } from '../../demo/database';
+/** Time for the demo's live cart, which has no order until it is paid or parked. */
+let mockCartScheduledFor = null;
+/**
+ * An ISO 8601 date-time WITH a zone — 'Z' or an offset. A zoneless time ('2026-10-13T19:00') is
+ * refused: it would mean a different moment on every device. Date.parse alone is too lenient
+ * (it accepts strings like "tomorrow at 7"), so the shape is checked first.
+ */
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})$/;
+/** The YYYY-MM-DD part is a real day — Date.parse quietly rolls "Feb 30" over to March 2. */
+const isCalendarDate = (text) => {
+    const [y, m, d] = text.slice(0, 10).split('-').map(Number);
+    const day = new Date(Date.UTC(y, m - 1, d));
+    return day.getUTCFullYear() === y && day.getUTCMonth() === m - 1 && day.getUTCDate() === d;
+};
+/** ISO 8601 in, UTC ISO 8601 out; null stays null (as soon as possible). */
+export const normalizeScheduledFor = (value) => {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new Error('setScheduledFor: scheduledFor must be an ISO 8601 date-time or null');
+    }
+    const text = value.trim();
+    const ms = ISO_DATE_TIME.test(text) && isCalendarDate(text) ? Date.parse(text) : NaN;
+    if (Number.isNaN(ms)) {
+        throw new Error(`setScheduledFor: "${value}" is not an ISO 8601 date-time with Z or an offset`);
+    }
+    return new Date(ms).toISOString();
+};
+export const mockSetScheduledFor = async (params) => {
+    console.log('[Mock] setScheduledFor called', params);
+    const scheduledFor = normalizeScheduledFor(params?.scheduledFor);
+    const timestamp = new Date().toISOString();
+    if (!params.orderId) {
+        mockCartScheduledFor = scheduledFor;
+        return { success: true, orderId: null, scheduledFor: mockCartScheduledFor, timestamp };
+    }
+    const order = [...MOCK_ORDERS, ...MOCK_PARKED_ORDERS].find((o) => o._id === params.orderId);
+    if (!order) {
+        throw new Error(`Order with ID ${params.orderId} not found`);
+    }
+    order.scheduledFor = scheduledFor;
+    mockPublishEvent('orders', 'order-updated', { order });
+    return { success: true, orderId: order._id, scheduledFor, timestamp };
+};

package/dist/actions/set-scheduled-for/types.d.ts

@@ -0,0 +1,22 @@
+export interface SetScheduledForParams {
+    /**
+     * Order to schedule. Omit to target the live cart — including a cart that isn't an
+     * order yet; the time is carried onto the order when it's created.
+     */
+    orderId?: string;
+    /**
+     * When the customer wants the order, as an ISO 8601 date-time with Z or an offset (e.g.
+     * '2026-10-13T23:00:00.000Z' or '2026-10-13T19:00:00-04:00'), or null for as soon as possible.
+     * Stored in UTC.
+     */
+    scheduledFor: string | null;
+}
+export interface SetScheduledForResponse {
+    success: boolean;
+    /** The order that was updated, or null when the live cart has no order yet. */
+    orderId: string | null;
+    /** The time after the call, normalised to UTC ISO 8601 — or null (as soon as possible). */
+    scheduledFor: string | null;
+    timestamp: string;
+}
+export type SetScheduledFor = (params: SetScheduledForParams) => Promise<SetScheduledForResponse>;

package/dist/actions/set-scheduled-for/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -7,7 +7,7 @@ export interface CFStatePair {
     payment: string;
     fulfillment: string;
 }
-export type CFBlockedBy = "financial_invariant" | "cross_axis_rule" | "path" | "condition";
+export type CFBlockedBy = 'financial_invariant' | 'cross_axis_rule' | 'path' | 'condition';
 export interface CFTransitionResult {
     allowed: boolean;
     blockedBy?: CFBlockedBy;
@@ -30,3 +30,22 @@ export interface CFAvailableTransition {
     displayLabel: string;
     conditions: CFConditionStatus[];
 }
+/**
+ * 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;
+    fulfillmentState?: string;
+    requiresPaymentState?: string[];
+}

package/dist/demo/database.d.ts

@@ -2,6 +2,7 @@
  * Mock Database for Standalone/Demo Mode
  * Stores mock data that mimics the Render environment
  */
+import type { CFOrderStatusDefinition } from '../common-types/order-state';
 import { CFActiveCompany, CFActiveUser, CFActiveStation, CFActiveOutlet, CFActiveOrder, CFCustomer, CFProduct, CFComposite, CFCartLineComponent, CFActiveCart, CFCategory, CFActiveProduct, CFSession, CFActiveRefundDetails, CFSmartGridLayout, CFBooking, CFBookingAvailability, CFBookingResource, CFBookingSlot, CFCartLineModifier, CFProdModifierBreakdown, CFModifierSelection, CFResolvedModifier } from '../CommonTypes';
 export * from './mocks';
 /** Replace mock catalog / context data in place (same array references mock handlers use). */
@@ -19,6 +20,7 @@ export interface MockDatabaseConfig {
     bookingResources?: CFBookingResource[];
     /** Windows already taken when the dataset loads, so a calendar does not open empty. */
     bookings?: CFBooking[];
+    orderStatuses?: CFOrderStatusDefinition[];
     /** Products hidden at an outlet (the host's `catalog-visibility`, product-level rows). Empty = sold everywhere. */
     catalogVisibility?: MockCatalogVisibility[];
 }
@@ -113,6 +115,8 @@ 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 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
  * so existing imports from this module keep working.

package/dist/demo/database.js

@@ -936,11 +936,40 @@ function resolveMockOrderCurrency() {
     }
     return CurrencyCode.USD;
 }
+/** The demo flow's order statuses (getOrderStatuses / setOrderStatus). */
+export const MOCK_ORDER_STATUSES = [
+    { 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
  * so existing imports from this module keep working.
  */
 export function setMockDatabase(config) {
+    if (config.orderStatuses !== undefined) {
+        MOCK_ORDER_STATUSES.splice(0, MOCK_ORDER_STATUSES.length, ...config.orderStatuses);
+    }
     if (config.company !== undefined) {
         Object.assign(MOCK_COMPANY, config.company);
     }