@final-commerce/command-frame 0.5.0-preprod.9 → 0.5.1

package/README.md

@@ -10,14 +10,16 @@ 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)     |
-| **Refund commands** | Refund payments to gift cards or redeem tenders via `redeemRefund`, or mixed-destination legs on `processPartialRefund`; query engine capacity with `getRefundPlan`; pre-gate UI with `checkPermission` (`issue_refunds` is enforced runtime-side) | Request/response per call                 |
+| 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) |
+| **Refund commands** | Refund payments to gift cards or redeem tenders via `redeemRefund`, or mixed-destination legs on `processPartialRefund`; query engine capacity with `getRefundPlan`; pre-gate UI with `checkPermission` (`issue_refunds` is enforced runtime-side) | Request/response per call             |
 
 Domain models (orders, cart, customers, products, and related types) are documented in **[Types reference](./src/types/README.md)**.
 
+The order lifecycle — payment × fulfillment state pairs, display labels, the transition guard chain, and the financial invariants — is documented in **[Order state machine reference](./docs/order-state-machine.md)**. Read it before building anything that reads or moves order state (`canTransition`, `getAvailableTransitions`, `applyTransition`, park/void/resume, payments, refunds).
+
 ## Installation
 
 ### From npm (public registry)

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

@@ -1,18 +1,21 @@
 import { MOCK_CART, mockPublishEvent } from "../../demo/database";
+import { percentToFraction, requireMinorUnitsInteger } from "../../demo/units";
 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);
