@final-commerce/command-frame 0.3.2-beta.1 → 0.4.0-preprod.1

package/README.md

@@ -71,7 +71,7 @@ For building applications that run inside the Render Point of Sale interface.
 - **Features:** Order management, Product catalog, Customer management, Payments, Hardware integration (Cash drawer, Printer), Custom tables, Secrets storage.
 
 ```typescript
-import { RenderClient } from "@final-commerce/command-frame";
+import { RenderClient } from '@final-commerce/command-frame';
 
 const client = new RenderClient();
 const products = await client.getProducts();
@@ -85,7 +85,7 @@ For building applications that run inside the Final Commerce Management Dashboar
 - **Features:** Context, catalog, entities, custom tables, secrets, and optional host-specific commands (navigation, media, tax, branding, notifications) when the dashboard implements them.
 
 ```typescript
-import { ManageClient } from "@final-commerce/command-frame";
+import { ManageClient } from '@final-commerce/command-frame';
 
 const client = new ManageClient();
 const context = await client.getContext();
@@ -96,17 +96,17 @@ const context = await client.getContext();
 The pub/sub system allows iframe extensions to subscribe to topics and receive real-time events published by the host (Render). Subscriptions are **page-scoped** -- they fire only while the iframe is mounted on the current page.
 
 - **[Pub/Sub Documentation](./src/pubsub/README.md)**
-- **Topics:** Cart (16), Customers (8), Orders (4), Payments (2), Products (4), Refunds (4), Print (3), Custom Tables (3), Outlet (2), Station (2), Session (2), Users (2).
+- **Topics:** Cart (16), Customers (8), Orders (5), Payments (2), Products (4), Refunds (4), Print (3), Custom Tables (3), Outlet (2), Station (2), Session (2), Users (2).
 
 ```typescript
-import { topics } from "@final-commerce/command-frame";
+import { topics } from '@final-commerce/command-frame';
 
-const subscriptionId = topics.subscribe("cart", event => {
-    console.log("Cart event:", event.type, event.data);
+const subscriptionId = topics.subscribe('cart', (event) => {
+  console.log('Cart event:', event.type, event.data);
 });
 
 // Unsubscribe when done
-topics.unsubscribe("cart", subscriptionId);
+topics.unsubscribe('cart', subscriptionId);
 ```
 
 ## Hooks
@@ -118,21 +118,21 @@ Hooks are **session-scoped** event callbacks that run in the host (Render) conte
 - A stable `hookId` is required for deduplication (safe on iframe reload).
 
 ```typescript
-import { hooks } from "@final-commerce/command-frame";
+import { hooks } from '@final-commerce/command-frame';
 
 hooks.register(
-    "cart",
-    async (event, hostCommands) => {
-        await hostCommands.upsertCustomTableData({
-            tableName: "cart-events-log",
-            data: { eventType: event.type, payload: event.data, timestamp: event.timestamp }
-        });
-    },
-    { hookId: "my-extension:cart-log" }
+  'cart',
+  async (event, hostCommands) => {
+    await hostCommands.upsertCustomTableData({
+      tableName: 'cart-events-log',
+      data: { eventType: event.type, payload: event.data, timestamp: event.timestamp },
+    });
+  },
+  { hookId: 'my-extension:cart-log' },
 );
 
 // Unregister when no longer needed
-hooks.unregister("my-extension:cart-log");
+hooks.unregister('my-extension:cart-log');
 ```
 
 ## Interceptors
@@ -147,14 +147,14 @@ Interceptors let an extension **gate a POS flow** (approve / modify / block) at
 import { interceptors } from '@final-commerce/command-frame';
 
 interceptors.register(
-    'refund_start',
-    async (payload, cmds) => {
-        if (payload.paymentTypes.includes('redeem')) {
-            return cmds.openExtensionOverlay({ point: 'refund_start', payload });
-        }
-        return true; // nothing for us to do
-    },
-    { interceptorId: 'my-extension:refund-guard' }
+  'refund_start',
+  async (payload, cmds) => {
+    if (payload.paymentTypes.includes('redeem')) {
+      return cmds.openExtensionOverlay({ point: 'refund_start', payload });
+    }
+    return true; // nothing for us to do
+  },
+  { interceptorId: 'my-extension:refund-guard' },
 );
 ```
 
@@ -171,13 +171,21 @@ interceptors.register(
 Exported APIs: `installExtensionRefundListener`, `EXTENSION_REFUND_REQUEST_ACTION`, types **`ExtensionRefundParams`** / **`ExtensionRefundResponse`**.
 
 ```typescript
