@final-commerce/command-frame 0.4.2-preprod.1 → 0.5.0-preprod.10

package/README.md

@@ -4,7 +4,7 @@ A TypeScript library for type-safe communication between iframes and their paren
 
 ## Overview
 
-Command Frame provides a structured way to build integrations that run inside Final Commerce applications (like Render POS or Manage Dashboard). It handles the underlying `postMessage` communication while enforcing strict type safety for both the host application (Provider) and the embedded app (Client).
+Command Frame provides a structured way to build integrations that run inside Final Commerce applications (the kaching POS runtime or the Manage Dashboard). It handles the underlying `postMessage` communication while enforcing strict type safety for both the host application (Provider) and the embedded app (Client).
 
 `RenderClient` and `ManageClient` extend `CommandFrameClient`: dynamic methods such as `getProducts()` map to `postMessage` actions named after the method (camelCase), with typed params and responses per project.
 
@@ -14,8 +14,6 @@ The library provides three main capabilities:
 | ------------------- | ------------------------------------------------------------------------- | ----------------------------------------- |
 | **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    |
 | **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)**.
@@ -65,7 +63,7 @@ true` → `amount` is `0–100`), and quantities.
 
 ### Render (POS System)
 
-For building applications that run inside the Render Point of Sale interface.
+For building applications that run inside the Final Commerce POS (the kaching runtime).
 
 - **[Render Documentation](./src/projects/render/README.md)**
 - **Features:** Order management, Product catalog, Customer management, Payments, Hardware integration (Cash drawer, Printer), Custom tables, Secrets storage.
@@ -93,10 +91,10 @@ const context = await client.getContext();
 
 ## Pub/Sub
 
-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.
+The pub/sub system allows iframe extensions to subscribe to topics and receive real-time events published by the POS host (kaching). 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 (7), Payments (2), Products (4), Refunds (4), Print (3), Custom Tables (3), Outlet (2), Station (2), Session (2), Users (4), Variants (2), Transactions (2), Categories (2), Attributes (2), Split Payments (1).
 
 ```typescript
 import { topics } from '@final-commerce/command-frame';