+        // FI-6991: a fixed amount arrives as an INTEGER in MINOR units (500 =
+        // $5.00) and is stored directly; a percent arrives raw (50 = 50%) and is
+        // stored as a fraction (0.5). Same as the real handler.
+        const value = params.isPercent
+            ? percentToFraction(params.amount)
+            : requireMinorUnitsInteger(params.amount, "Discount amount");
         MOCK_CART.discount = {
             value,
             isPercent: params.isPercent,
             label: params.label
         };
         if (params.isPercent) {
-            MOCK_CART.total = MOCK_CART.subtotal * (1 - params.amount / 100);
+            MOCK_CART.total = MOCK_CART.subtotal * (1 - value);
         }
         else {
             MOCK_CART.total = MOCK_CART.subtotal - value;

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

@@ -1,13 +1,16 @@
 import { MOCK_CART } from "../../demo/database";
+import { percentToFraction, requireMinorUnitsInteger } from "../../demo/units";
 export const mockAddCartFee = async (params) => {
     console.log("[Mock] addCartFee called", 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);
+        // FI-6991: a fixed amount arrives as an INTEGER in MINOR units (500 =
+        // $5.00) and is stored directly; a percent arrives raw (50 = 50%) and is
+        // stored as a fraction (0.5). Same as the real handler.
+        const storedAmount = params.isPercent
+            ? percentToFraction(params.amount)
+            : requireMinorUnitsInteger(params.amount, "Fee amount");
         MOCK_CART.customFee.push({
             label: params.label || "Fee",
             amount: storedAmount,
@@ -15,7 +18,7 @@ export const mockAddCartFee = async (params) => {
             applyTaxes: params.applyTaxes || false,
             taxTableId: params.taxTableId
         });
-        const feeAmount = params.isPercent ? MOCK_CART.subtotal * (params.amount / 100) : storedAmount;
+        const feeAmount = params.isPercent ? MOCK_CART.subtotal * storedAmount : 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,14 +1,14 @@
 import { MOCK_CART, mockPublishEvent } from '../../demo/database';
+import { requireMinorUnitsInteger } from '../../demo/units';
 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);
-    // 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);
+    // FI-6991: price arrives as an INTEGER in MINOR units (500 = $5.00) and is
+    // stored directly — the engine throws on a fraction, so the mock does too.
+    const price = requireMinorUnitsInteger(params.price, 'price');
     const quantity = params.quantity ?? 1;
     const customSale = {
         id: mockId,

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

@@ -1,4 +1,5 @@
 import { MOCK_CART, mockPublishEvent } from '../../demo/database';
+import { requireMinorUnitsInteger } from '../../demo/units';
 export const mockEditCustomSale = async (params) => {
     console.log('[Mock] editCustomSale called', params);
     if (!params)
@@ -13,10 +14,9 @@ export const mockEditCustomSale = async (params) => {
     if (params.label !== undefined)
         sale.name = params.label;
     if (params.price !== undefined) {
-        // 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);
-        sale.price = Math.round(Number(params.price) * minorFactor);
+        // FI-6991: price arrives as an INTEGER in MINOR units and is stored
+        // directly — the engine throws on a fraction, so the mock does too.
+        sale.price = requireMinorUnitsInteger(params.price, 'price');
     }
     if (params.quantity !== undefined)
         sale.quantity = params.quantity;

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

@@ -1,8 +1,13 @@
-import type { GetAvailableTransitions } from "./types";
+import type { GetAvailableTransitions } 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.
+ * default (empty cross-axis rules) config.
+ *
+ * FULFILLMENT-AXIS ONLY (common 2.1.4 contract): the payment axis never
+ * appears as an available transition — it moves exclusively through the
+ * money operations (pay / refund / void), which derive their own landing
+ * pairs. Every row keeps `to.payment` equal to the order's current payment
+ * state, exactly like the host's `getAvailableTransitions`.
  */
 export declare const getAvailableTransitionsMock: GetAvailableTransitions;

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

@@ -1,38 +1,38 @@
 /**
  * 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.
+ * default (empty cross-axis rules) config.
+ *
+ * FULFILLMENT-AXIS ONLY (common 2.1.4 contract): the payment axis never
+ * appears as an available transition — it moves exclusively through the
+ * money operations (pay / refund / void), which derive their own landing
+ * pairs. Every row keeps `to.payment` equal to the order's current payment
+ * state, exactly like the host's `getAvailableTransitions`.
  */
 export const getAvailableTransitionsMock = () => Promise.resolve({
     transitions: [
         {
-            to: { payment: "unpaid", fulfillment: "in_progress" },
-            displayLabel: "Start Preparing",
-            conditions: [{ met: true, description: "Order has items" }]
+            to: { payment: 'unpaid', fulfillment: 'in_progress' },
+            displayLabel: 'Start Preparing',
+            conditions: [{ met: true, description: 'Order has items' }],
         },
         {
-            to: { payment: "unpaid", fulfillment: "fulfilled" },
-            displayLabel: "Mark Fulfilled",
-            conditions: [{ met: true, description: "Order has items" }]
+            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: '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",
+            to: { payment: 'unpaid', fulfillment: 'cancelled' },
+            displayLabel: 'Cancel Order',
             conditions: [
-                { met: true, description: "Order exists" },
-                { met: false, description: "No payments captured (mock: skipped)" }
-            ]
-        }
-    ]
+                { met: true, description: 'Order exists' },
+                { met: false, description: 'No payments captured (mock: skipped)' },
+            ],
+        },
+    ],
 });

package/dist/actions/get-refund-plan/mock.js

@@ -58,6 +58,7 @@ export const mockGetRefundPlan = async (params) => {
         transactionId: s.transactionId,
         amount: s.maxRefundable,
         paymentType: s.paymentType,
+        requiresDestination: s.paymentType === 'redeem',
         requiresGiftCardDestination: s.paymentType === 'redeem',
     }));
     const budget = legs.reduce((sum, l) => sum + l.amount, 0);

package/dist/actions/get-refund-plan/types.d.ts