-import { installExtensionRefundListener, type ExtensionRefundParams, type ExtensionRefundResponse } from "@final-commerce/command-frame";
-
-const unsubscribe = installExtensionRefundListener(async (params: ExtensionRefundParams): Promise<ExtensionRefundResponse> => {
+import {
+  installExtensionRefundListener,
+  type ExtensionRefundParams,
+  type ExtensionRefundResponse,
+} from '@final-commerce/command-frame';
+
+const unsubscribe = installExtensionRefundListener(
+  async (params: ExtensionRefundParams): Promise<ExtensionRefundResponse> => {
     // params.paymentType === "redeem", params.amount in major currency units, params.saleId, params.processor, etc.
     const ok = await myGiftCardProvider.refund(params);
-    return ok ? { success: true, extensionTransactionId: ok.providerRefundId } : { success: false, error: "Refund declined" };
-});
+    return ok
+      ? { success: true, extensionTransactionId: ok.providerRefundId }
+      : { success: false, error: 'Refund declined' };
+  },
+);
 
 // on teardown (optional)
 // unsubscribe();

package/dist/actions/apply-transition/mock.d.ts

@@ -1,6 +1,6 @@
 import type { ApplyTransitionParams, ApplyTransitionResponse } from "./types";
 /**
- * Mock implementation: applies all transitions except a few known-invalid ones
+ * Mock implementation: applies all transitions except a known-invalid one
  * so the demo app can show both successful and blocked responses.
  */
 export declare const applyTransitionMock: (params: ApplyTransitionParams) => Promise<ApplyTransitionResponse>;

package/dist/actions/apply-transition/mock.js

