@final-commerce/command-frame 0.1.63 → 0.2.0-beta.6

package/dist/actions/get-available-transitions/mock.js

@@ -0,0 +1,26 @@
+/**
+ * Mock implementation: returns a fixed set of plausible transitions
+ * so the demo app has data to render.
+ */
+export const getAvailableTransitionsMock = async (_params) => ({
+    transitions: [
+        {
+            to: { payment: "refunded", fulfillment: "returned" },
+            displayLabel: "Full Refund",
+            conditions: [{ met: true, description: "Order is paid" }],
+        },
+        {
+            to: { payment: "partially_refunded", fulfillment: "partially_returned" },
+            displayLabel: "Partial Refund",
+            conditions: [{ met: true, description: "Order is paid" }],
+        },
+        {
+            to: { payment: "voided", fulfillment: "cancelled" },
+            displayLabel: "Void Order",
+            conditions: [
+                { met: true, description: "Order exists" },
+                { met: false, description: "No payments captured (mock: skipped)" },
+            ],
+        },
+    ],
+});

package/dist/actions/get-available-transitions/types.d.ts

@@ -0,0 +1,9 @@
+import type { CFAvailableTransition } from "../../common-types/order-state";
+export interface GetAvailableTransitionsParams {
+    /** Order to evaluate. Required — we need the current state. */
+    orderId: string;
+}
+export interface GetAvailableTransitionsResponse {
+    transitions: CFAvailableTransition[];
+}
+export type GetAvailableTransitions = (params: GetAvailableTransitionsParams) => Promise<GetAvailableTransitionsResponse>;

package/dist/actions/get-available-transitions/types.js

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

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

@@ -1,8 +1,8 @@
 import { MOCK_COMPANY, MOCK_OUTLET, MOCK_STATION, MOCK_USER } from "../../demo/database";
 // Mock for Render context (POS terminal)
