@final-commerce/command-frame 0.1.73 → 0.1.74

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/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/open-extension-overlay/mock.d.ts

@@ -0,0 +1,2 @@
+import type { OpenExtensionOverlay } from "./types";
+export declare const mockOpenExtensionOverlay: OpenExtensionOverlay;

package/dist/actions/open-extension-overlay/mock.js

@@ -0,0 +1 @@
+export const mockOpenExtensionOverlay = async (_params) => true;

package/dist/actions/open-extension-overlay/types.d.ts

@@ -0,0 +1,9 @@
+import type { InterceptorPoint, InterceptorReturn } from "../../interceptors/types";
+export interface OpenExtensionOverlayParams {
+    point: InterceptorPoint;
+    payload?: any;
+    /** Owning extension id. Injected by the host for interceptor-originated calls; optional for direct calls. */
+    extensionId?: string;
+}
+export type OpenExtensionOverlayResponse = InterceptorReturn;
+export type OpenExtensionOverlay = (params: OpenExtensionOverlayParams) => Promise<OpenExtensionOverlayResponse>;

package/dist/actions/open-extension-overlay/types.js

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

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/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-product-from-cart/mock.js

@@ -1,8 +1,8 @@
 import { MOCK_CART, mockPublishEvent } from "../../demo/database";
-export const mockRemoveProductFromCart = async (params) => {
+export const mockRemoveProductFromCart = (params) => {
     console.log("[Mock] removeProductFromCart called", params);
     if (!params?.internalId) {
-        throw new Error('internalId is required');
+        throw new Error("internalId is required");
     }
     const { internalId } = params;
     // Find the product in the cart
@@ -20,13 +20,13 @@ export const mockRemoveProductFromCart = async (params) => {
     MOCK_CART.amountToBeCharged = MOCK_CART.total;
     MOCK_CART.remainingBalance = MOCK_CART.total;
     // Publish product-deleted event
-    mockPublishEvent('cart', 'product-deleted', {
+    mockPublishEvent("cart", "product-deleted", {
         product: product,
         internalId: internalId
     });
-    return {
+    return Promise.resolve({
         success: true,
         internalId: internalId,
         timestamp: new Date().toISOString()
-    };
+    });
 };

package/dist/actions/resolve-extension-overlay/mock.d.ts

@@ -0,0 +1,2 @@
+import type { ResolveExtensionOverlay } from "./types";
+export declare const mockResolveExtensionOverlay: ResolveExtensionOverlay;

package/dist/actions/resolve-extension-overlay/mock.js

@@ -0,0 +1 @@
+export const mockResolveExtensionOverlay = async (_params) => ({ success: true });

package/dist/actions/resolve-extension-overlay/types.d.ts

@@ -0,0 +1,9 @@
+import type { InterceptorReturn } from "../../interceptors/types";
+export interface ResolveExtensionOverlayParams {
+    overlayId: string;
+    result: InterceptorReturn;
+}
+export interface ResolveExtensionOverlayResponse {
+    success: boolean;
+}
+export type ResolveExtensionOverlay = (params: ResolveExtensionOverlayParams) => Promise<ResolveExtensionOverlayResponse>;

package/dist/actions/resolve-extension-overlay/types.js

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

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/update-cart-item-quantity/mock.js

@@ -1,11 +1,11 @@
 import { MOCK_CART, mockPublishEvent } from "../../demo/database";
-export const mockUpdateCartItemQuantity = async (params) => {
+export const mockUpdateCartItemQuantity = (params) => {
     console.log("[Mock] updateCartItemQuantity called", params);
     if (!params?.internalId) {
-        throw new Error('internalId is required');
+        throw new Error("internalId is required");
     }
     if (params.quantity === undefined || params.quantity === null) {
-        throw new Error('quantity is required');
+        throw new Error("quantity is required");
     }
     const { internalId, quantity } = params;
     // Find the product in the cart
@@ -25,16 +25,16 @@ export const mockUpdateCartItemQuantity = async (params) => {
         MOCK_CART.amountToBeCharged = MOCK_CART.total;
         MOCK_CART.remainingBalance = MOCK_CART.total;
         // Publish product-deleted event
-        mockPublishEvent('cart', 'product-deleted', {
+        mockPublishEvent("cart", "product-deleted", {
             product: product,
             internalId: internalId
         });
-        return {
+        return Promise.resolve({
             success: true,
             internalId: internalId,
             quantity: 0,
             timestamp: new Date().toISOString()
-        };
+        });
     }
     // Update quantity
     const quantityDelta = quantity - previousQuantity;
@@ -46,15 +46,15 @@ export const mockUpdateCartItemQuantity = async (params) => {
     MOCK_CART.amountToBeCharged = MOCK_CART.total;
     MOCK_CART.remainingBalance = MOCK_CART.total;
     // Publish product-updated event
-    mockPublishEvent('cart', 'product-updated', {
+    mockPublishEvent("cart", "product-updated", {
         product: product,
         previousQuantity: previousQuantity,
         newQuantity: quantity
     });
-    return {
+    return Promise.resolve({
         success: true,
         internalId: internalId,
         quantity: quantity,
         timestamp: new Date().toISOString()
-    };
+    });
 };

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

@@ -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,
@@ -382,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,
@@ -607,6 +613,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,

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;