@@ -1,33 +1,23 @@
 /**
- * Mock implementation: applies all transitions except a few known-invalid ones
+ * Mock implementation: applies all transitions except a known-invalid one
  * so the demo app can show both successful and blocked responses.
  */
 export const applyTransitionMock = (params) => {
-    const { to } = params;
-    if (to.payment === "refunded" && to.fulfillment === "draft") {
+    const { targetFulfillmentState } = params;
+    if (targetFulfillmentState === "cancelled") {
         return Promise.resolve({
             result: {
                 allowed: false,
-                blockedBy: "financial_invariant",
-                guard: "no-refund-in-draft",
-                reason: "Cannot refund an order that is still in draft"
-            }
-        });
-    }
-    if (to.payment === "paid" && to.fulfillment === "cancelled") {
-        return Promise.resolve({
-            result: {
-                allowed: false,
-                blockedBy: "cross_axis_rule",
-                guard: "no-pay-cancelled",
-                reason: "Cannot mark a cancelled order as paid"
+                blockedBy: "condition",
+                guard: "no-cancel-open-order",
+                reason: "Cannot cancel an order with open items"
             }
         });
     }
     return Promise.resolve({
         result: { allowed: true },
         from: { payment: "unpaid", fulfillment: "draft" },
-        to,
-        displayState: `${to.payment} / ${to.fulfillment}`
+        to: { payment: "unpaid", fulfillment: targetFulfillmentState },
+        displayState: `unpaid / ${targetFulfillmentState}`
     });
 };

package/dist/actions/apply-transition/types.d.ts

@@ -1,9 +1,11 @@
 import type { CFStatePair, CFTransitionResult } from "../../common-types/order-state";
 export interface ApplyTransitionParams {
-    /** Order to transition. */
-    orderId: string;
-    /** Target state pair. */
-    to: CFStatePair;
+    /** Order to transition. Omit to target the active order — materializing one from the live cart if none exists. */
+    orderId?: string;
+    /** Target fulfillment state. The payment axis is never client-settable. */
+    targetFulfillmentState: string;
+    /** Clear the terminal after transitioning the ACTIVE order (park parity). Default true. */
+    clearTerminal?: boolean;
 }
 export interface ApplyTransitionResponse {
     result: CFTransitionResult;

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

@@ -15,8 +15,8 @@ export interface ExtensionPaymentParams {
     referenceId?: string;
     extensionId?: string;
     metadata?: Record<string, unknown>;
-    /** Override the fulfillment state after full payment. Render resolves the cascade. */
-    checkoutFulfillmentTarget?: string;
+    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    targetFulfillmentState?: string;
     /** EMV data when the underlying payment carries one (typed as `IntegrationEmvData` by the integration wrapper). */
     emvData?: unknown;
     /** Processor fee in integer MINOR currency units; recorded on the order's paymentMethod.processorFee. */

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

@@ -1,6 +1,8 @@
-import type { GetAvailableTransitionsParams, GetAvailableTransitionsResponse } from "./types";
+import type { GetAvailableTransitions } from "./types";
 /**
  * Mock implementation: returns a fixed set of plausible transitions
- * so the demo app has data to render.
+ * so the demo app has data to render. Mirrors an UNPAID order under the
+ * default (empty cross-axis rules) config: fulfillment can advance without
+ * payment (FI-6383), plus the classic park/void moves.
  */
-export declare const getAvailableTransitionsMock: (_params: GetAvailableTransitionsParams) => Promise<GetAvailableTransitionsResponse>;
+export declare const getAvailableTransitionsMock: GetAvailableTransitions;

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

@@ -1,26 +1,38 @@
 /**
  * Mock implementation: returns a fixed set of plausible transitions
- * so the demo app has data to render.
+ * so the demo app has data to render. Mirrors an UNPAID order under the
+ * default (empty cross-axis rules) config: fulfillment can advance without
+ * payment (FI-6383), plus the classic park/void moves.
  */
-export const getAvailableTransitionsMock = async (_params) => ({
+export const getAvailableTransitionsMock = () => Promise.resolve({
     transitions: [
         {
-            to: { payment: "refunded", fulfillment: "returned" },
-            displayLabel: "Full Refund",
-            conditions: [{ met: true, description: "Order is paid" }],
+            to: { payment: "unpaid", fulfillment: "in_progress" },
+            displayLabel: "Start Preparing",
+            conditions: [{ met: true, description: "Order has items" }]
         },
         {
-            to: { payment: "partially_refunded", fulfillment: "partially_returned" },
-            displayLabel: "Partial Refund",
-            conditions: [{ met: true, description: "Order is paid" }],
+            to: { payment: "unpaid", fulfillment: "fulfilled" },
+            displayLabel: "Mark Fulfilled",
+            conditions: [{ met: true, description: "Order has items" }]
+        },
+        {
+            to: { payment: "unpaid", fulfillment: "on_hold" },
+            displayLabel: "Park Order",
+            conditions: [{ met: true, description: "Order is open" }]
+        },
+        {
+            to: { payment: "paid", fulfillment: "fulfilled" },
+            displayLabel: "Complete Payment",
+            conditions: [{ met: true, description: "Balance due > 0" }]
         },
         {
             to: { payment: "voided", fulfillment: "cancelled" },
             displayLabel: "Void Order",
             conditions: [
                 { met: true, description: "Order exists" },
-                { met: false, description: "No payments captured (mock: skipped)" },
-            ],
-        },
-    ],
+                { met: false, description: "No payments captured (mock: skipped)" }
+            ]
+        }
+    ]
 });

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

@@ -51,6 +51,8 @@ export interface IntegrationPaymentParams {
     metadata?: Record<string, unknown>;
     /** Provider fee in integer MINOR currency units — stored on paymentMethod.processorFee. */
     processorFee?: number;
+    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    targetFulfillmentState?: string;
 }
 export type IntegrationPaymentResponse = ExtensionPaymentResponse;
 export type IntegrationPayment = (params: IntegrationPaymentParams) => Promise<IntegrationPaymentResponse>;

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

@@ -7,8 +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;
+    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    targetFulfillmentState?: string;
 }
 export interface PartialPaymentResponse {
     success: boolean;

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

@@ -12,6 +12,8 @@ export interface RedeemPaymentParams {
     processor?: string;
     referenceId?: string;
     metadata?: Record<string, unknown>;
+    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    targetFulfillmentState?: string;
 }
 export type RedeemPaymentResponse = ExtensionPaymentResponse;
 export type RedeemPayment = (params: RedeemPaymentParams) => Promise<RedeemPaymentResponse>;

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

@@ -12,9 +12,9 @@ export interface TerminalPaymentParams {
      */
     amount: number;
     /** "Bluetooth" or "Cloud". Defaults to "Cloud". */
-    paymentType?: 'Bluetooth' | 'Cloud';
-    /** Override the fulfillment state after full payment. Render resolves the cascade. */
-    checkoutFulfillmentTarget?: string;
+    paymentType?: "Bluetooth" | "Cloud";
+    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    targetFulfillmentState?: string;
 }
 export interface TerminalPaymentResponse {
     success: boolean;

package/dist/actions/void-order/action.d.ts

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

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

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

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

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

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

@@ -0,0 +1,23 @@
+import { MOCK_ORDERS, mockPublishEvent } from '../../demo/database';
+// Payment states in which an order is still open — mirrors the runtime gate
+// (kaching's OPEN_PAYMENT_STATES / handler.ts). Anything outside this set
+// (paid, partially_refunded, refunded, voided, or unknown) is ORDER_NOT_VOIDABLE.
+const OPEN_PAYMENT_STATES = ['unpaid', 'payment_pending', 'partially_paid'];
+export const mockVoidOrder = async (params) => {
+    console.log('[Mock] voidOrder called', params);
+    const order = params?.orderId ? MOCK_ORDERS.find((o) => o._id === params.orderId) : MOCK_ORDERS[0];
+    if (!order) {
+        throw new Error(`Order with ID ${params?.orderId} not found`);
+    }
+    const orderId = order._id;
+    // Only OPEN orders are voidable — mirror the runtime gate.
+    if (!OPEN_PAYMENT_STATES.includes(order.paymentState)) {
+        throw new Error(`ORDER_NOT_VOIDABLE: order ${orderId} is '${order.paymentState}' — use the refund flow for completed orders`);
+    }
+    const hasCapturedLegs = (order.paymentMethods?.length ?? 0) > 0;
+    const outcome = hasCapturedLegs ? 'refunded' : 'voided';
+    order.paymentState = outcome;
+    order.fulfillmentState = 'cancelled';
+    mockPublishEvent('orders', 'order-voided', { orderId, outcome, reason: params?.reason });
+    return { success: true, orderId, outcome, timestamp: new Date().toISOString() };
+};

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

@@ -0,0 +1,27 @@
+import type { CFTransitionResult } from '../../common-types/order-state';
+export type VoidOrderOutcome = 'voided' | 'refunded';
+export interface VoidOrderParams {
+    /** Order to void; defaults to the active order. */
+    orderId?: string;
+    /**
+     * Optional cashier-facing reason. On a pure void, recorded on the void audit
+     * row and carried on the `order-voided` event. On the refund branch it rides
+     * the event only — the refund dispatcher does not consume it.
+     */
+    reason?: string;
+}
+export interface VoidOrderResponse {
+    success: boolean;
+    orderId: string;
+    /**
+     * `voided`   — nothing was captured; pure state transition to voided × cancelled.
+     * `refunded` — captured split legs were refunded to their original tenders;
+     *              order lands refunded × cancelled (financially equivalent to a
+     *              void, but the capture + payout stay on the audit trail).
+     */
+    outcome: VoidOrderOutcome;
+    timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
+}
+export type VoidOrder = (params?: VoidOrderParams) => Promise<VoidOrderResponse>;

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

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

package/dist/demo/database.d.ts

@@ -2,8 +2,8 @@
  * Mock Database for Standalone/Demo Mode
  * Stores mock data that mimics the Render environment
  */
-import { CFActiveCompany, CFActiveUser, CFActiveStation, CFActiveOutlet, CFActiveOrder, CFCustomer, CFProduct, CFActiveCart, CFCategory, CFActiveProduct, CFSession, CFActiveRefundDetails, CFSmartGridLayout } from "../CommonTypes";
-export * from "./mocks";
+import { CFActiveCompany, CFActiveUser, CFActiveStation, CFActiveOutlet, CFActiveOrder, CFCustomer, CFProduct, CFActiveCart, CFCategory, CFActiveProduct, CFSession, CFActiveRefundDetails, CFSmartGridLayout } from '../CommonTypes';
+export * from './mocks';
 /** Replace mock catalog / context data in place (same array references mock handlers use). */
 export interface MockDatabaseConfig {
     company?: Partial<CFActiveCompany>;
@@ -51,6 +51,7 @@ export declare const MOCK_PRODUCT_BLACK_GARLIC: import("@final-commerce/common/p
 export declare const MOCK_ORDER_1: CFActiveOrder;
 export declare const MOCK_ORDER_2: CFActiveOrder;
 export declare const MOCK_ORDER_3: CFActiveOrder;
+export declare const MOCK_ORDER_4: CFActiveOrder;
 export declare const MOCK_PARKED_ORDER_1: CFActiveOrder;
 export declare const MOCK_PARKED_ORDER_2: CFActiveOrder;
 export declare const MOCK_USERS: import("@final-commerce/common/pos-types").ActiveUser[];