@@ -52,7 +52,18 @@ export interface RefundPlanLeg {
     amount: number;
     /** `cash` / `card` / `redeem` / etc., copied from the source. */
     paymentType: string;
-    /** True when the leg must carry a `giftCard` destination (a `redeem` source). */
+    /**
+     * True when the leg must carry a destination tender (a `redeem` source
+     * cannot be refunded to itself — the money needs somewhere to land, credited
+     * by the flow FIRST). The destination is usually a gift card but redeem is
+     * the general rail: loyalty and store-credit extensions ride it too.
+     */
+    requiresDestination: boolean;
+    /**
+     * @deprecated Same value as {@link RefundPlanLeg.requiresDestination} — the
+     * old name baked one extension (gift card) into a general redeem concept.
+     * Kept populated for existing callers; prefer `requiresDestination`.
+     */
     requiresGiftCardDestination: boolean;
     /**
      * Cash legs only: what the drawer actually pays after the company's

package/dist/actions/partial-payment/mock.js

@@ -1,4 +1,5 @@
 import { MOCK_CART, mockPublishEvent } from "../../demo/database";
+import { percentToFraction, requireMinorUnitsInteger } from "../../demo/units";
 export const mockPartialPayment = async (params) => {
     console.log("[Mock] partialPayment called", params);
     const openUI = params?.openUI ?? true;
@@ -18,10 +19,11 @@ export const mockPartialPayment = async (params) => {
     // untouched until the payment is actually taken (see applyMockPayment).
     const remaining = MOCK_CART.remainingBalance ?? MOCK_CART.total;
     const raw = params?.amount ?? 0;
-    // Mirror render: fixed amount is raw dollars (render does toMinorUnits), so
-    // convert to minor units here; percent is a percentage of the remaining total.
-    const minorFactor = 10 ** (MOCK_CART.minorUnits ?? 2);
-    const charge = params?.isPercent ? Math.round((remaining * raw) / 100) : Math.round(raw * minorFactor);
+    // FI-6991: a fixed amount is already an INTEGER in MINOR units and is used
+    // directly; a percent is raw 0-100 against the remaining total.
+    const charge = params?.isPercent
+        ? Math.round(remaining * percentToFraction(raw))
+        : requireMinorUnitsInteger(raw, "Payment amount");
     MOCK_CART.amountToBeCharged = Math.min(Math.max(0, charge), remaining);
     mockPublishEvent("cart", "partial-payment-set", { amountToBeCharged: MOCK_CART.amountToBeCharged });
     return {

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

@@ -1,2 +1,2 @@
-import { ProcessPartialRefund } from "./types";
+import { ProcessPartialRefund } from './types';
 export declare const mockProcessPartialRefund: ProcessPartialRefund;

package/dist/actions/process-partial-refund/mock.js

@@ -10,7 +10,7 @@ export const mockProcessPartialRefund = async (params) => {
     if (params?.legs && params?.giftCard) {
         throw new Error('refund.giftCardAndLegs: pass either `legs` (you allocate) or `giftCard` (the engine allocates), not both');
     }
-    console.log("[Mock] processPartialRefund called", {
+    console.log('[Mock] processPartialRefund called', {
         ...params,
         openUI: params?.openUI ?? true,
         legs: params?.legs ?? null,
@@ -19,6 +19,7 @@ export const mockProcessPartialRefund = async (params) => {
     return {
         success: true,
         refundId: 'mock_refund_' + Date.now(),
-        timestamp: new Date().toISOString()
+        modalRaised: false,
+        timestamp: new Date().toISOString(),
     };
 };

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

@@ -153,7 +153,25 @@ export interface ProcessPartialRefundParams {
 }
 export interface ProcessPartialRefundResponse {
     success: boolean;
-    refundId: string;
+    /**
+     * The persisted Refund document's id — the REAL one, usable to look the
+     * refund up. `null` means nothing has committed: the split-payment modal
+     * was raised (`modalRaised: true`) and owns the commit from there.
+     *
+     * Before kaching 1.9.5-preprod.17 this was the hardcoded string
+     * `'processed'` regardless of outcome, so a truthiness check could not
+     * detect a refund that silently didn't happen. Guard on it now:
+     * `if (!res.refundId && !res.modalRaised) …` is unreachable (such paths
+     * throw instead), so `res.refundId` alone answers "did money move".
+     */
+    refundId: string | null;
+    /**
+     * True when a multi-tender order raised the split-payment refund modal
+     * (`openUI` omitted or `true`): the cashier allocates there and the modal
+     * drives the commit — this call wrote nothing. Headless calls
+     * (`openUI: false`) never raise it.
+     */
+    modalRaised: boolean;
     timestamp: string;
 }
 export type ProcessPartialRefund = (params?: ProcessPartialRefundParams) => Promise<ProcessPartialRefundResponse>;

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

