@final-commerce/command-frame 0.4.1-preprod.2 → 0.5.0-preprod.1

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,9 +14,7 @@ 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` | Request/response per call                 |
+| **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/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,5 +1,4 @@
 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
@@ -29,7 +28,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 +55,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/check-permission/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Check permission action
+ * Calls the checkPermission action on the parent window
+ */
+import type { CheckPermission } from './types';
+export declare const checkPermission: CheckPermission;

package/dist/actions/check-permission/action.js

@@ -0,0 +1,8 @@
+/**
+ * Check permission action
+ * Calls the checkPermission action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const checkPermission = async (params) => {
+    return await commandFrameClient.call('checkPermission', params);
+};

package/dist/actions/check-permission/mock.d.ts

@@ -0,0 +1,8 @@
+import { CheckPermission } from './types';
+/**
+ * Standalone mock: `allowed: true` for every permission EXCEPT the magic name
+ * `'mock_denied'`, which returns `allowed: false` — so flows can exercise both
+ * UI branches outside the iframe. The runtime answers from the hydrated
+ * active user's role instead.
+ */
+export declare const mockCheckPermission: CheckPermission;

package/dist/actions/check-permission/mock.js

@@ -0,0 +1,18 @@
+/**
+ * Standalone mock: `allowed: true` for every permission EXCEPT the magic name
+ * `'mock_denied'`, which returns `allowed: false` — so flows can exercise both
+ * UI branches outside the iframe. The runtime answers from the hydrated
+ * active user's role instead.
+ */
+export const mockCheckPermission = async (params) => {
+    console.log('[Mock] checkPermission called', params);
+    if (!params?.permission) {
+        throw new Error('permission is required');
+    }
+    return {
+        success: true,
+        permission: params.permission,
+        allowed: params.permission !== 'mock_denied',
+        timestamp: new Date().toISOString(),
+    };
+};

package/dist/actions/check-permission/types.d.ts

@@ -0,0 +1,17 @@
+export interface CheckPermissionParams {
+    /** Permission name, e.g. 'issue_refunds'. */
+    permission: string;
+}
+export interface CheckPermissionResponse {
+    success: boolean;
+    /** Echo of the permission that was checked. */
+    permission: string;
+    /**
+     * True when the active user holds the permission — either explicitly on
+     * their role, or implicitly because their user type does not carry a role
+     * (company owner, final/org staff).
+     */
+    allowed: boolean;
+    timestamp: string;
+}
+export type CheckPermission = (params: CheckPermissionParams) => Promise<CheckPermissionResponse>;

package/dist/actions/check-permission/types.js

@@ -0,0 +1,9 @@
+// Check Permission Types
+//
+// READ-ONLY query: does the ACTIVE user hold a named permission? Truth source
+// is the runtime's hydrated active user (role + permissions from the synced
+// `users`/`roles` collections). Use it to PRE-GATE UI (hide/disable a Refund
+// button, show "You are not allowed to initiate refunds") — it is not the
+// security boundary: mutating refund commands enforce `issue_refunds`
+// runtime-side regardless (`REFUND_PERMISSION_DENIED: ` prefix).
+export {};

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/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,5 @@ export interface InitiateRefundResponse {
     success: boolean;
     orderId: string;
     timestamp: string;
-    /** Present when the state machine blocked or forced the transition. */
-    transitionResult?: CFTransitionResult;
 }
 export type InitiateRefund = (params?: InitiateRefundParams) => Promise<InitiateRefundResponse>;

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

@@ -2,7 +2,7 @@ import type { ExtensionPaymentResponse } from "../extension-payment/types";
 /**
  * Card display fields for an integration payment.
  *
- * Render JSON-serializes this object onto the order's `paymentMethod.emv` field;
+ * kaching JSON-serializes this object onto the order's `paymentMethod.emv` field;
  * the transactions list, split-payment refund modal, and receipt mapper parse it
  * back. Field names are translated to the platform's canonical EMV keys ("Brand",
  * "Cardholder Name", "Card Number", etc.) on the host before serialization — your
@@ -24,13 +24,13 @@ export interface IntegrationEmvData {
     expiryDate?: string;
     /** Issuer / bank name. → "Issuer" */
     issuer?: string;
-    /** Last 4 digits of the card. Render masks to "**** **** **** XXXX" before display. → "Card Number" */
+    /** Last 4 digits of the card. kaching masks to "**** **** **** XXXX" before display. → "Card Number" */
     cardNumberLast4?: string;
 }
 /**
  * Integration payment (e.g. Stripe-like) — always uses paymentType `"integration"` on the wire.
  * The extension processes the payment with its own provider, then reports the result here so
- * Render can record the transaction + order.
+ * kaching can record the transaction + order.
  *
  * Required fields (compile-time enforced by TS, runtime-enforced by the host handler):
  *   - `amount` — integer MINOR currency units of the captured amount (e.g. 1575 = $15.75)
@@ -51,8 +51,8 @@ export interface IntegrationPaymentParams {
     metadata?: Record<string, unknown>;
     /** Provider fee in integer MINOR currency units — stored on paymentMethod.processorFee. */
     processorFee?: number;
-    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
-    targetFulfillmentState?: string;
+    /** 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;
 }
 export type IntegrationPaymentResponse = ExtensionPaymentResponse;
 export type IntegrationPayment = (params: IntegrationPaymentParams) => Promise<IntegrationPaymentResponse>;

package/dist/actions/park-order/types.d.ts

@@ -1,10 +1,7 @@
 import { CFOrder } from "../../CommonTypes";
-import type { CFTransitionResult } from "../../common-types/order-state";
 export interface ParkOrderResponse {
     success: boolean;
     order: CFOrder;
     timestamp: string;
-    /** Present when the state machine blocked or forced the transition. */
-    transitionResult?: CFTransitionResult;
 }
 export type ParkOrder = () => Promise<ParkOrderResponse>;

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

@@ -1,5 +1,4 @@
 import { CFOrder } from "../../CommonTypes";
-import type { CFTransitionResult } from "../../common-types/order-state";
 export interface PartialPaymentParams {
     /** The payment amount in integer MINOR currency units (required if openUI is false). If isPercent is true, this is a percentage (0-100) instead. */
     amount?: number;
@@ -7,8 +6,6 @@ export interface PartialPaymentParams {
     isPercent?: boolean;
     /** If true, opens the split payment UI. */
     openUI?: boolean;
-    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
-    targetFulfillmentState?: string;
 }
 export interface PartialPaymentResponse {
     success: boolean;
@@ -17,7 +14,5 @@ export interface PartialPaymentResponse {
     openUI: boolean;
     order: CFOrder | null;
     timestamp: string;
-    /** Present when the state machine blocked or forced the transition. */
-    transitionResult?: CFTransitionResult;
 }
 export type PartialPayment = (params?: PartialPaymentParams) => Promise<PartialPaymentResponse>;

package/dist/actions/print/mock.js

@@ -9,9 +9,11 @@ export const mockPrint = (params) => {
             console.log("[Mock] Would print image:", params.data.image?.substring(0, 50) + "...");
             break;
         case "html":
+            console.warn("[Mock] print type 'html' is DEPRECATED — rasterize and use type: 'image'.");
             console.log("[Mock] Would print HTML:", params.data.html?.substring(0, 100) + "...");
             break;
         case "receipt":
+            console.warn("[Mock] print type 'receipt' is DEPRECATED — rasterize and use type: 'image'.");
             console.log("[Mock] Would print receipt for order:", params.data.order);
             break;
     }

package/dist/actions/print/types.d.ts

@@ -7,12 +7,18 @@ export type PrintParams = {
     };
     options?: PrintOptions;
 } | {
+    /** @deprecated Rasterize your HTML and use `type: "image"`. The native path posts raw HTML to the shell (no html2canvas/sanitization) and PrintOptions may be dropped. */
     type: "html";
     data: {
         html: string;
     };
     options?: PrintOptions;
 } | {
+    /**
+     * @deprecated Compose + rasterize your receipt and use `type: "image"`.
+     * The station requires `order` (no active-order fallback), ignores
+     * `globalBlockId`, and drops ALL PrintOptions (including tag routing).
+     */
     type: "receipt";
     data: {
         order?: Omit<CFActiveOrder, "_id">;
@@ -27,6 +33,7 @@ export interface PrintOptions {
         bottom?: number;
         left?: number;
     };
+    /** @deprecated Not consumed by the runtime — paper size comes from the station's per-printer settings. */
     paperSize?: string;
     width?: string;
     /**

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

@@ -1,4 +1,3 @@
-import type { CFTransitionResult } from "../../common-types/order-state";
 export interface ProcessPartialRefundParams {
     /**
      * Optional refund reason.
@@ -114,7 +113,5 @@ export interface ProcessPartialRefundResponse {
     success: boolean;
     refundId: string;
     timestamp: string;
-    /** Present when the state machine blocked or forced the transition. */
-    transitionResult?: CFTransitionResult;
 }
 export type ProcessPartialRefund = (params?: ProcessPartialRefundParams) => Promise<ProcessPartialRefundResponse>;

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

@@ -12,8 +12,8 @@ export interface RedeemPaymentParams {
     processor?: string;
     referenceId?: string;
     metadata?: Record<string, unknown>;
-    /** Override the fulfillment landing on full payment. Omitted: preserve advanced fulfillment, auto-fulfill from draft/pending/on_hold. */
-    targetFulfillmentState?: string;
+    /** 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;
 }
 export type RedeemPaymentResponse = ExtensionPaymentResponse;
 export type RedeemPayment = (params: RedeemPaymentParams) => Promise<RedeemPaymentResponse>;

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

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

package/dist/actions/tap-to-pay-payment/mock.js

@@ -10,6 +10,10 @@ export const mockTapToPayPayment = async (params) => {
         amount: due,
         paymentType: "tapToPay",
         order,
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
+        change: 0,
+        cashRounding: 0,
+        saleFinalized: true,
+        remainingBalance: 0
     };
 };

package/dist/actions/tap-to-pay-payment/types.d.ts

@@ -1,5 +1,4 @@
 import { CFOrder } from "../../CommonTypes";
-import type { CFTransitionResult } from "../../common-types/order-state";
 export interface TapToPayPaymentParams {
     /**
      * The amount to pay with this tender, in integer MINOR currency units
@@ -11,7 +10,7 @@ export interface TapToPayPaymentParams {
      *   - more than balance  → error
      */
     amount: number;
-    /** 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 TapToPayPaymentResponse {
@@ -20,7 +19,13 @@ export interface TapToPayPaymentResponse {
     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 TapToPayPayment = (params?: TapToPayPaymentParams) => Promise<TapToPayPaymentResponse>;