@final-commerce/command-frame 0.1.73 → 0.1.75

package/README.md

@@ -10,11 +10,12 @@ Command Frame provides a structured way to build integrations that run inside Fi
 
 The library provides three main capabilities:
 
-| Capability | Purpose | Scope |
-|-----------|---------|-------|
-| **Commands** | Call host functions from the iframe (e.g. get products, open cash drawer) | Request/response per call |
-| **Pub/Sub** | Subscribe to real-time events from the host (e.g. cart changes, payments) | Page-scoped (while iframe is mounted) |
-| **Hooks** | Register business-logic callbacks that persist across all pages | Session-scoped (survives page navigation) |
+| Capability                | Purpose                                                                                         | Scope                                          |
+| ------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| **Commands**              | Call host functions from the iframe (e.g. get products, open cash drawer)                       | Request/response per call                      |
+| **Pub/Sub**               | Subscribe to real-time events from the host (e.g. cart changes, payments)                       | Page-scoped (while iframe is mounted)          |
+| **Hooks**                 | Register business-logic callbacks that persist across all pages                                 | Session-scoped (survives page navigation)      |
+| **Interceptors**          | Gate POS flows (approve / modify / block) at named points                                       | Blocking; host waits for your response         |
 | **Host → iframe refunds** | Render asks the extension to reverse redeem / gift-card payments before completing a POS refund | Parent `postMessage` + `requestId` (see below) |
 
 Domain models (orders, cart, customers, products, and related types) are documented in **[Types reference](./src/types/README.md)**.
@@ -54,7 +55,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();
@@ -68,7 +69,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();
@@ -82,14 +83,14 @@ The pub/sub system allows iframe extensions to subscribe to topics and receive r
 - **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
@@ -101,17 +102,44 @@ 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';
-
-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' });
+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" }
+);
 
 // Unregister when no longer needed
-hooks.unregister('my-extension:cart-log');
+hooks.unregister("my-extension:cart-log");
+```
+
+## Interceptors
+
+Interceptors let an extension **gate a POS flow** (approve / modify / block) at a named point — the host waits for your interceptor and acts on what it returns. Unlike hooks, interceptors are **blocking**.
+
+- **[Interceptors Documentation](./src/interceptors/README.md)**
+- The callback is serialized and reconstructed on the host; it must be **self-contained** (no closures, no imports).
+- A stable `interceptorId` is required for deduplication (safe on iframe reload).
+
+```typescript
+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' }
+);
 ```
 
 ## Host-initiated extension refunds (redeem / gift card)
@@ -127,18 +155,12 @@ hooks.unregister('my-extension:cart-log');
 Exported APIs: `installExtensionRefundListener`, `EXTENSION_REFUND_REQUEST_ACTION`, types **`ExtensionRefundParams`** / **`ExtensionRefundResponse`**.
 
 ```typescript
-import {
-    installExtensionRefundListener,
-    type ExtensionRefundParams,
-    type ExtensionRefundResponse
-} from '@final-commerce/command-frame';
+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)

package/dist/CommonTypes.d.ts