-export const mockGetContext = async () => {
+export const mockGetContext = () => {
     console.log("[Mock] getContext called (Render)");
-    return {
+    return Promise.resolve({
         userId: MOCK_USER.id || null,
         companyId: MOCK_COMPANY.id || null,
         companyName: MOCK_COMPANY.name || null,
@@ -17,17 +17,23 @@ export const mockGetContext = async () => {
         buildSourceId: "mock_source_id",
         buildIsPremium: true,
         isOffline: false,
+        currency: "USD",
+        currencySymbol: "$",
+        currencyPrefix: "$",
+        currencySuffix: "",
+        thousandSeparator: ",",
+        decimalSeparator: ".",
         user: null,
         company: null,
         station: null,
         outlet: null,
         timestamp: new Date().toISOString()
-    };
+    });
 };
 // Mock for Manage context (Hub/BuilderHub)
-export const mockGetContextManage = async () => {
+export const mockGetContextManage = () => {
     console.log("[Mock] getContext called (Manage)");
-    return {
+    return Promise.resolve({
         user: {
             _id: MOCK_USER.id,
             id: MOCK_USER.id,
@@ -47,5 +53,5 @@ export const mockGetContextManage = async () => {
         extensionId: "mock_extension_id",
         outlets: [MOCK_OUTLET],
         timestamp: new Date().toISOString()
-    };
+    });
 };

package/dist/actions/initiate-refund/types.d.ts

@@ -1,3 +1,4 @@
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface InitiateRefundParams {
     /** The ID of the order to refund. If not provided, uses the currently active order. */
     orderId?: string;
@@ -6,5 +7,7 @@ export interface InitiateRefundResponse {
     success: boolean;
     orderId: string;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type InitiateRefund = (params?: InitiateRefundParams) => Promise<InitiateRefundResponse>;

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

@@ -1,7 +1,10 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface ParkOrderResponse {
     success: boolean;
     order: CFOrder;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type ParkOrder = () => Promise<ParkOrderResponse>;

package/dist/actions/partial-payment/types.d.ts

@@ -1,4 +1,5 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface PartialPaymentParams {
     /** The payment amount (required if openUI is false). */
     amount?: number;
@@ -6,6 +7,8 @@ export interface PartialPaymentParams {
     isPercent?: boolean;
     /** If true, opens the split payment UI. */
     openUI?: boolean;
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: string;
 }
 export interface PartialPaymentResponse {
     success: boolean;
@@ -14,5 +17,7 @@ export interface PartialPaymentResponse {
     openUI: boolean;
     order: CFOrder | null;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type PartialPayment = (params?: PartialPaymentParams) => Promise<PartialPaymentResponse>;

package/dist/actions/print/mock.js

@@ -1,4 +1,4 @@
-export const mockPrint = async (params) => {
+export const mockPrint = (params) => {
     console.log("[Mock] print called", params);
     if (!params) {
         throw new Error("Print parameters are required");
@@ -11,16 +11,13 @@ export const mockPrint = async (params) => {
         case "html":
             console.log("[Mock] Would print HTML:", params.data.html?.substring(0, 100) + "...");
             break;
-        case "selector":
-            console.log("[Mock] Would print element with selector:", params.data.selector);
-            break;
         case "receipt":
             console.log("[Mock] Would print receipt for order:", params.data.order);
             break;
     }
-    return {
+    return Promise.resolve({
         success: true,
         timestamp: new Date().toISOString(),
         type: params.type
-    };
+    });
 };

package/dist/actions/print/types.d.ts

@@ -1,5 +1,5 @@
 import type { CFActiveOrder } from "../../CommonTypes";
-export type PrintType = "image" | "html" | "selector" | "receipt";
+export type PrintType = "image" | "html" | "receipt";
 export type PrintParams = {
     type: "image";
     data: {
@@ -12,12 +12,6 @@ export type PrintParams = {
         html: string;
     };
     options?: PrintOptions;
-} | {
-    type: "selector";
-    data: {
-        selector: string;
-    };
-    options?: PrintOptions;
 } | {
     type: "receipt";
     data: {

package/dist/actions/process-partial-refund/types.d.ts

@@ -1,3 +1,4 @@
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface ProcessPartialRefundParams {
     /** Optional refund reason. */
     reason?: string;
@@ -15,5 +16,7 @@ export interface ProcessPartialRefundResponse {
     success: boolean;
     refundId: string;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type ProcessPartialRefund = (params?: ProcessPartialRefundParams) => Promise<ProcessPartialRefundResponse>;

package/dist/actions/remove-customer-note/mock.js

@@ -1,13 +1,22 @@
-export const mockRemoveCustomerNote = async (params) => {
+import { MOCK_CUSTOMERS, mockPublishEvent } from "../../demo/database";
+export const mockRemoveCustomerNote = (params) => {
     console.log("[Mock] removeCustomerNote called", params);
     const noteId = params?.noteId ?? "";
     const timestamp = new Date().toISOString();
     if (!noteId) {
-        return { success: false, noteId, timestamp };
+        return Promise.resolve({ success: false, noteId, timestamp });
     }
-    return {
-        success: true,
-        noteId,
-        timestamp
-    };
+    for (const customer of MOCK_CUSTOMERS) {
+        const before = customer.notes?.length ?? 0;
+        const removed = (customer.notes || []).find(n => n._id === noteId);
+        customer.notes = (customer.notes || []).filter(n => n._id !== noteId);
+        if ((customer.notes?.length ?? 0) !== before) {
+            mockPublishEvent("customers", "customer-note-deleted", {
+                customer,
+                note: removed
+            });
+            return Promise.resolve({ success: true, noteId, timestamp });
+        }
+    }
+    return Promise.resolve({ success: false, noteId, timestamp });
 };

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

@@ -1,4 +1,5 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface ResumeParkedOrderParams {
     orderId: string;
 }
@@ -6,5 +7,7 @@ export interface ResumeParkedOrderResponse {
     success: boolean;
     order: CFOrder;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type ResumeParkedOrder = (params?: ResumeParkedOrderParams) => Promise<ResumeParkedOrderResponse>;

package/dist/actions/tap-to-pay-payment/types.d.ts

@@ -1,7 +1,10 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface TapToPayPaymentParams {
     /** If not provided, uses the cart total. */
     amount?: number;
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: string;
 }
 export interface TapToPayPaymentResponse {
     success: boolean;
@@ -9,5 +12,7 @@ export interface TapToPayPaymentResponse {
     paymentType: string;
     order: CFOrder | null;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type TapToPayPayment = (params?: TapToPayPaymentParams) => Promise<TapToPayPaymentResponse>;

package/dist/actions/terminal-payment/types.d.ts

@@ -1,9 +1,12 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface TerminalPaymentParams {
     /** If not provided, uses the cart total. */
     amount?: number;
     /** "Bluetooth" or "Cloud". Defaults to "Cloud". */
     paymentType?: 'Bluetooth' | 'Cloud';
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: string;
 }
 export interface TerminalPaymentResponse {
     success: boolean;
@@ -11,5 +14,7 @@ export interface TerminalPaymentResponse {
     paymentType: string;
     order: CFOrder | null;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type TerminalPayment = (params?: TerminalPaymentParams) => Promise<TerminalPaymentResponse>;

package/dist/actions/vendara-payment/types.d.ts

@@ -1,7 +1,10 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface VendaraPaymentParams {
     /** If not provided, uses the cart total. */
     amount?: number;
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: string;
 }
 export interface VendaraPaymentResponse {
     success: boolean;
@@ -9,5 +12,7 @@ export interface VendaraPaymentResponse {
     paymentType: string;
     order: CFOrder | null;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type VendaraPayment = (params?: VendaraPaymentParams) => Promise<VendaraPaymentResponse>;

package/dist/common-types/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./custom-tables";
 export * from "./custom-extensions";
+export * from "./order-state";

package/dist/common-types/index.js

@@ -1,2 +1,3 @@
 export * from "./custom-tables";
 export * from "./custom-extensions";
+export * from "./order-state";

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

@@ -0,0 +1,32 @@
+/**
+ * State machine protocol types for the command-frame boundary.
+ * These mirror @final-commerce/common shapes but carry no logic.
+ * command-frame must NOT depend on common.
+ */
+export interface CFStatePair {
+    payment: string;
+    fulfillment: string;
+}
+export type CFBlockedBy = "financial_invariant" | "cross_axis_rule" | "path" | "condition";
+export interface CFTransitionResult {
+    allowed: boolean;
+    blockedBy?: CFBlockedBy;
+    guard?: string;
+    reason?: string;
+    failedConditions?: CFFailedCondition[];
+}
+export interface CFFailedCondition {
+    field: string;
+    operator: string;
+    value: unknown;
+    reason?: string;
+}
+export interface CFConditionStatus {
+    met: boolean;
+    description: string;
+}
+export interface CFAvailableTransition {
+    to: CFStatePair;
+    displayLabel: string;
+    conditions: CFConditionStatus[];
+}

package/dist/common-types/order-state.js

@@ -0,0 +1,6 @@
+/**
+ * State machine protocol types for the command-frame boundary.
+ * These mirror @final-commerce/common shapes but carry no logic.
+ * command-frame must NOT depend on common.
+ */
+export {};

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

@@ -0,0 +1,77 @@
+/**
+ * State config fragment types for the command-frame boundary.
+ * These mirror @final-commerce/common's StateConfigFragment shapes but carry no logic.
+ * command-frame must NOT depend on common.
+ *
+ * Extensions pass a CFStateConfigFragment to Render, which merges it into the
+ * running StoredStateConfig via mergeFragment(). All contributed entries are tagged
+ * with the extension's id (_sourceExtensionId) so they can be cleaned up on unregister.
+ */
+import type { CFStatePair } from "./order-state";
+export type CFConditionOperator = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "notIn" | "isEmpty" | "isNotEmpty";
+export interface CFCondition {
+    /** Dot-path into the OrderContext, e.g. "order.balance" or "computed.totalPaid". */
+    field: string;
+    operator: CFConditionOperator;
+    value: unknown;
+}
+/** All conditions in a group are AND'd together. */
+export interface CFConditionGroup {
+    conditions: CFCondition[];
+}
+/** Groups are OR'd — the first passing group satisfies the set. */
+export interface CFTransitionConditionSet {
+    id: string;
+    label: string;
+    groups: CFConditionGroup[];
+}
+export interface CFPaymentTransitionPath {
+    from: string;
+    to: string;
+    /** References a CFTransitionConditionSet.id in the same fragment. */
+    conditionSetId?: string;
+}
+export interface CFFulfillmentTransitionPath {
+    from: string;
+    to: string;
+    conditionSetId?: string;
+}
+export interface CFCrossAxisRule {
+    id: string;
+    label: string;
+    description?: string;
+    enabled: boolean;
+    /** Which axis + target state(s) activate this rule. */
+    trigger: {
+        axis: "payment" | "fulfillment";
+        to: string[];
+    };
+    /** Which axis + states must be present when the trigger fires. */
+    requires: {
+        axis: "payment" | "fulfillment";
+        states: string[];
+    };
+}
+export interface CFDisplayStateRule {
+    paymentState?: string[];
+    fulfillmentState?: string[];
+    label: string;
+    color?: string;
+    icon?: string;
+}
+/**
+ * Partial config contributed by an extension. Render merges this into the
+ * running StoredStateConfig. All arrays are appended; display rules replace
+ * on key collision.
+ *
+ * IDs (crossAxisRules, transitionConditions) must be unique across the merged
+ * config — prefix them with your extension id to avoid collisions.
+ */
+export interface CFStateConfigFragment {
+    paymentPaths?: CFPaymentTransitionPath[];
+    fulfillmentPaths?: CFFulfillmentTransitionPath[];
+    crossAxisRules?: CFCrossAxisRule[];
+    transitionConditions?: CFTransitionConditionSet[];
+    validInitialStates?: CFStatePair[];
+    displayStateMap?: CFDisplayStateRule[];
+}

package/dist/common-types/state-fragment.js

@@ -0,0 +1,10 @@
+/**
+ * State config fragment types for the command-frame boundary.
+ * These mirror @final-commerce/common's StateConfigFragment shapes but carry no logic.
+ * command-frame must NOT depend on common.
+ *
+ * Extensions pass a CFStateConfigFragment to Render, which merges it into the
+ * running StoredStateConfig via mergeFragment(). All contributed entries are tagged
+ * with the extension's id (_sourceExtensionId) so they can be cleaned up on unregister.
+ */
+export {};

package/dist/demo/database.js

@@ -202,7 +202,7 @@ export const MOCK_CATEGORY_SPICY = {
     parentId: null
 };
 // --- PRODUCTS ---
-const createInventory = (stock) => [{ outletId: MOCK_OUTLET_MAIN.id, stock }];
+const createInventory = (stock) => [{ warehouse: "main", outletId: MOCK_OUTLET_MAIN.id, stock }];
 // Helper for Simple Product
 const createSimpleProduct = (id, name, price, image, categories, description) => {
     const sku = `SKU-${id.toUpperCase()}`;
@@ -335,6 +335,9 @@ export const MOCK_ORDER_1 = {
     companyId: MOCK_COMPANY.id,
     externalId: null,
     status: "completed",
+    paymentState: "paid",
+    fulfillmentState: "fulfilled",
+    displayState: "Completed",
     customer: MOCK_CUSTOMER_1,
     summary: {
         total: 2100,
@@ -366,10 +369,7 @@ export const MOCK_ORDER_1 = {
     metadata: [],
     billing: MOCK_CUSTOMER_1.billing || null,
     shipping: null,
-    lineItems: [
-        createLineItem(MOCK_PRODUCT_GARLIC, 0, 1),
-        createLineItem(MOCK_PRODUCT_BASIL_ALMOND, 0, 1)
-    ],
+    lineItems: [createLineItem(MOCK_PRODUCT_GARLIC, 0, 1), createLineItem(MOCK_PRODUCT_BASIL_ALMOND, 0, 1)],
     customSales: [],
     balance: 0,
     user: MOCK_USER_LUIGI,
@@ -385,6 +385,9 @@ export const MOCK_ORDER_2 = {
     companyId: MOCK_COMPANY.id,
     externalId: null,
     status: "completed",
+    paymentState: "paid",
+    fulfillmentState: "fulfilled",
+    displayState: "Completed",
     customer: MOCK_CUSTOMER_2,
     summary: {
         total: 3000,
@@ -416,9 +419,7 @@ export const MOCK_ORDER_2 = {
     metadata: [],
     billing: null,
     shipping: null,
-    lineItems: [
-        createLineItem(MOCK_PRODUCT_BEER, 0, 2)
-    ],
+    lineItems: [createLineItem(MOCK_PRODUCT_BEER, 0, 2)],
     customSales: [],
     balance: 0,
     user: MOCK_USER_MARIO,
@@ -430,20 +431,8 @@ export const MOCK_ORDER_2 = {
 export const MOCK_USERS = [MOCK_USER_MARIO, MOCK_USER_LUIGI];
 export const MOCK_STATIONS = [MOCK_STATION_1, MOCK_STATION_2];
 export const MOCK_OUTLETS = [MOCK_OUTLET_MAIN];
-export const MOCK_CUSTOMERS = [
-    MOCK_CUSTOMER_1,
-    MOCK_CUSTOMER_2,
-    MOCK_CUSTOMER_3,
-    MOCK_CUSTOMER_4,
-    MOCK_CUSTOMER_5
-];
-export const MOCK_CATEGORIES = [
-    MOCK_CATEGORY_PASTES,
-    MOCK_CATEGORY_SPECIALTY,
-    MOCK_CATEGORY_BASIC,
-    MOCK_CATEGORY_VEGAN,
-    MOCK_CATEGORY_SPICY
-];
+export const MOCK_CUSTOMERS = [MOCK_CUSTOMER_1, MOCK_CUSTOMER_2, MOCK_CUSTOMER_3, MOCK_CUSTOMER_4, MOCK_CUSTOMER_5];
+export const MOCK_CATEGORIES = [MOCK_CATEGORY_PASTES, MOCK_CATEGORY_SPECIALTY, MOCK_CATEGORY_BASIC, MOCK_CATEGORY_VEGAN, MOCK_CATEGORY_SPICY];
 export const MOCK_PRODUCTS = [
     MOCK_PRODUCT_BASIL_ALMOND,
     MOCK_PRODUCT_BEER,
@@ -494,7 +483,8 @@ export const resetMockCart = () => {
     };
 };
 function resolveMockOrderCurrency() {
-    const raw = MOCK_COMPANY.settings?.currency;
+    const settings = MOCK_COMPANY.settings;
+    const raw = settings?.currency;
     if (typeof raw === "string" && Object.values(CurrencyCode).includes(raw)) {
         return raw;
     }
@@ -554,6 +544,7 @@ export const safeSerialize = (data) => {
     return JSON.parse(JSON.stringify(data));
 };
 const mockTopicSubscribers = {};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const mockPublishEvent = (topic, eventType, data) => {
     const subscribers = mockTopicSubscribers[topic] || [];
     const event = {
@@ -618,6 +609,9 @@ export const createOrderFromCart = (paymentType, amount, processor = "cash") =>
         companyId: MOCK_COMPANY.id,
         externalId: null,
         status: "completed",
+        paymentState: "paid",
+        fulfillmentState: "fulfilled",
+        displayState: "Completed",
         customer: MOCK_CART.customer ? MOCK_CART.customer : null,
         summary: {
             total: totalNum,
@@ -660,6 +654,6 @@ export const createOrderFromCart = (paymentType, amount, processor = "cash") =>
     MOCK_ORDERS.push(newOrder);
     resetMockCart();
     // Publish cart-created event after cart is reset (simulates new empty cart)
-    mockPublishEvent('cart', 'cart-created', {});
+    mockPublishEvent("cart", "cart-created", {});
     return newOrder;
 };

package/dist/fragments/index.d.ts

@@ -0,0 +1 @@
+export { preorderNoDepositFragment } from "./preorder-no-deposit";

package/dist/fragments/index.js

@@ -0,0 +1 @@
+export { preorderNoDepositFragment } from "./preorder-no-deposit";

package/dist/fragments/preorder-no-deposit.d.ts

@@ -0,0 +1,26 @@
+import type { CFStateConfigFragment } from "../common-types/state-fragment";
+/**
+ * Pre-order fragment — no deposit required.
+ *
+ * Mirrors preorder-with-deposit but removes the cross-axis rule that gates
+ * `on_hold` on payment state. An order can be placed on hold while still
+ * `unpaid` — payment is collected later (pay-at-pickup, BOPIS, COD, etc.).
+ *
+ * State flow:
+ *
+ *   unpaid|on_hold  →  (cashier collects payment)  →  paid|on_hold
+ *                                                           ↓
+ *                                              (progress fulfillment)
+ *                                                           ↓
+ *                                                    paid|in_progress
+ *
+ * Key difference from preorder-with-deposit:
+ *   - No cross-axis rule blocking `on_hold` when unpaid. The cashier can
+ *     confirm the pre-order without collecting a deposit first.
+ *   - `unpaid|on_hold` is whitelisted as a valid first-save state pair.
+ *   - `in_progress` still requires at least a partial payment (you must pay
+ *     before the merchant starts fulfilling).
+ *
+ * Prefix all IDs with your extension id before merging to avoid collisions.
+ */
+export declare const preorderNoDepositFragment: CFStateConfigFragment;