@final-commerce/command-frame 0.5.0-preprod.8 → 0.5.0

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-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

@@ -1,6 +1,29 @@
 export interface GetRefundPlanParams {
     /** Order to inspect; defaults to the active order. */
     orderId?: string;
+    /**
+     * The selection to allocate — the SAME array you will pass to
+     * `processPartialRefund({ items })`, so the plan you render and the refund
+     * you submit are computed from one input.
+     *
+     * A flow that owns its own refund UI holds the selection in its own state and
+     * never stages it on the POS, so without this there is nothing for the engine
+     * to allocate. Pass it here on every selection change to get the matching
+     * {@link RefundPlanAllocation} back. **Purely a read** — unlike
+     * `processPartialRefund`, this never stages the selection or touches POS
+     * state, so it is safe to call as the cashier ticks rows.
+     *
+     * Omit it to fall back to the selection already staged on the POS (what
+     * `selectAllRefundItems` sets) — the in-POS modal's path. Omitted with
+     * nothing staged, no `allocation` comes back.
+     */
+    items?: {
+        /** `internalId` / `variantId` for a product, `customSaleId`, cart-fee id, or tip `transactionId`. */
+        itemKey: string;
+        quantity: number;
+        /** Optional hint; inferred from the order when omitted. */
+        type?: 'product' | 'customSale' | 'fee' | 'tip';
+    }[];
 }
 export interface RefundPlanSource {
     transactionId: string;
@@ -29,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
@@ -47,9 +81,10 @@ export interface RefundPlanLeg {
  * order's captures — what a flow renders and submits instead of computing a
  * split of its own.
  *
- * Present only when a refund selection exists on the ACTIVE order (i.e. after
- * `selectAllRefundItems` / `setRefundItemQuantity`); omitted for a pure
- * capacity read of some other order.
+ * Present when the call carries a selection: either `params.items` (a flow
+ * holding its own selection — the usual case) or a selection already staged on
+ * the POS for the active order (`selectAllRefundItems`). Omitted for a bare
+ * capacity read with neither.
  */
 export interface RefundPlanAllocation {
     /**

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.8",
+  "version": "0.5.0",
   "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",