@final-commerce/command-frame 0.4.0-preprod.1 → 0.4.0-staging.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 (5), 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 (4), 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,21 +171,13 @@ 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/add-product-to-cart/types.d.ts

@@ -3,7 +3,19 @@ import type { AddProductFeeParams } from "../add-product-fee/types";
 export interface AddProductToCartParams {
     /** ID of the variant to add. */
     variantId: string;
-    /** Defaults to 1. */
+    /**
+     * Defaults to 1. **May be fractional** — a variant sold by weight, volume or length is priced
+     * per its own unit and keyed in that unit, so `0.456` kg is a quantity, not a typo.
+     *
+     * How many decimals are allowed is the variant's own business: `variant.unit.precision` —
+     * `3` for a litre, `0` for anything sold by the piece. The engine refuses a quantity finer
+     * than that and says which unit it was measured against; do not round, floor or clamp before
+     * sending, and never key a quantity in base units to work around it (a per-100g price with a
+     * gram count is explicitly not supported).
+     *
+     * A quantity field should take its step and its decimal count from `variant.unit.precision`,
+     * not from a constant.
+     */
     quantity?: number;
     /** Array of discounts to apply immediately. */
     discounts?: AddProductDiscountParams[];

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

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

@@ -1,11 +1,9 @@
 import type { CFStatePair, CFTransitionResult } from "../../common-types/order-state";
 export interface ApplyTransitionParams {
-    /** 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;
+    /** Order to transition. */
+    orderId: string;
+    /** Target state pair. */
+    to: CFStatePair;
 }
 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 landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
-    targetFulfillmentState?: string;
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: 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,8 +1,6 @@
-import type { GetAvailableTransitions } from "./types";
+import type { GetAvailableTransitionsParams, GetAvailableTransitionsResponse } from "./types";
 /**
  * Mock implementation: returns a fixed set of plausible transitions
- * 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.
+ * so the demo app has data to render.
  */
-export declare const getAvailableTransitionsMock: GetAvailableTransitions;
+export declare const getAvailableTransitionsMock: (_params: GetAvailableTransitionsParams) => Promise<GetAvailableTransitionsResponse>;

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

@@ -1,38 +1,26 @@
 /**
  * Mock implementation: returns a fixed set of plausible transitions
- * 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.
+ * so the demo app has data to render.
  */
-export const getAvailableTransitionsMock = () => Promise.resolve({
+export const getAvailableTransitionsMock = async (_params) => ({
     transitions: [
         {
-            to: { payment: "unpaid", fulfillment: "in_progress" },
-            displayLabel: "Start Preparing",
-            conditions: [{ met: true, description: "Order has items" }]
+            to: { payment: "refunded", fulfillment: "returned" },
+            displayLabel: "Full 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: "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)" }
-            ]
-        }
-    ]
+                { met: false, description: "No payments captured (mock: skipped)" },
+            ],
+        },
+    ],
 });

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

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

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

@@ -12,8 +12,6 @@ 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 landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
-    targetFulfillmentState?: string;
+    paymentType?: 'Bluetooth' | 'Cloud';
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: string;
 }
 export interface TerminalPaymentResponse {
     success: boolean;

package/dist/actions/update-cart-item-quantity/types.d.ts

@@ -1,7 +1,14 @@
 export interface UpdateCartItemQuantityParams {
     /** The unique identifier for the specific cart item to update. */
     internalId: string;
-    /** The new quantity. If set to 0, the item will be removed from the cart. */
+    /**
+     * The new quantity. If set to 0, the item will be removed from the cart.
+     *
+     * **May be fractional** for a variant sold by measure; the number of decimals allowed comes
+     * from `variant.unit.precision`. The engine refuses anything finer and names the unit in the
+     * error. Do not round or clamp before sending — a silently altered quantity is charged and
+     * deducted differently than the one the cashier typed.
+     */
     quantity: number;
 }
 export interface UpdateCartItemQuantityResponse {

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,7 +51,6 @@ 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[];