@@ -1,7 +1,10 @@
 import { MOCK_CART, mockPublishEvent } from "../../demo/database";
 function feeContributionToTotal(fee, subtotal) {
+    // A percent fee is STORED as a fraction (10% -> 0.1), so it scales the
+    // subtotal directly. Dividing by 100 again credited back a hundredth of the
+    // fee, leaving the total permanently inflated after a remove.
     if (fee.isPercent) {
-        return subtotal * (fee.amount / 100);
+        return subtotal * fee.amount;
     }
     return fee.amount;
 }

package/dist/demo/units.d.ts

@@ -0,0 +1,18 @@
+/**
+ * FI-6991 money contract, mirrored for the mock host.
+ *
+ * The POS engine a published build boots (kaching) takes every FIXED money
+ * amount as an INTEGER in MINOR currency units and stores it DIRECTLY, throwing
+ * on a fraction; a percent arrives raw 0-100 and is stored as a FRACTION
+ * (10 -> 0.1). See kaching's `src/command-frame/utils/adjustmentValue.ts`.
+ *
+ * The mocks used to convert fixed amounts from MAJOR units — the pre-FI-6991
+ * contract — so an app that was correct against a real register read 100x wrong
+ * in preview, and an app tuned until preview looked right shipped 100x wrong.
+ * A mock host is only worth having if it stores, and rejects, exactly what the
+ * engine does.
+ */
+/** A fixed money amount must be an integer count of minor units. */
+export declare function requireMinorUnitsInteger(amount: number | string, what: string): number;
+/** A percent arrives raw 0-100 on the wire and is STORED as a fraction. */
+export declare function percentToFraction(amount: number): number;

package/dist/demo/units.js

@@ -0,0 +1,29 @@
+/**
+ * FI-6991 money contract, mirrored for the mock host.
+ *
+ * The POS engine a published build boots (kaching) takes every FIXED money
+ * amount as an INTEGER in MINOR currency units and stores it DIRECTLY, throwing
+ * on a fraction; a percent arrives raw 0-100 and is stored as a FRACTION
+ * (10 -> 0.1). See kaching's `src/command-frame/utils/adjustmentValue.ts`.
+ *
+ * The mocks used to convert fixed amounts from MAJOR units — the pre-FI-6991
+ * contract — so an app that was correct against a real register read 100x wrong
+ * in preview, and an app tuned until preview looked right shipped 100x wrong.
+ * A mock host is only worth having if it stores, and rejects, exactly what the
+ * engine does.
+ */
+/** A fixed money amount must be an integer count of minor units. */
+export function requireMinorUnitsInteger(amount, what) {
+    const n = Number(amount);
+    if (!Number.isFinite(n)) {
+        throw new Error(`${what} must be a valid number`);
+    }
+    if (!Number.isInteger(n)) {
+        throw new Error(`${what} must be an integer amount in minor currency units (e.g. 1575 = $15.75)`);
+    }
+    return n;
+}
+/** A percent arrives raw 0-100 on the wire and is STORED as a fraction. */
+export function percentToFraction(amount) {
+    return Number(amount) / 100;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.5.0-preprod.9",
+  "version": "0.5.1",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -63,6 +63,7 @@
     "@commitlint/cli": "^19.0.0",
     "@commitlint/config-conventional": "^19.0.0",
     "@eslint/js": "^9.0.0",
+    "@vitest/coverage-v8": "^4.1.11",
     "eslint": "^9.0.0",
     "husky": "^9.1.7",
     "jira-prepare-commit-msg": "^1.7.2",