@@ -27,6 +27,107 @@ export declare enum CurrencyCode {
     ILS = "ILS",
     TRY = "TRY",
     RUB = "RUB",
+    HTG = "HTG",
+    BND = "BND",
+    CRC = "CRC",
+    BDT = "BDT",
+    UAH = "UAH",
+    NGN = "NGN",
+    AFN = "AFN",
+    ALL = "ALL",
+    AMD = "AMD",
+    ANG = "ANG",
+    AOA = "AOA",
+    ARS = "ARS",
+    AWG = "AWG",
+    AZN = "AZN",
+    BAM = "BAM",
+    BBD = "BBD",
+    BGN = "BGN",
+    BMD = "BMD",
+    BOB = "BOB",
+    BSD = "BSD",
+    BTN = "BTN",
+    BWP = "BWP",
+    BYN = "BYN",
+    BZD = "BZD",
+    COP = "COP",
+    CZK = "CZK",
+    DOP = "DOP",
+    DZD = "DZD",
+    EGP = "EGP",
+    ETB = "ETB",
+    FJD = "FJD",
+    GEL = "GEL",
+    GHS = "GHS",
+    GTQ = "GTQ",
+    GYD = "GYD",
+    HNL = "HNL",
+    IRR = "IRR",
+    JMD = "JMD",
+    KES = "KES",
+    KGS = "KGS",
+    KHR = "KHR",
+    KYD = "KYD",
+    KZT = "KZT",
+    LAK = "LAK",
+    LBP = "LBP",
+    LKR = "LKR",
+    MAD = "MAD",
+    MDL = "MDL",
+    MKD = "MKD",
+    MMK = "MMK",
+    MNT = "MNT",
+    MOP = "MOP",
+    MUR = "MUR",
+    MVR = "MVR",
+    MZN = "MZN",
+    NAD = "NAD",
+    NIO = "NIO",
+    NPR = "NPR",
+    PAB = "PAB",
+    PEN = "PEN",
+    PGK = "PGK",
+    PKR = "PKR",
+    QAR = "QAR",
+    RON = "RON",
+    RSD = "RSD",
+    SBD = "SBD",
+    SRD = "SRD",
+    SYP = "SYP",
+    TJS = "TJS",
+    TMT = "TMT",
+    TOP = "TOP",
+    TTD = "TTD",
+    TZS = "TZS",
+    UYU = "UYU",
+    UZS = "UZS",
+    VES = "VES",
+    WST = "WST",
+    XCD = "XCD",
+    YER = "YER",
+    ZMW = "ZMW",
+    CDF = "CDF",
+    CUP = "CUP",
+    ERN = "ERN",
+    FKP = "FKP",
+    GIP = "GIP",
+    GMD = "GMD",
+    KPW = "KPW",
+    LRD = "LRD",
+    LSL = "LSL",
+    MGA = "MGA",
+    MWK = "MWK",
+    SCR = "SCR",
+    SDG = "SDG",
+    SHP = "SHP",
+    SLE = "SLE",
+    SOS = "SOS",
+    SSP = "SSP",
+    STN = "STN",
+    SZL = "SZL",
+    VED = "VED",
+    XCG = "XCG",
     JPY = "JPY",
     KRW = "KRW",
     VND = "VND",
@@ -34,6 +135,17 @@ export declare enum CurrencyCode {
     ISK = "ISK",
     HUF = "HUF",
     TWD = "TWD",
+    GNF = "GNF",
+    BIF = "BIF",
+    DJF = "DJF",
+    KMF = "KMF",
+    PYG = "PYG",
+    RWF = "RWF",
+    UGX = "UGX",
+    VUV = "VUV",
+    XAF = "XAF",
+    XOF = "XOF",
+    XPF = "XPF",
     KWD = "KWD",
     BHD = "BHD",
     OMR = "OMR",
@@ -255,7 +367,7 @@ export interface CFActiveProduct extends CFActiveEntity {
 }
 export interface CFCustomer {
     _id: string;
-    companyId: any;
+    companyId: string;
     externalId?: string;
     email: string;
     firstName: string;
@@ -440,8 +552,7 @@ export interface CFRefundedLineItem {
     images?: string[];
     fee: CFFeeLineItem;
 }
-export interface CFRefundedCustomSale extends CFCustomSale {
-}
+export type CFRefundedCustomSale = CFCustomSale;
 export interface CFRefundItem {
     lineItems: CFRefundedLineItem[];
     customSales: CFRefundedCustomSale[];
@@ -464,6 +575,12 @@ export interface CFOrder {
     companyId: string;
     externalId: string | null;
     status: string;
+    /** Financial state (state machine). Undefined on legacy orders pre-backfill. */
+    paymentState?: string;
+    /** Operational state (state machine). Undefined on legacy orders pre-backfill. */
+    fulfillmentState?: string;
+    /** Computed display label from paymentState + fulfillmentState matrix. */
+    displayState?: string;
     customer: Partial<CFActiveCustomer | null>;
     customerNote?: string;
     summary: CFSummary;
@@ -521,7 +638,7 @@ export interface CFActiveUser extends CFActiveEntity {
         _id: string;
     }[];
     type?: CFUserTypes;
-    companies?: any;
+    companies?: unknown;
 }
 export interface CFActiveOutlet extends CFActiveEntity {
     address: string;
@@ -607,8 +724,8 @@ export interface CFActiveCustomSales {
     taxTableId?: string;
     quantity: number;
     price: number;
-    discount?: any;
-    fee?: any;
+    discount?: Record<string, unknown>;
+    fee?: Record<string, unknown>;
 }
 /** Non-revenue cart line (e.g. gift card load) — aligned with Render `NonRevenueItem.externalId` (order line id). */
 export interface CFNonRevenueItem {
@@ -660,7 +777,7 @@ export interface CFActiveCompany extends CFActiveEntity {
     id?: string;
     name?: string;
     logo?: string;
-    settings?: any;
+    settings?: Record<string, unknown>;
 }
 export type CFProjectName = "Render" | "Manage";
 export interface CFContextRender {

package/dist/CommonTypes.js

@@ -28,6 +28,107 @@ export var CurrencyCode;
     CurrencyCode["ILS"] = "ILS";
     CurrencyCode["TRY"] = "TRY";
     CurrencyCode["RUB"] = "RUB";
+    CurrencyCode["HTG"] = "HTG";
+    CurrencyCode["BND"] = "BND";
+    CurrencyCode["CRC"] = "CRC";
+    CurrencyCode["BDT"] = "BDT";
+    CurrencyCode["UAH"] = "UAH";
+    CurrencyCode["NGN"] = "NGN";
+    CurrencyCode["AFN"] = "AFN";
+    CurrencyCode["ALL"] = "ALL";
+    CurrencyCode["AMD"] = "AMD";
+    CurrencyCode["ANG"] = "ANG";
+    CurrencyCode["AOA"] = "AOA";
+    CurrencyCode["ARS"] = "ARS";
+    CurrencyCode["AWG"] = "AWG";
+    CurrencyCode["AZN"] = "AZN";
+    CurrencyCode["BAM"] = "BAM";
+    CurrencyCode["BBD"] = "BBD";
+    CurrencyCode["BGN"] = "BGN";
+    CurrencyCode["BMD"] = "BMD";
+    CurrencyCode["BOB"] = "BOB";
+    CurrencyCode["BSD"] = "BSD";
+    CurrencyCode["BTN"] = "BTN";
+    CurrencyCode["BWP"] = "BWP";
+    CurrencyCode["BYN"] = "BYN";
+    CurrencyCode["BZD"] = "BZD";
+    CurrencyCode["COP"] = "COP";
+    CurrencyCode["CZK"] = "CZK";
+    CurrencyCode["DOP"] = "DOP";
+    CurrencyCode["DZD"] = "DZD";
+    CurrencyCode["EGP"] = "EGP";
+    CurrencyCode["ETB"] = "ETB";
+    CurrencyCode["FJD"] = "FJD";
+    CurrencyCode["GEL"] = "GEL";
+    CurrencyCode["GHS"] = "GHS";
+    CurrencyCode["GTQ"] = "GTQ";
+    CurrencyCode["GYD"] = "GYD";
+    CurrencyCode["HNL"] = "HNL";
+    CurrencyCode["IRR"] = "IRR";
+    CurrencyCode["JMD"] = "JMD";
+    CurrencyCode["KES"] = "KES";
+    CurrencyCode["KGS"] = "KGS";
+    CurrencyCode["KHR"] = "KHR";
+    CurrencyCode["KYD"] = "KYD";
+    CurrencyCode["KZT"] = "KZT";
+    CurrencyCode["LAK"] = "LAK";
+    CurrencyCode["LBP"] = "LBP";
+    CurrencyCode["LKR"] = "LKR";
+    CurrencyCode["MAD"] = "MAD";
+    CurrencyCode["MDL"] = "MDL";
+    CurrencyCode["MKD"] = "MKD";
+    CurrencyCode["MMK"] = "MMK";
+    CurrencyCode["MNT"] = "MNT";
+    CurrencyCode["MOP"] = "MOP";
+    CurrencyCode["MUR"] = "MUR";
+    CurrencyCode["MVR"] = "MVR";
+    CurrencyCode["MZN"] = "MZN";
+    CurrencyCode["NAD"] = "NAD";
+    CurrencyCode["NIO"] = "NIO";
+    CurrencyCode["NPR"] = "NPR";
+    CurrencyCode["PAB"] = "PAB";
+    CurrencyCode["PEN"] = "PEN";
+    CurrencyCode["PGK"] = "PGK";
+    CurrencyCode["PKR"] = "PKR";
+    CurrencyCode["QAR"] = "QAR";
+    CurrencyCode["RON"] = "RON";
+    CurrencyCode["RSD"] = "RSD";
+    CurrencyCode["SBD"] = "SBD";
+    CurrencyCode["SRD"] = "SRD";
+    CurrencyCode["SYP"] = "SYP";
+    CurrencyCode["TJS"] = "TJS";
+    CurrencyCode["TMT"] = "TMT";
+    CurrencyCode["TOP"] = "TOP";
+    CurrencyCode["TTD"] = "TTD";
+    CurrencyCode["TZS"] = "TZS";
+    CurrencyCode["UYU"] = "UYU";
+    CurrencyCode["UZS"] = "UZS";
+    CurrencyCode["VES"] = "VES";
+    CurrencyCode["WST"] = "WST";
+    CurrencyCode["XCD"] = "XCD";
+    CurrencyCode["YER"] = "YER";
+    CurrencyCode["ZMW"] = "ZMW";
+    CurrencyCode["CDF"] = "CDF";
+    CurrencyCode["CUP"] = "CUP";
+    CurrencyCode["ERN"] = "ERN";
+    CurrencyCode["FKP"] = "FKP";
+    CurrencyCode["GIP"] = "GIP";
+    CurrencyCode["GMD"] = "GMD";
+    CurrencyCode["KPW"] = "KPW";
+    CurrencyCode["LRD"] = "LRD";
+    CurrencyCode["LSL"] = "LSL";
+    CurrencyCode["MGA"] = "MGA";
+    CurrencyCode["MWK"] = "MWK";
+    CurrencyCode["SCR"] = "SCR";
+    CurrencyCode["SDG"] = "SDG";
+    CurrencyCode["SHP"] = "SHP";
+    CurrencyCode["SLE"] = "SLE";
+    CurrencyCode["SOS"] = "SOS";
+    CurrencyCode["SSP"] = "SSP";
+    CurrencyCode["STN"] = "STN";
+    CurrencyCode["SZL"] = "SZL";
+    CurrencyCode["VED"] = "VED";
+    CurrencyCode["XCG"] = "XCG";
     CurrencyCode["JPY"] = "JPY";
     CurrencyCode["KRW"] = "KRW";
     CurrencyCode["VND"] = "VND";
@@ -35,6 +136,17 @@ export var CurrencyCode;
     CurrencyCode["ISK"] = "ISK";
     CurrencyCode["HUF"] = "HUF";
     CurrencyCode["TWD"] = "TWD";
+    CurrencyCode["GNF"] = "GNF";
+    CurrencyCode["BIF"] = "BIF";
+    CurrencyCode["DJF"] = "DJF";
+    CurrencyCode["KMF"] = "KMF";
+    CurrencyCode["PYG"] = "PYG";
+    CurrencyCode["RWF"] = "RWF";
+    CurrencyCode["UGX"] = "UGX";
+    CurrencyCode["VUV"] = "VUV";
+    CurrencyCode["XAF"] = "XAF";
+    CurrencyCode["XOF"] = "XOF";
+    CurrencyCode["XPF"] = "XPF";
     CurrencyCode["KWD"] = "KWD";
     CurrencyCode["BHD"] = "BHD";
     CurrencyCode["OMR"] = "OMR";

package/dist/actions/add-cart-discount/mock.js

@@ -2,17 +2,20 @@ import { MOCK_CART, mockPublishEvent } from "../../demo/database";
 export const mockAddCartDiscount = async (params) => {
     console.log("[Mock] addCartDiscount called", params);
     if (params) {
+        // Mirror render: input is raw (50 = 50%, 5 = $5). Store percent as a
+        // fraction (0.5) and fixed as minor units (500), like the real handler.
+        const minorFactor = 10 ** (MOCK_CART.minorUnits ?? 2);
+        const value = params.isPercent ? params.amount / 100 : Math.round(params.amount * minorFactor);
         MOCK_CART.discount = {
-            value: params.amount,
+            value,
             isPercent: params.isPercent,
             label: params.label
         };
-        // Simple mock calc (not real logic)
         if (params.isPercent) {
             MOCK_CART.total = MOCK_CART.subtotal * (1 - params.amount / 100);
         }
         else {
-            MOCK_CART.total = MOCK_CART.subtotal - params.amount;
+            MOCK_CART.total = MOCK_CART.subtotal - value;
         }
         MOCK_CART.amountToBeCharged = MOCK_CART.total;
         MOCK_CART.remainingBalance = MOCK_CART.total;

package/dist/actions/add-cart-fee/mock.js

@@ -4,18 +4,18 @@ export const mockAddCartFee = async (params) => {
     if (params) {
         if (!MOCK_CART.customFee)
             MOCK_CART.customFee = [];
+        // Mirror render: input is raw (50 = 50%, 5 = $5). Store percent as a
+        // fraction (0.5) and fixed as minor units (500), like the real handler.
+        const minorFactor = 10 ** (MOCK_CART.minorUnits ?? 2);
+        const storedAmount = params.isPercent ? params.amount / 100 : Math.round(params.amount * minorFactor);
         MOCK_CART.customFee.push({
             label: params.label || "Fee",
-            amount: params.amount,
+            amount: storedAmount,
             isPercent: params.isPercent || false,
             applyTaxes: params.applyTaxes || false,
             taxTableId: params.taxTableId
         });
-        // Simple calc
-        let feeAmount = params.amount;
-        if (params.isPercent) {
-            feeAmount = MOCK_CART.subtotal * (params.amount / 100);
-        }
+        const feeAmount = params.isPercent ? MOCK_CART.subtotal * (params.amount / 100) : storedAmount;
         MOCK_CART.total += feeAmount;
         MOCK_CART.amountToBeCharged = MOCK_CART.total;
         MOCK_CART.remainingBalance = MOCK_CART.total;

package/dist/actions/add-custom-sale/mock.js

@@ -1,11 +1,14 @@
-import { MOCK_CART } from "../../demo/database";
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
 export const mockAddCustomSale = async (params) => {
     console.log("[Mock] addCustomSale called", params);
     if (!params)
         throw new Error("Params required");
     // Simple mock ID generation
     const mockId = 'sale_' + Math.random().toString(36).substr(2, 9);
-    const price = Number(params.price);
+    // Mirror render: the flow sends raw dollars ($4); render does toMinorUnits.
+    // MOCK_CART tracks minor units, so convert here too.
+    const minorFactor = 10 ** (MOCK_CART.minorUnits ?? 2);
+    const price = Math.round(Number(params.price) * minorFactor);
     const quantity = 1; // Default to 1 for custom sale usually
     const customSale = {
         id: mockId,
@@ -24,6 +27,8 @@ export const mockAddCustomSale = async (params) => {
     MOCK_CART.total += price * quantity;
     MOCK_CART.amountToBeCharged = MOCK_CART.total;
     MOCK_CART.remainingBalance = MOCK_CART.total;
+    // Publish custom-sale-added event so cart subscribers refresh
+    mockPublishEvent('cart', 'custom-sale-added', { customSale });
     return {
         success: true,
         customSaleId: mockId,

package/dist/actions/add-order-note/mock.js

@@ -1,4 +1,4 @@
-import { MOCK_CART } from "../../demo/database";
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
 export const mockAddOrderNote = async (params) => {
     console.log("[Mock] addOrderNote called", params);
     // In Render, AddOrderNote usually adds a note to the active cart if it's not checked out yet.
@@ -9,6 +9,8 @@ export const mockAddOrderNote = async (params) => {
         else {
             MOCK_CART.orderNotes = params.note;
         }
+        // Publish order-note-added event so cart subscribers refresh.
+        mockPublishEvent("cart", "order-note-added", { note: params.note });
     }
     return {
         success: true,

package/dist/actions/add-product-discount/mock.js

@@ -1,4 +1,4 @@
-import { MOCK_CART } from "../../demo/database";
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
 export const mockAddProductDiscount = async (params) => {
     console.log("[Mock] addProductDiscount called", params);
     if (params && (params.amount > 0 || params.amount < 0)) { // Allow 0 to clear discount if logic permits
@@ -10,13 +10,20 @@ export const mockAddProductDiscount = async (params) => {
             item = MOCK_CART.products[MOCK_CART.products.length - 1];
         }
         if (item) {
+            // Mirror render's product handler: it stores `amount` AS-IS — the flow
+            // already sends a fraction (0.5 = 50%) for percent and minor units (500 = $5)
+            // for fixed. tax.ts then uses value as the fraction / minor amount directly.
             item.discount = {
                 value: params.amount,
                 isPercent: params.isPercent || false,
                 label: params.label
             };
-            // Recalculate cart totals (simplified)
-            // Ideally, this should trigger a full recalculation function
+            const linePrice = (item.price || 0) * (item.quantity || 1);
+            const discountMinor = params.isPercent ? Math.round(linePrice * params.amount) : params.amount;
+            MOCK_CART.total = Math.max(0, MOCK_CART.total - discountMinor);
+            MOCK_CART.amountToBeCharged = MOCK_CART.total;
+            MOCK_CART.remainingBalance = MOCK_CART.total;
+            mockPublishEvent("cart", "product-discount-added", { internalId: params.internalId });
         }
     }
     return {

package/dist/actions/add-product-fee/mock.js

@@ -1,4 +1,4 @@
-import { MOCK_CART } from "../../demo/database";
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
 export const mockAddProductFee = async (params) => {
     console.log("[Mock] addProductFee called", params);
     if (params) {
@@ -10,12 +10,21 @@ export const mockAddProductFee = async (params) => {
             item = MOCK_CART.products[MOCK_CART.products.length - 1];
         }
         if (item) {
+            // Mirror render's product handler: it stores `amount` AS-IS — the flow
+            // already sends a fraction (0.5 = 50%) for percent and minor units (500 = $5)
+            // for fixed. tax.ts then uses amount as the fraction / minor amount directly.
             item.fee = {
                 label: params.label || "Fee",
                 amount: params.amount,
                 isPercent: params.isPercent || false,
                 applyTaxes: params.applyTaxes || false
             };
+            const linePrice = (item.price || 0) * (item.quantity || 1);
+            const feeMinor = params.isPercent ? Math.round(linePrice * params.amount) : params.amount;
+            MOCK_CART.total += feeMinor;
+            MOCK_CART.amountToBeCharged = MOCK_CART.total;
+            MOCK_CART.remainingBalance = MOCK_CART.total;
+            mockPublishEvent("cart", "product-fee-added", { internalId: params.internalId });
         }
     }
     return {

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

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

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

@@ -0,0 +1,4 @@
+import { commandFrameClient } from "../../client";
+export const applyTransition = async (params) => {
+    return await commandFrameClient.call("applyTransition", params);
+};

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

@@ -0,0 +1,6 @@
+import type { ApplyTransitionParams, ApplyTransitionResponse } from "./types";
+/**
+ * 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

@@ -0,0 +1,33 @@
+/**
+ * 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 { to } = params;
+    if (to.payment === "refunded" && to.fulfillment === "draft") {
+        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"
+            }
+        });
+    }
+    return Promise.resolve({
+        result: { allowed: true },
+        from: { payment: "unpaid", fulfillment: "draft" },
+        to,
+        displayState: `${to.payment} / ${to.fulfillment}`
+    });
+};

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

@@ -0,0 +1,17 @@
+import type { CFStatePair, CFTransitionResult } from "../../common-types/order-state";
+export interface ApplyTransitionParams {
+    /** Order to transition. */
+    orderId: string;
+    /** Target state pair. */
+    to: CFStatePair;
+}
+export interface ApplyTransitionResponse {
+    result: CFTransitionResult;
+    /** Previous state — present only when the transition was applied. */
+    from?: CFStatePair;
+    /** New state — present only when the transition was applied. */
+    to?: CFStatePair;
+    /** Computed display label — present only when the transition was applied. */
+    displayState?: string;
+}
+export type ApplyTransition = (params: ApplyTransitionParams) => Promise<ApplyTransitionResponse>;

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

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

package/dist/actions/can-transition/action.d.ts

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