@@ -109,55 +107,6 @@ const subscriptionId = topics.subscribe('cart', (event) => {
 topics.unsubscribe('cart', subscriptionId);
 ```
 
-## Hooks
-
-Hooks are **session-scoped** event callbacks that run in the host (Render) context and persist across all page navigations -- even when the extension iframe is no longer on the current page. Use hooks for business logic that must run on every event (e.g. logging to custom tables, triggering webhooks).
-
-- **[Hooks Documentation](./src/hooks/README.md)**
-- The callback is serialized and sent to the host; it must be **self-contained** (no closures, no imports).
-- 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' },
-);
-
-// Unregister when no longer needed
-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' },
-);
-```
-
 ## Refunding redeem / extension payments
 
 When staff refund an order that was paid with `paymentType: "redeem"` (via `redeemPayment` or `extensionPayment`), use the **`redeemRefund`** command to refund the amount onto a gift card or redeem tender.

package/dist/CommonTypes.d.ts

@@ -96,7 +96,7 @@ export interface CFActiveRefundDetails {
     refundProcessingStatus?: CFRefundProcessingStatus | null;
     sessionRefundedTotal?: number;
 }
-export type CFProjectName = "Render" | "Manage";
+export type CFProjectName = "kaching" | "Manage";
 export interface CFContextRender {
     userId: string | null;
     companyId: string | null;

package/dist/actions/add-product-fee/types.d.ts

@@ -5,9 +5,8 @@ export interface AddProductFeeParams {
     isPercent?: boolean;
     /** Defaults to "Fee". */
     label?: string;
-    /** Defaults to `false`. */
+    /** Defaults to `false`. When true, the fee inherits the target cart line's own tax table (a caller-supplied tax table is not honored). */
     applyTaxes?: boolean;
-    taxTableId?: string;
     /** The unique identifier for a specific line item in the cart. */
     internalId?: string;
 }

package/dist/actions/adjust-inventory/mock.js

@@ -2,29 +2,33 @@ import { MOCK_PRODUCTS } from "../../demo/database";
 export const mockAdjustInventory = async (params) => {
     console.log("[Mock] adjustInventory called", params);
     let newStock = 0;
-    if (params && params.productId) {
-        const product = MOCK_PRODUCTS.find(p => p._id === params.productId);
-        if (product) {
-            // Find variant
-            const variant = params.variantId
-                ? product.variants.find(v => v._id === params.variantId)
-                : product.variants[0];
-            if (variant && variant.inventory && variant.inventory.length > 0) {
-                const currentStock = variant.inventory[0].stock || 0;
-                const changeAmount = Number(params.amount);
-                if (params.stockType === 'add') {
-                    newStock = currentStock + changeAmount;
-                }
-                else if (params.stockType === 'subtract') {
-                    newStock = currentStock - changeAmount;
-                }
-                else {
-                    newStock = changeAmount;
-                }
-                // Update mock DB
-                variant.inventory[0].stock = newStock;
+    // Real handler keys off variantId (falling back to the active product's
+    // variant); mirror that here by finding the owning product for the variant.
+    if (params && params.variantId) {
+        const variantId = params.variantId;
+        let variant;
+        for (const product of MOCK_PRODUCTS) {
+            const match = product.variants.find(v => v._id === variantId);
+            if (match) {
+                variant = match;
+                break;
             }
         }
+        if (variant && variant.inventory && variant.inventory.length > 0) {
+            const currentStock = variant.inventory[0].stock || 0;
+            const changeAmount = Number(params.amount);
+            if (params.stockType === 'add') {
+                newStock = currentStock + changeAmount;
+            }
+            else if (params.stockType === 'subtract') {
+                newStock = currentStock - changeAmount;
+            }
+            else {
+                newStock = changeAmount;
+            }
+            // Update mock DB
+            variant.inventory[0].stock = newStock;
+        }
     }
     return {
         success: true,

package/dist/actions/adjust-inventory/types.d.ts

@@ -3,8 +3,8 @@ export interface AdjustInventoryParams {
     amount: string;
     /** 'add' (increase), 'subtract' (decrease), or 'set' (recount). */
     stockType: 'add' | 'subtract' | 'set';
+    /** Variant to adjust. Omit to use the active product's selected variant. */
     variantId?: string;
-    productId?: string;
 }
 export interface AdjustInventoryResponse {
     success: boolean;

package/dist/actions/authenticate-user/mock.js

@@ -1,5 +1,9 @@
 export const mockAuthenticateUser = async (params) => {
     console.log("[Mock] authenticateUser called", params);
+    // Headless path requires both userId and pin together (mirrors the handler guard).
+    if ((params?.userId || params?.pin) && !(params?.userId && params?.pin)) {
+        throw new Error("userId and pin must be provided together");
+    }
     return {
         success: true,
         roleIds: params?.roleIds || [],

package/dist/actions/authenticate-user/types.d.ts

@@ -1,5 +1,18 @@
 export interface AuthenticateUserParams {
+    /** Role IDs authorized for the gated action. The authenticating user must hold one of these. */
     roleIds: string[];
+    /**
+     * Headless validation: the id of the user whose PIN to verify. Provide together
+     * with `pin` to validate the credentials in-process and return success/failure
+     * WITHOUT showing kaching's PIN modal (the flow owns its own PIN UI). When
+     * omitted, the modal flow is used. Must be paired with `pin`.
+     */
+    userId?: string;
+    /**
+     * Headless validation: the PIN to check against `userId`'s stored pincode.
+     * Must be paired with `userId`. The user must also hold one of `roleIds`.
+     */
+    pin?: string;
 }
 export interface AuthenticateUserResponse {
     success: boolean;

package/dist/actions/calculate-refund-total/action.js

@@ -3,6 +3,6 @@
  * Calls the calculateRefundTotal action on the parent window
  */
 import { commandFrameClient } from "../../client";
-export const calculateRefundTotal = async () => {
-    return await commandFrameClient.call("calculateRefundTotal");
+export const calculateRefundTotal = async (params) => {
+    return await commandFrameClient.call("calculateRefundTotal", params);
 };

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

@@ -1,6 +1,6 @@
 import type { CFStatePair, CFTransitionResult } from "../../common-types/order-state";
 export interface CanTransitionParams {
-    /** Order to evaluate. If omitted, evaluates against a new order (from = null). */
+    /** Order to evaluate. Defaults to the active order; if there is no active order (or none matches), evaluates as a brand-new order (from = null). */
     orderId?: string;
     /** Target state pair to transition to. */
     to: CFStatePair;

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

@@ -11,7 +11,9 @@ export const mockCashPayment = async (params) => {
             cashRounding: 0,
             paymentType: "cash",
             order: null,
-            timestamp: new Date().toISOString()
+            timestamp: new Date().toISOString(),
+            saleFinalized: false,
+            remainingBalance: 0
         };
     };
     // Contract: `amount` is required, integer MINOR currency units — same
@@ -55,6 +57,8 @@ export const mockCashPayment = async (params) => {
         cashRounding: 0,
         paymentType: "cash",
         order,
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
+        saleFinalized: true,
+        remainingBalance: 0
     };
 };

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

@@ -1,17 +1,19 @@
 import { CFOrder } from "../../CommonTypes";
-import type { CFTransitionResult } from "../../common-types/order-state";
 export interface CashPaymentParams {
     /**
      * The amount to pay with this tender, in integer MINOR currency units
      * (e.g. 1575 = $15.75 — see `getContext().minorUnits` for the currency's
-     * exponent). Required. Semantics against the cart's balance due:
-     *   - missing            → error
+     * exponent). Required whenever the balance due is greater than $0; may be
+     * omitted only on a cart that already nets to a $0 balance due (e.g. fully
+     * discounted), where it defaults to 0. Semantics against the cart's
+     * balance due:
+     *   - missing            → error, unless the balance due is $0 (→ 0)
      *   - less than balance  → partial payment (the POS enters a fixed
      *                          split-payment leg for this amount)
      *   - equal to balance   → full payment
      *   - more than balance  → error (overpayment is `tenderedAmount`'s job)
      */
-    amount: number;
+    amount?: number;
     /**
      * Cash physically handed over by the customer, in integer MINOR currency
      * units. When provided, the POS computes the change itself (after applying
@@ -29,7 +31,7 @@ export interface CashPaymentParams {
      * POS still opens its legacy change-calculator modal.
      */
     openChangeCalculator?: boolean;
-    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    /** Override the fulfillment state after full payment. kaching resolves the cascade. */
     checkoutFulfillmentTarget?: string;
 }
 export interface CashPaymentResponse {
@@ -56,7 +58,9 @@ export interface CashPaymentResponse {
     paymentType: string;
     order: CFOrder | null;
     timestamp: string;
-    /** Present when the state machine blocked or forced the transition. */
-    transitionResult?: CFTransitionResult;
+    /** True when this tender settled the cart's remaining balance (the sale completed). */
+    saleFinalized: boolean;
+    /** Balance still due after this tender, in integer MINOR currency units (0 once the sale is finalized). */
+    remainingBalance: number;
 }
 export type CashPayment = (params: CashPaymentParams) => Promise<CashPaymentResponse>;

package/dist/actions/delete-parked-order/types.d.ts

@@ -1,4 +1,3 @@
-import type { CFTransitionResult } from "../../common-types/order-state";
 export interface DeleteParkedOrderParams {
     orderId: string;
 }
@@ -6,7 +5,5 @@ export interface DeleteParkedOrderResponse {
     success: boolean;
     orderId: string;
     timestamp: string;
-    /** Present when the state machine blocked or forced the transition. */
-    transitionResult?: CFTransitionResult;
 }
 export type DeleteParkedOrder = (params?: DeleteParkedOrderParams) => Promise<DeleteParkedOrderResponse>;

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

@@ -6,6 +6,10 @@ export const mockExtensionPayment = async (params) => {
         amount: params?.amount ?? null,
         paymentType,
         order: MOCK_ORDERS[0],
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
+        change: 0,
+        cashRounding: 0,
+        saleFinalized: true,
+        remainingBalance: 0
     };
 };

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

@@ -1,5 +1,4 @@
 import { CFOrder } from "../../CommonTypes";
-import type { CFTransitionResult } from "../../common-types/order-state";
 /** Params for extension-initiated payments; host routes by `paymentType`. */
 export interface ExtensionPaymentParams {
     paymentType: string;
@@ -15,8 +14,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 the order lands in on full payment (validated against the fulfillment state machine; invalid values throw). Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
+    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. */
@@ -28,7 +27,13 @@ export interface ExtensionPaymentResponse {
     paymentType: string;
     order: CFOrder | null;
     timestamp: string;
-    /** Present when the state machine blocked or forced the transition. */
-    transitionResult?: CFTransitionResult;
+    /** Change due back to the customer in integer MINOR currency units (0 for non-cash tenders). */
+    change: number;
+    /** Signed cash-rounding delta applied to the charge, in integer MINOR currency units (positive = rounded up); 0 when the company has no cash-rounding setting. */
+    cashRounding: number;
+    /** True when this tender settled the cart's remaining balance (the sale completed). */
+    saleFinalized: boolean;
+    /** Balance still due after this tender, in integer MINOR currency units (0 once the sale is finalized). */
+    remainingBalance: number;
 }
 export type ExtensionPayment = (params?: ExtensionPaymentParams) => Promise<ExtensionPaymentResponse>;

package/dist/actions/get-custom-table-data/types.d.ts

@@ -4,10 +4,8 @@ export interface GetCustomTableDataResponse<T = any> {
     timestamp: string;
 }
 export interface GetCustomTableDataParams {
-    /** Table name (kebab-case). Required if tableId is not provided. */
-    tableName?: string;
-    /** Table ID. Required if tableName is not provided. */
-    tableId?: string;
+    /** Table name (kebab-case). Required — the handler throws if it is absent. */
+    tableName: string;
     /** Optional query filter */
     query?: any;
     /** Pagination offset */

package/dist/actions/get-final-context/mock.js

@@ -1,6 +1,6 @@
 export const mockGetFinalContext = async () => {
     console.log("[Mock] getFinalContext called");
     return {
-        projectName: "Render"
+        projectName: "kaching"
     };
 };

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

@@ -10,5 +10,10 @@ import { GetRefundPlan } from './types';
  * `maxRefundable` as the full captured amount. Against real kaching those
  * numbers come from `order.refund[]` and the capture's `emv` JSON. Use this
  * only to shape UI in local/standalone mode — never to assert real capacity.
+ *
+ * `allocation` is likewise shape-only: the demo has no refund SELECTION state
+ * and no company cash-rounding setting, so it always describes a FULL refund
+ * with `rounding: 0` and no cash `payout`. Against real kaching the allocation
+ * tracks the live selection and carries the drawer snap.
  */
 export declare const mockGetRefundPlan: GetRefundPlan;

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

@@ -10,6 +10,11 @@ import { MOCK_ORDERS } from '../../demo/database';
  * `maxRefundable` as the full captured amount. Against real kaching those
  * numbers come from `order.refund[]` and the capture's `emv` JSON. Use this
  * only to shape UI in local/standalone mode — never to assert real capacity.
+ *
+ * `allocation` is likewise shape-only: the demo has no refund SELECTION state
+ * and no company cash-rounding setting, so it always describes a FULL refund
+ * with `rounding: 0` and no cash `payout`. Against real kaching the allocation
+ * tracks the live selection and carries the drawer snap.
  */
 export const mockGetRefundPlan = async (params) => {
     console.log('[Mock] getRefundPlan called', params);
@@ -45,10 +50,29 @@ export const mockGetRefundPlan = async (params) => {
     });
     const totalCaptured = sources.reduce((sum, s) => sum + s.capturedAmount, 0);
     const nonRefundableLiability = order.summary?.nonRevenueTotal ?? 0;
+    // Full-refund legs: every source returns its whole capture (the demo's
+    // `maxRefundable`), which is exactly the shape a full selection produces.
+    const legs = sources
+        .filter((s) => s.maxRefundable > 0)
+        .map((s) => ({
+        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);
     return {
         success: true,
         orderId: order._id,
         sources,
+        allocation: {
+            budget,
+            // No cash rounding in the demo, so the goods value and the budget agree.
+            itemTotal: budget,
+            rounding: 0,
+            legs,
+        },
         // Demo: no prior refunds, so remaining = captured minus the non-revenue load.
         remainingRefundable: Math.max(0, totalCaptured - nonRefundableLiability),
         nonRefundableLiability,

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;
@@ -17,10 +40,79 @@ export interface RefundPlanSource {
     /** For redeem sources: the card number from the payment entry's emv, when present. */
     cardNumber?: string;
 }
+/**
+ * One ready-to-submit refund leg. Pass these straight to
+ * `processPartialRefund({ openUI: false, legs })` — the amounts are the
+ * engine's own allocation and already satisfy its Σ-contract.
+ */
+export interface RefundPlanLeg {
+    /** `transactionId` of the source payment this leg draws from — join key to `sources`. */
+    transactionId: string;
+    /** Amount to return to this source (minor units). Submit VERBATIM; do not re-derive. */
+    amount: number;
+    /** `cash` / `card` / `redeem` / etc., copied from the source. */
+    paymentType: string;
+    /**
+     * 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
+     * cash-rounding snap, and the signed delta from `amount`. Display it
+     * ("drawer pays 6.50 (+0.01 rounding)") — never apply the snap yourself,
+     * and never stage `payout.amount` as the leg (`amount` is the leg).
+     */
+    payout?: {
+        amount: number;
+        rounding: number;
+    };
+}
+/**
+ * The engine's own allocation of the CURRENT refund selection across the
+ * order's captures — what a flow renders and submits instead of computing a
+ * split of its own.
+ *
+ * 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 {
+    /**
+     * What Σ `legs.amount` MUST equal — `min(itemTotal, Σ maxRefundable)`, which
+     * on a FULL selection is the captured total, not the goods value. Staging the
+     * goods value instead is rejected with `refund.legSumMismatch`.
+     */
+    budget: number;
+    /** Goods value of the selection (minor units). DISPLAY ONLY — never allocate against it. */
+    itemTotal: number;
+    /**
+     * `budget − itemTotal` — the sale's cash rounding, returned to the tender that
+     * took it. Non-zero only on a cash-rounded capture; the engine stamps it as
+     * refund residue at commit.
+     */
+    rounding: number;
+    /** One leg per source that receives money. Submit as `legs`, unchanged. */
+    legs: RefundPlanLeg[];
+}
 export interface GetRefundPlanResponse {
     success: boolean;
     orderId: string;
     sources: RefundPlanSource[];
+    /**
+     * Ready-to-submit allocation of the current selection. Present only when a
+     * refund selection exists on the active order. See {@link RefundPlanAllocation}.
+     */
+    allocation?: RefundPlanAllocation;
     /** Order-level remaining refundable (minor units) — non-revenue liability already excluded. */
     remainingRefundable: number;
     /** Non-refundable liability (gift-card loads etc., minor units). */

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

@@ -4,4 +4,10 @@
 // order-level math so flows can PRESENT accurate refund options without
 // re-deriving the numbers client-side (the mutating commands —
 // `processPartialRefund` / `redeemRefund` — re-validate at submit time).
+//
+// `allocation` closes the last gap: capacities alone still left a flow to work
+// out WHICH tender gets WHAT, and a flow that split the goods value across the
+// tenders shaved the sale's cash rounding off gift-card legs and was rejected
+// at submit. The engine now returns the legs it would accept — render them,
+// submit them unchanged, compute nothing.
 export {};

package/dist/actions/get-refunds/types.d.ts

@@ -3,7 +3,7 @@ export interface GetRefundsParams {
     orderId?: string;
     sessionId?: string;
     outletId?: string;
-    /** Default: 50. */
+    /** No default — when omitted, all matching refunds are returned. */
     limit?: number;
     /** Default: 0. */
     offset?: number;

package/dist/actions/get-remaining-refundable-quantities/action.js

@@ -3,6 +3,6 @@
  * Calls the getRemainingRefundableQuantities action on the parent window
  */
 import { commandFrameClient } from "../../client";
-export const getRemainingRefundableQuantities = async () => {
-    return await commandFrameClient.call("getRemainingRefundableQuantities");
+export const getRemainingRefundableQuantities = async (params) => {
+    return await commandFrameClient.call("getRemainingRefundableQuantities", params);
 };

package/dist/actions/get-remaining-refundable-quantities/mock.js

@@ -4,6 +4,8 @@ export const mockGetRemainingRefundableQuantities = async (_params) => {
         success: true,
         lineItems: {},
         customSales: {},
+        cartFees: {},
+        tips: {},
         timestamp: new Date().toISOString()
     };
 };

package/dist/actions/get-remaining-refundable-quantities/types.d.ts

@@ -5,6 +5,19 @@ export interface GetRemainingRefundableQuantitiesResponse {
     success: boolean;
     lineItems: Record<string, number>;
     customSales: Record<string, number>;
+    /**
+     * Remaining refundable cart fees, keyed by `order.cartFees[].id` —
+     * the same key `processPartialRefund` takes for `type: 'fee'` items.
+     * 0/1 semantics: `1` = still refundable, `0` = already refunded.
+     */
+    cartFees: Record<string, number>;
+    /**
+     * Remaining refundable tips, keyed by the paying method's
+     * `transactionId` — the same key `processPartialRefund` takes for
+     * `type: 'tip'` items. Only payment methods that carry a tip appear.
+     * 0/1 semantics: `1` = still refundable, `0` = already refunded.
+     */
+    tips: Record<string, number>;
     timestamp: string;
 }
 export type GetRemainingRefundableQuantities = (params?: GetRemainingRefundableQuantitiesParams) => Promise<GetRemainingRefundableQuantitiesResponse>;

package/dist/actions/initiate-refund/types.d.ts

@@ -1,4 +1,3 @@
-import type { CFTransitionResult } from "../../common-types/order-state";
 export interface InitiateRefundParams {
     /** The ID of the order to refund. If not provided, uses the currently active order. */
     orderId?: string;
@@ -7,7 +6,11 @@ export interface InitiateRefundResponse {
     success: boolean;
     orderId: string;
     timestamp: string;
-    /** Present when the state machine blocked or forced the transition. */
-    transitionResult?: CFTransitionResult;
 }
+/**
+ * @deprecated The host-side refund popup is disabled — no UI opens. Stages the
+ * active order (and arms barcode refund-scan routing when no `orderId` is
+ * given). Build refund UI in the flow: `getRefundPlan`,
+ * `getRemainingRefundableQuantities`, `processPartialRefund`, `redeemRefund`.
+ */
 export type InitiateRefund = (params?: InitiateRefundParams) => Promise<InitiateRefundResponse>;