@final-commerce/command-frame 0.3.0-beta.6 → 0.3.0-beta.8

package/README.md

@@ -47,6 +47,22 @@ npm install @final-commerce/command-frame
 
 Commands let the extension iframe call typed functions on the host. Each host environment (Render, Manage) exposes its own set of commands.
 
+### Money values: integer minor units
+
+Every money value on this API — params **and** responses — is an **integer in
+minor currency units**: `1575` means $15.75 in USD, ¥1575 in JPY. The host
+does all money math in minor units and never converts your inputs. Use
+`getContext().minorUnits` (the currency's decimal exponent, e.g. `2` for USD,
+`0` for JPY) to convert user-typed values before sending:
+
+```typescript
+const { minorUnits } = await command.getContext();
+const amount = Math.round(parseFloat(userInput) * 10 ** (minorUnits ?? 2));
+```
+
+The two exceptions, always flagged in the field docs: percentages (`isPercent:
+true` → `amount` is `0–100`), and quantities.
+
 ### Render (POS System)
 
 For building applications that run inside the Render Point of Sale interface.

package/dist/CommonTypes.d.ts

@@ -113,6 +113,13 @@ export interface CFContextRender {
     buildIsPremium: boolean;
     isOffline: boolean;
     currency: string | null;
+    /**
+     * Number of minor-unit decimals for the company currency (e.g. 2 for USD
+     * — $15.75 = 1575 minor units; 0 for JPY). Every money param/response on
+     * this API is expressed in integer minor units; use this to convert user
+     * input.
+     */
+    minorUnits: number | null;
     currencySymbol: string | null;
     currencyPrefix: string | null;
     currencySuffix: string | null;

package/dist/actions/add-cart-discount/types.d.ts

@@ -1,5 +1,5 @@
 export interface AddCartDiscountParams {
-    /** The discount amount. If isPercent is true, this is a percentage (0-100). */
+    /** The discount amount in integer MINOR currency units (e.g. 500 = $5.00). If isPercent is true, this is a percentage (0-100) instead. */
     amount: number;
     /** Defaults to `false`. */
     isPercent?: boolean;

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

@@ -1,5 +1,5 @@
 export interface AddCartFeeParams {
-    /** The fee amount. If isPercent is true, this is a percentage. */
+    /** The fee amount in integer MINOR currency units (e.g. 500 = $5.00). If isPercent is true, this is a percentage (0-100) instead. */
     amount: number;
     /** Defaults to `false`. */
     isPercent?: boolean;

package/dist/actions/add-custom-sale/types.d.ts

@@ -1,5 +1,6 @@
 export interface AddCustomSaleParams {
     label: string;
+    /** Price in integer MINOR currency units (e.g. 1575 = $15.75). */
     price: number | string;
     applyTaxes?: boolean;
     taxTableId?: string;

package/dist/actions/add-non-revenue-item/types.d.ts

@@ -8,7 +8,7 @@ export interface AddNonRevenueItemParams {
      * The cart uses a separate unique line id per add so multiple lines can share the same refId.
      */
     id: string;
-    /** Amount in major currency units (e.g. dollars), same as cart totals */
+    /** Amount in integer MINOR currency units (e.g. 1575 = $15.75), same as cart totals. */
     amount: number;
     /** Short label for receipts/UI */
     label?: string;

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

@@ -1,5 +1,5 @@
 export interface AddProductDiscountParams {
-    /** The discount amount. If isPercent is true, this is a percentage. */
+    /** The discount amount in integer MINOR currency units (e.g. 500 = $5.00). If isPercent is true, this is a percentage (0-100) instead. */
     amount: number;
     /** Defaults to `false`. */
     isPercent?: boolean;

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

@@ -1,4 +1,5 @@
 export interface AddProductFeeParams {
+    /** The fee amount in integer MINOR currency units (e.g. 500 = $5.00). If isPercent is true, this is a percentage (0-100) instead. */
     amount: number;
     /** Defaults to `false`. */
     isPercent?: boolean;

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

@@ -4,9 +4,9 @@
  */
 import { commandFrameClient } from "../../client";
 export const cashPayment = async (params) => {
-    const finalParams = {
-        ...params,
-        openChangeCalculator: params?.openChangeCalculator ?? true
-    };
-    return await commandFrameClient.call("cashPayment", finalParams);
+    // NOTE: beta.6 defaulted `openChangeCalculator` to true here. The change
+    // calculator is deprecated (the flow owns the tender UI via
+    // `tenderedAmount` + `getCashRoundingAmount`), so the flag now passes
+    // through as-sent and defaults to false host-side.
+    return await commandFrameClient.call("cashPayment", params);
 };

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

@@ -1,40 +1,58 @@
 import { applyMockPayment, MOCK_CART } from "../../demo/database";
 export const mockCashPayment = async (params) => {
     console.log("[Mock] cashPayment called", params);
-    // Default to true to match action behavior.
-    const openChangeCalculator = params?.openChangeCalculator ?? true;
-    // Amount due for THIS tender (the queued amount-to-be-charged), in minor units.
-    const due = params?.amount ?? MOCK_CART.amountToBeCharged ?? MOCK_CART.total;
-    if (openChangeCalculator) {
+    const fail = (reason) => {
+        console.warn(`[Mock] cashPayment rejected: ${reason}`);
+        return {
+            success: false,
+            amount: 0,
+            openChangeCalculator: params?.openChangeCalculator ?? false,
+            change: 0,
+            cashRounding: 0,
+            paymentType: "cash",
+            order: null,
+            timestamp: new Date().toISOString()
+        };
+    };
+    // Contract: `amount` is required, integer MINOR currency units — same
+    // scale as the mock cart's totals, so comparisons are direct.
+    if (params?.amount === undefined || params.amount === null) {
+        return fail("amount is required (integer minor currency units)");
+    }
+    const balanceDue = MOCK_CART.amountToBeCharged ?? MOCK_CART.total;
+    if (params.amount > balanceDue) {
+        return fail(`amount ${params.amount} exceeds balance due ${balanceDue}`);
+    }
+    // Flow-owned tender: compute change here (no rounding in the mock).
+    let change = 0;
+    if (params.tenderedAmount !== undefined) {
+        if (params.tenderedAmount < params.amount) {
+            return fail(`tenderedAmount ${params.tenderedAmount} is less than amount ${params.amount}`);
+        }
+        change = params.tenderedAmount - params.amount;
+    }
+    else if (params.openChangeCalculator) {
+        // Deprecated legacy path: simulate the POS-owned change calculator.
         try {
-            const input = window.prompt(`Amount due: $${(due / 100).toFixed(2)}\nEnter amount tendered:`, (due / 100).toFixed(2));
-            if (input === null) {
-                return {
-                    success: false,
-                    amount: 0,
-                    openChangeCalculator,
-                    paymentType: "cash",
-                    order: null,
-                    timestamp: new Date().toISOString()
-                };
-            }
-            const tendered = parseFloat(input); // dollars
-            if (!isNaN(tendered)) {
-                const change = tendered - due / 100;
-                window.alert(change >= 0
-                    ? `Change Due: $${change.toFixed(2)}`
-                    : `Warning: Tendered is short by: $${Math.abs(change).toFixed(2)}`);
-            }
+            const input = window.prompt(`Amount due: $${(params.amount / 100).toFixed(2)}\nEnter amount tendered (dollars):`, (params.amount / 100).toFixed(2));
+            if (input === null)
+                return fail("cancelled");
+            const tendered = parseFloat(input);
+            if (!isNaN(tendered))
+                change = Math.round(tendered * 100) - params.amount;
         }
         catch (e) {
             console.warn("Could not open prompt/alert (possibly in non-interactive environment)", e);
         }
     }
-    const order = applyMockPayment(due, "cash", "cash");
+    const order = applyMockPayment(params.amount, "cash", "cash");
     return {
         success: true,
-        amount: due,
-        openChangeCalculator,
+        amount: params.amount,
+        openChangeCalculator: params.openChangeCalculator ?? false,
+        change,
+        tenderedAmount: params.tenderedAmount,
+        cashRounding: 0,
         paymentType: "cash",
         order,
         timestamp: new Date().toISOString()

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

@@ -1,21 +1,62 @@
 import { CFOrder } from "../../CommonTypes";
 import type { CFTransitionResult } from "../../common-types/order-state";
 export interface CashPaymentParams {
-    /** If not provided, uses the cart total. */
-    amount?: number;
-    /** Defaults to false. */
+    /**
+     * 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
+     *   - 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;
+    /**
+     * Cash physically handed over by the customer, in integer MINOR currency
+     * units. When provided, the POS computes the change itself (after applying
+     * the company's cash-rounding setting to the charge) and does NOT open its
+     * own change-calculator modal — the flow owns the tender UI. Must be >= the
+     * (rounded) charge or the payment fails.
+     * Pair with `getCashRoundingAmount` to display the rounded total before
+     * collecting the tender.
+     */
+    tenderedAmount?: number;
+    /**
+     * @deprecated The change calculator now lives in the flow: call
+     * `getCashRoundingAmount`, collect the tender in your own UI, and pass
+     * `tenderedAmount` instead. When true (and `tenderedAmount` is absent) the
+     * POS still opens its legacy change-calculator modal.
+     */
     openChangeCalculator?: boolean;
     /** Override the fulfillment state after full payment. Render resolves the cascade. */
     checkoutFulfillmentTarget?: string;
 }
 export interface CashPaymentResponse {
     success: boolean;
+    /** The amount paid with this tender, in integer MINOR currency units. */
     amount: number;
+    /** @deprecated Mirror of the deprecated request flag. */
     openChangeCalculator: boolean;
+    /**
+     * Change due back to the customer in integer MINOR currency units.
+     * Non-zero only when `tenderedAmount` exceeded the (cash-rounded) charge.
+     * Display this — don't recompute it client-side: it accounts for cash
+     * rounding.
+     */
+    change: number;
+    /** Echo of the tendered cash (MINOR units) when it was provided. */
+    tenderedAmount?: 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;
     paymentType: string;
     order: CFOrder | null;
     timestamp: string;
     /** Present when the state machine blocked or forced the transition. */
     transitionResult?: CFTransitionResult;
 }
-export type CashPayment = (params?: CashPaymentParams) => Promise<CashPaymentResponse>;
+export type CashPayment = (params: CashPaymentParams) => Promise<CashPaymentResponse>;

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

@@ -4,7 +4,13 @@ import type { CFTransitionResult } from "../../common-types/order-state";
 export interface ExtensionPaymentParams {
     paymentType: string;
     processor?: string;
-    amount?: number;
+    /**
+     * The amount to pay with this tender, in integer MINOR currency units
+     * (e.g. 1575 = $15.75). Required. Semantics against the cart's balance
+     * due: missing → error; less than balance → partial payment (fixed
+     * split-payment leg); equal → full payment; more → error.
+     */
+    amount: number;
     label?: string;
     referenceId?: string;
     extensionId?: string;
@@ -13,7 +19,7 @@ export interface ExtensionPaymentParams {
     checkoutFulfillmentTarget?: string;
     /** EMV data when the underlying payment carries one (typed as `IntegrationEmvData` by the integration wrapper). */
     emvData?: unknown;
-    /** Processor fee in minor units; recorded on the order's paymentMethod.processorFee. */
+    /** Processor fee in integer MINOR currency units; recorded on the order's paymentMethod.processorFee. */
     processorFee?: number;
 }
 export interface ExtensionPaymentResponse {

package/dist/actions/get-cash-rounding-amount/action.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Get cash rounding amount action — preview the company's cash rounding for an
+ * amount (or the cart's balance due) WITHOUT touching any state. Read-only.
+ *
+ * Built for flow-owned cash tender UIs: fetch the rounded total, display it,
+ * collect the tendered cash, then call `cashPayment({ amount, tenderedAmount })`.
+ */
+import type { GetCashRoundingAmount } from "./types";
+export declare const getCashRoundingAmount: GetCashRoundingAmount;

package/dist/actions/get-cash-rounding-amount/action.js

@@ -0,0 +1,11 @@
+/**
+ * Get cash rounding amount action — preview the company's cash rounding for an
+ * amount (or the cart's balance due) WITHOUT touching any state. Read-only.
+ *
+ * Built for flow-owned cash tender UIs: fetch the rounded total, display it,
+ * collect the tendered cash, then call `cashPayment({ amount, tenderedAmount })`.
+ */
+import { commandFrameClient } from "../../client";
+export const getCashRoundingAmount = async (params) => {
+    return await commandFrameClient.call("getCashRoundingAmount", params);
+};

package/dist/actions/get-cash-rounding-amount/mock.d.ts

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

package/dist/actions/get-cash-rounding-amount/mock.js

@@ -0,0 +1,15 @@
+import { MOCK_CART } from "../../demo/database";
+/** Mock rounds to the nearest 5 minor units (a typical $0.05 cash-rounding setting). */
+const MOCK_INCREMENT_MINOR = 5;
+export const mockGetCashRoundingAmount = async (params) => {
+    console.log("[Mock] getCashRoundingAmount called", params);
+    const amount = Math.round(params?.amount ?? MOCK_CART.amountToBeCharged ?? MOCK_CART.total);
+    const roundedAmount = Math.round(amount / MOCK_INCREMENT_MINOR) * MOCK_INCREMENT_MINOR;
+    return {
+        success: true,
+        amount,
+        roundedAmount,
+        cashRounding: roundedAmount - amount,
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/get-cash-rounding-amount/types.d.ts

@@ -0,0 +1,25 @@
+export interface GetCashRoundingAmountParams {
+    /**
+     * The amount to round, in integer MINOR currency units (e.g. 1577 =
+     * $15.77). Defaults to the cart's current balance due when omitted.
+     */
+    amount?: number;
+}
+export interface GetCashRoundingAmountResponse {
+    success: boolean;
+    /** The input amount that was rounded, in integer MINOR currency units. */
+    amount: number;
+    /**
+     * The amount after applying the company's cash-rounding setting, in
+     * integer MINOR currency units. Equals `amount` when no cash-rounding
+     * setting is configured.
+     */
+    roundedAmount: number;
+    /**
+     * Signed rounding delta (`roundedAmount - amount`) in integer MINOR
+     * currency units. Positive = rounded up. 0 when no setting is configured.
+     */
+    cashRounding: number;
+    timestamp: string;
+}
+export type GetCashRoundingAmount = (params?: GetCashRoundingAmountParams) => Promise<GetCashRoundingAmountResponse>;

package/dist/actions/get-cash-rounding-amount/types.js

@@ -0,0 +1,2 @@
+// Get Cash Rounding Amount Types
+export {};

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

@@ -18,6 +18,7 @@ export const mockGetContext = () => {
         buildIsPremium: true,
         isOffline: false,
         currency: "USD",
+        minorUnits: 2,
         currencySymbol: "$",
         currencyPrefix: "$",
         currencySuffix: "",

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

@@ -33,7 +33,7 @@ export interface IntegrationEmvData {
  * Render can record the transaction + order.
  *
  * Required fields (compile-time enforced by TS, runtime-enforced by the host handler):
- *   - `amount` — minor units of the captured amount
+ *   - `amount` — integer MINOR currency units of the captured amount (e.g. 1575 = $15.75)
  *   - `emvData` — typed card display fields; the host maps + JSON-serializes to `paymentMethod.emv`
  *                 (same persisted shape as the native card flow). Required: if the integration
  *                 doesn't produce card data, use redeemPayment instead.
@@ -49,7 +49,7 @@ export interface IntegrationPaymentParams {
     processor?: string;
     referenceId?: string;
     metadata?: Record<string, unknown>;
-    /** Provider fee in minor units — stored on paymentMethod.processorFee. */
+    /** Provider fee in integer MINOR currency units — stored on paymentMethod.processorFee. */
     processorFee?: number;
 }
 export type IntegrationPaymentResponse = ExtensionPaymentResponse;

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

@@ -1,7 +1,7 @@
 import { CFOrder } from "../../CommonTypes";
 import type { CFTransitionResult } from "../../common-types/order-state";
 export interface PartialPaymentParams {
-    /** The payment amount (required if openUI is false). */
+    /** 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;
     /** Defaults to false. */
     isPercent?: boolean;

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

@@ -5,6 +5,7 @@ import type { ExtensionPaymentResponse } from "../extension-payment/types";
  * total. The host handler also re-validates this at runtime to catch raw-postMessage callers.
  */
 export interface RedeemPaymentParams {
+    /** Amount in integer MINOR currency units (e.g. 1575 = $15.75). */
     amount: number;
     label?: string;
     extensionId?: string;

package/dist/actions/send-email/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Send email action — email the customer the active order's (or a refund's) receipt.
+ * Calls the sendEmail action on the parent window.
+ */
+import type { SendEmail } from "./types";
+export declare const sendEmail: SendEmail;

package/dist/actions/send-email/action.js

@@ -0,0 +1,8 @@
+/**
+ * Send email action — email the customer the active order's (or a refund's) receipt.
+ * Calls the sendEmail action on the parent window.
+ */
+import { commandFrameClient } from "../../client";
+export const sendEmail = async (params) => {
+    return await commandFrameClient.call("sendEmail", params);
+};

package/dist/actions/send-email/mock.d.ts

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

package/dist/actions/send-email/mock.js

@@ -0,0 +1,11 @@
+export const mockSendEmail = async (params) => {
+    console.log("[Mock] sendEmail called", params);
+    return {
+        success: true,
+        channel: "email",
+        email: params?.email || "mock@example.com",
+        entityId: params?.refundId || params?.orderId || "mock_order_1",
+        type: params?.type || "order",
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/send-email/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Which receipt to send: a finalized order (default) or a refund.
+ * Values MUST stay in lockstep with `ReceiptType` in `@final-commerce/common` (used by hub-api);
+ * this SDK intentionally has no dependency on that package, so the literal is duplicated here.
+ */
+export type SendReceiptType = 'order' | 'refund';
+export interface SendEmailParams {
+    /** Recipient email. Defaults to the active customer's email. */
+    email?: string;
+    /** Order id to send the receipt for. Defaults to the active order. */
+    orderId?: string;
+    /** Refund id — required when `type` is 'refund'. */
+    refundId?: string;
+    /** 'order' (default) or 'refund'. */
+    type?: SendReceiptType;
+}
+export interface SendEmailResponse {
+    success: boolean;
+    /** Always 'email' for this action. */
+    channel: 'email';
+    /** The email the receipt was sent to. */
+    email: string;
+    /** The order or refund id the receipt was sent for. */
+    entityId: string;
+    type: SendReceiptType;
+    timestamp: string;
+}
+export type SendEmail = (params?: SendEmailParams) => Promise<SendEmailResponse>;

package/dist/actions/send-email/types.js

@@ -0,0 +1,2 @@
+// Send Email Types — email the customer their order/refund receipt.
+export {};

package/dist/actions/send-sms/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Send SMS action — text the customer the active order's (or a refund's) receipt.
+ * Calls the sendSms action on the parent window.
+ */
+import type { SendSms } from "./types";
+export declare const sendSms: SendSms;

package/dist/actions/send-sms/action.js

@@ -0,0 +1,8 @@
+/**
+ * Send SMS action — text the customer the active order's (or a refund's) receipt.
+ * Calls the sendSms action on the parent window.
+ */
+import { commandFrameClient } from "../../client";
+export const sendSms = async (params) => {
+    return await commandFrameClient.call("sendSms", params);
+};

package/dist/actions/send-sms/mock.d.ts

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

package/dist/actions/send-sms/mock.js

@@ -0,0 +1,11 @@
+export const mockSendSms = async (params) => {
+    console.log("[Mock] sendSms called", params);
+    return {
+        success: true,
+        channel: "text",
+        phone: params?.phone || "+15555550123",
+        entityId: params?.refundId || params?.orderId || "mock_order_1",
+        type: params?.type || "order",
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/send-sms/types.d.ts

@@ -0,0 +1,24 @@
+import type { SendReceiptType } from "../send-email/types";
+export type { SendReceiptType };
+export interface SendSmsParams {
+    /** Recipient phone in E.164 format (e.g. +15555550123). Defaults to the active customer's phone. */
+    phone?: string;
+    /** Order id to send the receipt for. Defaults to the active order. */
+    orderId?: string;
+    /** Refund id — required when `type` is 'refund'. */
+    refundId?: string;
+    /** 'order' (default) or 'refund'. */
+    type?: SendReceiptType;
+}
+export interface SendSmsResponse {
+    success: boolean;
+    /** Always 'text' for this action. */
+    channel: 'text';
+    /** The phone the receipt was sent to (E.164). */
+    phone: string;
+    /** The order or refund id the receipt was sent for. */
+    entityId: string;
+    type: SendReceiptType;
+    timestamp: string;
+}
+export type SendSms = (params?: SendSmsParams) => Promise<SendSmsResponse>;

package/dist/actions/send-sms/types.js

@@ -0,0 +1,2 @@
+// Send SMS Types — text the customer their order/refund receipt.
+export {};

package/dist/actions/set-active-product-discount/types.d.ts

@@ -1,5 +1,5 @@
 export interface SetActiveProductDiscountParams {
-    /** The discount amount. If isPercent is true, this is a percentage. */
+    /** The discount amount in integer MINOR currency units (e.g. 500 = $5.00). If isPercent is true, this is a percentage (0-100) instead. */
     amount: number;
     /** Defaults to `false`. */
     isPercent?: boolean;

package/dist/actions/set-active-product-fee/types.d.ts

@@ -1,4 +1,5 @@
 export interface SetActiveProductFeeParams {
+    /** The fee amount in integer MINOR currency units (e.g. 500 = $5.00). If isPercent is true, this is a percentage (0-100) instead. */
     amount: number;
     /** Defaults to `false`. */
     isPercent?: boolean;

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

@@ -1,8 +1,16 @@
 import { CFOrder } from "../../CommonTypes";
 import type { CFTransitionResult } from "../../common-types/order-state";
 export interface TapToPayPaymentParams {
-    /** If not provided, uses the cart total. */
-    amount?: number;
+    /**
+     * The amount to pay with this tender, in integer MINOR currency units
+     * (e.g. 1575 = $15.75). Required. Semantics against the cart's balance due:
+     *   - missing            → error
+     *   - 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
+     */
+    amount: number;
     /** Override the fulfillment state after full payment. Render resolves the cascade. */
     checkoutFulfillmentTarget?: string;
 }

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

@@ -1,8 +1,16 @@
 import { CFOrder } from "../../CommonTypes";
 import type { CFTransitionResult } from "../../common-types/order-state";
 export interface TerminalPaymentParams {
-    /** If not provided, uses the cart total. */
-    amount?: number;
+    /**
+     * The amount to pay with this tender, in integer MINOR currency units
+     * (e.g. 1575 = $15.75). Required. Semantics against the cart's balance due:
+     *   - missing            → error
+     *   - 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
+     */
+    amount: number;
     /** "Bluetooth" or "Cloud". Defaults to "Cloud". */
     paymentType?: 'Bluetooth' | 'Cloud';
     /** Override the fulfillment state after full payment. Render resolves the cascade. */

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

@@ -1,8 +1,16 @@
 import { CFOrder } from "../../CommonTypes";
 import type { CFTransitionResult } from "../../common-types/order-state";
 export interface VendaraPaymentParams {
-    /** If not provided, uses the cart total. */
-    amount?: number;
+    /**
+     * The amount to pay with this tender, in integer MINOR currency units
+     * (e.g. 1575 = $15.75). Required. Semantics against the cart's balance due:
+     *   - missing            → error
+     *   - 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
+     */
+    amount: number;
     /** Override the fulfillment state after full payment. Render resolves the cascade. */
     checkoutFulfillmentTarget?: string;
 }

package/dist/demo/database.js

@@ -25,6 +25,7 @@ export const MOCK_COMPANY = {
     settings: {
         currencyPrefix: "$",
         currencySuffix: "",
+        minorUnits: 2,
         currencySymbol: "$",
         decimalSeparator: ".",
         thousandSeparator: ",",

package/dist/index.d.ts

@@ -33,6 +33,7 @@ export declare const command: {
     readonly resumeParkedOrder: import(".").ResumeParkedOrder;
     readonly deleteParkedOrder: import(".").DeleteParkedOrder;
     readonly cashPayment: import(".").CashPayment;
+    readonly getCashRoundingAmount: import(".").GetCashRoundingAmount;
     readonly tapToPayPayment: import(".").TapToPayPayment;
     readonly terminalPayment: import(".").TerminalPayment;
     readonly vendaraPayment: import(".").VendaraPayment;
@@ -68,6 +69,8 @@ export declare const command: {
     readonly removeOrderNote: import(".").RemoveOrderNote;
     readonly removeCustomSale: import(".").RemoveCustomSale;
     readonly removeNonRevenueItem: import(".").RemoveNonRevenueItem;
+    readonly sendEmail: import(".").SendEmail;
+    readonly sendSms: import(".").SendSms;
     readonly initiateRefund: import(".").InitiateRefund;
     readonly setRefundStockAction: import(".").SetRefundStockAction;
     readonly selectAllRefundItems: import(".").SelectAllRefundItems;
@@ -157,6 +160,7 @@ export type { ParkOrder, ParkOrderResponse } from "./actions/park-order/types";
 export type { ResumeParkedOrder, ResumeParkedOrderParams, ResumeParkedOrderResponse } from "./actions/resume-parked-order/types";
 export type { DeleteParkedOrder, DeleteParkedOrderParams, DeleteParkedOrderResponse } from "./actions/delete-parked-order/types";
 export type { CashPayment, CashPaymentParams, CashPaymentResponse } from "./actions/cash-payment/types";
+export type { GetCashRoundingAmount, GetCashRoundingAmountParams, GetCashRoundingAmountResponse } from "./actions/get-cash-rounding-amount/types";
 export type { TapToPayPayment, TapToPayPaymentParams, TapToPayPaymentResponse } from "./actions/tap-to-pay-payment/types";
 export type { TerminalPayment, TerminalPaymentParams, TerminalPaymentResponse } from "./actions/terminal-payment/types";
 export type { VendaraPayment, VendaraPaymentParams, VendaraPaymentResponse } from "./actions/vendara-payment/types";
@@ -198,6 +202,8 @@ export type { RemoveCartFee, RemoveCartFeeParams, RemoveCartFeeResponse } from "
 export type { RemoveOrderNote, RemoveOrderNoteResponse } from "./actions/remove-order-note/types";
 export type { RemoveCustomSale, RemoveCustomSaleParams, RemoveCustomSaleResponse } from "./actions/remove-custom-sale/types";
 export type { RemoveNonRevenueItem, RemoveNonRevenueItemParams, RemoveNonRevenueItemResponse } from "./actions/remove-non-revenue-item/types";
+export type { SendEmail, SendEmailParams, SendEmailResponse, SendReceiptType } from "./actions/send-email/types";
+export type { SendSms, SendSmsParams, SendSmsResponse } from "./actions/send-sms/types";
 export * from "./CommonTypes";
 export { setMockDatabase, setMockActiveProduct } from "./demo/database";
 export type { MockDatabaseConfig } from "./demo/database";

package/dist/index.js

@@ -33,6 +33,7 @@ import { parkOrder } from "./actions/park-order/action";
 import { resumeParkedOrder } from "./actions/resume-parked-order/action";
 import { deleteParkedOrder } from "./actions/delete-parked-order/action";
 import { cashPayment } from "./actions/cash-payment/action";
+import { getCashRoundingAmount } from "./actions/get-cash-rounding-amount/action";
 import { tapToPayPayment } from "./actions/tap-to-pay-payment/action";
 import { terminalPayment } from "./actions/terminal-payment/action";
 import { vendaraPayment } from "./actions/vendara-payment/action";
@@ -72,6 +73,9 @@ import { removeOrderNote } from "./actions/remove-order-note/action";
 import { removeCustomSale } from "./actions/remove-custom-sale/action";
 import { removeNonRevenueItem } from "./actions/remove-non-revenue-item/action";
 // Integration Actions
+// Receipt send Actions
+import { sendEmail } from "./actions/send-email/action";
+import { sendSms } from "./actions/send-sms/action";
 // Refund Actions
 import { getRefunds } from "./actions/get-refunds/action";
 import { initiateRefund } from "./actions/initiate-refund/action";
@@ -158,6 +162,7 @@ export const command = {
     resumeParkedOrder,
     deleteParkedOrder,
     cashPayment,
+    getCashRoundingAmount,
     tapToPayPayment,
     terminalPayment,
     vendaraPayment,
@@ -197,6 +202,9 @@ export const command = {
     removeCustomSale,
     removeNonRevenueItem,
     // Integration Actions
+    // Receipt send Actions
+    sendEmail,
+    sendSms,
     // Refund Actions
     initiateRefund,
     setRefundStockAction,
@@ -245,7 +253,6 @@ export const command = {
     getAvailableTransitions,
     applyTransition
 };
-// Integration Actions
 // Export Common Types
 export * from "./CommonTypes";
 // Mock database override (standalone / extension dev)

package/dist/projects/render/mocks.js

@@ -27,6 +27,7 @@ import { mockAssignCustomer } from "../../actions/assign-customer/mock";
 import { mockAuthenticateUser } from "../../actions/authenticate-user/mock";
 import { mockCalculateRefundTotal } from "../../actions/calculate-refund-total/mock";
 import { mockCashPayment } from "../../actions/cash-payment/mock";
+import { mockGetCashRoundingAmount } from "../../actions/get-cash-rounding-amount/mock";
 import { mockClearCart } from "../../actions/clear-cart/mock";
 import { mockDeleteParkedOrder } from "../../actions/delete-parked-order/mock";
 import { mockExampleFunction } from "../../actions/example-function/mock";
@@ -91,6 +92,8 @@ import { canTransitionMock } from "../../actions/can-transition/mock";
 import { getAvailableTransitionsMock } from "../../actions/get-available-transitions/mock";
 import { mockGetSmartGridLayout } from "../../actions/get-smart-grid-layout/mock";
 import { mockSaveSmartGridLayout } from "../../actions/save-smart-grid-layout/mock";
+import { mockSendEmail } from "../../actions/send-email/mock";
+import { mockSendSms } from "../../actions/send-sms/mock";
 export const RENDER_MOCKS = {
     addCartDiscount: mockAddCartDiscount,
     addCartFee: mockAddCartFee,
@@ -115,6 +118,7 @@ export const RENDER_MOCKS = {
     authenticateUser: mockAuthenticateUser,
     calculateRefundTotal: mockCalculateRefundTotal,
     cashPayment: mockCashPayment,
+    getCashRoundingAmount: mockGetCashRoundingAmount,
     clearCart: mockClearCart,
     deleteParkedOrder: mockDeleteParkedOrder,
     exampleFunction: mockExampleFunction,
@@ -186,5 +190,7 @@ export const RENDER_MOCKS = {
     canTransition: canTransitionMock,
     getAvailableTransitions: getAvailableTransitionsMock,
     getSmartGridLayout: mockGetSmartGridLayout,
-    saveSmartGridLayout: mockSaveSmartGridLayout
+    saveSmartGridLayout: mockSaveSmartGridLayout,
+    sendEmail: mockSendEmail,
+    sendSms: mockSendSms
 };

package/dist/projects/render/types.d.ts

@@ -1,4 +1,4 @@
-import type { ExampleFunction, GetProducts, AddCustomSale, GetCustomers, AssignCustomer, AddCustomer, EditCustomer, GetCategories, GetOrders, GetRefunds, GetTaxTables, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, AddOrderNote, AddCartFee, ClearCart, ParkOrder, ResumeParkedOrder, DeleteParkedOrder, InitiateRefund, CashPayment, TapToPayPayment, TerminalPayment, VendaraPayment, ExtensionPayment, RedeemPayment, AddNonRevenueItem, AddCustomerNote, RemoveCustomerNote, RemoveCustomerFromCart, GoToStationHome, OpenCashDrawer, ShowNotification, ShowConfirmation, AuthenticateUser, PartialPayment, SwitchUser, SetRefundStockAction, SelectAllRefundItems, ResetRefundDetails, CalculateRefundTotal, GetRemainingRefundableQuantities, ProcessPartialRefund, GetCurrentCart, Print, SetActiveOrder, GetCustomTables, GetCustomTableData, UpsertCustomTableData, DeleteCustomTableData, GetCustomExtensions, GetCurrentCompanyCustomExtensions, GetCustomExtensionCustomTables, GetCustomTableFields, GetSecretsKeys, GetSecretVal, SetSecretVal, GetUsers, GetRoles, RemoveCartDiscount, GetActiveOrder, GetActiveCustomer, SetActiveCustomer, GetActiveOutlet, GetActiveStation, GetActiveSession, GetActiveUser, SetActiveUser, SetActiveRefund, RemoveProductDiscount, RemoveProductFee, RemoveProductNote, RemoveCartFee, RemoveOrderNote, RemoveCustomSale, RemoveNonRevenueItem, CanTransition, GetAvailableTransitions, IntegrationPayment, GetSmartGridLayout, SaveSmartGridLayout } from "../../index";
+import type { ExampleFunction, GetProducts, AddCustomSale, GetCustomers, AssignCustomer, AddCustomer, EditCustomer, GetCategories, GetOrders, GetRefunds, GetTaxTables, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, AddOrderNote, AddCartFee, ClearCart, ParkOrder, ResumeParkedOrder, DeleteParkedOrder, InitiateRefund, CashPayment, GetCashRoundingAmount, TapToPayPayment, TerminalPayment, VendaraPayment, ExtensionPayment, RedeemPayment, AddNonRevenueItem, AddCustomerNote, RemoveCustomerNote, RemoveCustomerFromCart, GoToStationHome, OpenCashDrawer, ShowNotification, ShowConfirmation, AuthenticateUser, PartialPayment, SwitchUser, SetRefundStockAction, SelectAllRefundItems, ResetRefundDetails, CalculateRefundTotal, GetRemainingRefundableQuantities, ProcessPartialRefund, GetCurrentCart, Print, SetActiveOrder, GetCustomTables, GetCustomTableData, UpsertCustomTableData, DeleteCustomTableData, GetCustomExtensions, GetCurrentCompanyCustomExtensions, GetCustomExtensionCustomTables, GetCustomTableFields, GetSecretsKeys, GetSecretVal, SetSecretVal, GetUsers, GetRoles, RemoveCartDiscount, GetActiveOrder, GetActiveCustomer, SetActiveCustomer, GetActiveOutlet, GetActiveStation, GetActiveSession, GetActiveUser, SetActiveUser, SetActiveRefund, RemoveProductDiscount, RemoveProductFee, RemoveProductNote, RemoveCartFee, RemoveOrderNote, RemoveCustomSale, RemoveNonRevenueItem, CanTransition, GetAvailableTransitions, IntegrationPayment, GetSmartGridLayout, SaveSmartGridLayout, SendEmail, SendSms } from "../../index";
 import type { OpenExtensionOverlay } from "../../actions/open-extension-overlay/types";
 import type { ResolveExtensionOverlay } from "../../actions/resolve-extension-overlay/types";
 export interface RenderProviderActions {
@@ -37,6 +37,7 @@ export interface RenderProviderActions {
     openExtensionOverlay: OpenExtensionOverlay;
     resolveExtensionOverlay: ResolveExtensionOverlay;
     cashPayment: CashPayment;
+    getCashRoundingAmount: GetCashRoundingAmount;
     tapToPayPayment: TapToPayPayment;
     terminalPayment: TerminalPayment;
     vendaraPayment: VendaraPayment;
@@ -97,4 +98,6 @@ export interface RenderProviderActions {
     getAvailableTransitions: GetAvailableTransitions;
     getSmartGridLayout: GetSmartGridLayout;
     saveSmartGridLayout: SaveSmartGridLayout;
+    sendEmail: SendEmail;
+    sendSms: SendSms;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.3.0-beta.6",
+  "version": "0.3.0-beta.8",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",