@final-commerce/command-frame 0.1.43 → 0.1.46

package/README.md

@@ -13,6 +13,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) |
+| **Host → iframe refunds** | Render asks the extension to reverse redeem / gift-card payments before completing a POS refund | Parent `postMessage` + `requestId` (see below) |
 
 ## Installation
 
@@ -109,6 +110,39 @@ hooks.register('cart', async (event, hostCommands) => {
 hooks.unregister('my-extension:cart-log');
 ```
 
+## Host-initiated extension refunds (redeem / gift card)
+
+**Extensions that accept redeem / extension payments must implement a refund listener.** When staff refund an order paid with `paymentType: "redeem"`, Render (host) `postMessage`s into your iframe **before** it records the refund locally. If your app does not handle this message, redeem refunds will time out or fail.
+
+### What you should do
+
+1. **Recommended:** call **`installExtensionRefundListener`** once when your extension boots (e.g. next to your `RenderClient` setup). Pass an `async` handler that calls your provider (gift card API, wallet, etc.) and returns an **`ExtensionRefundResponse`** (`success`, optional `error`, optional `extensionTransactionId` for receipts / support).
+2. The helper validates `event.source === window.parent`, parses params, and replies with the same **`PostMessageResponse`** envelope as the rest of Command Frame (`requestId`, `success`, `data` / `error`).
+3. **Alternative:** implement a `window` `message` listener yourself using the same contract (action name: **`extensionRefundRequest`**, or import **`EXTENSION_REFUND_REQUEST_ACTION`** from this package).
+
+Exported APIs: `installExtensionRefundListener`, `EXTENSION_REFUND_REQUEST_ACTION`, types **`ExtensionRefundParams`** / **`ExtensionRefundResponse`**.
+
+```typescript
+import {
+    installExtensionRefundListener,
+    type ExtensionRefundParams,
+    type ExtensionRefundResponse
+} from '@final-commerce/command-frame';
+
+const unsubscribe = installExtensionRefundListener(async (params: ExtensionRefundParams): Promise<ExtensionRefundResponse> => {
+    // params.paymentType === "redeem", params.amount in major currency units, params.saleId, params.processor, etc.
+    const ok = await myGiftCardProvider.refund(params);
+    return ok
+        ? { success: true, extensionTransactionId: ok.providerRefundId }
+        : { success: false, error: 'Refund declined' };
+});
+
+// on teardown (optional)
+// unsubscribe();
+```
+
+**Full protocol, edge cases, and manual handling:** **[Extension refund documentation](./src/actions/extension-refund/README.md)**.
+
 ## Development & Testing
 
 ### Demo Mode / Mocking

package/dist/CommonTypes.d.ts

@@ -1,4 +1,47 @@
 export * from "./common-types";
+export declare enum CurrencyCode {
+    USD = "USD",
+    EUR = "EUR",
+    GBP = "GBP",
+    CAD = "CAD",
+    AUD = "AUD",
+    NZD = "NZD",
+    CHF = "CHF",
+    CNY = "CNY",
+    INR = "INR",
+    MXN = "MXN",
+    BRL = "BRL",
+    ZAR = "ZAR",
+    SGD = "SGD",
+    HKD = "HKD",
+    SEK = "SEK",
+    NOK = "NOK",
+    DKK = "DKK",
+    PLN = "PLN",
+    THB = "THB",
+    MYR = "MYR",
+    PHP = "PHP",
+    IDR = "IDR",
+    AED = "AED",
+    SAR = "SAR",
+    ILS = "ILS",
+    TRY = "TRY",
+    RUB = "RUB",
+    JPY = "JPY",
+    KRW = "KRW",
+    VND = "VND",
+    CLP = "CLP",
+    ISK = "ISK",
+    HUF = "HUF",
+    TWD = "TWD",
+    KWD = "KWD",
+    BHD = "BHD",
+    OMR = "OMR",
+    JOD = "JOD",
+    TND = "TND",
+    LYD = "LYD",
+    IQD = "IQD"
+}
 export declare enum CFProductType {
     SIMPLE = "simple",
     VARIABLE = "variable"
@@ -51,7 +94,7 @@ export interface CFTax {
     id: string;
     name: string;
     percentage: number;
-    amount: string;
+    amount: number;
     taxTableName: string;
     taxTableId: string;
 }
@@ -82,11 +125,11 @@ export interface CFCategory {
 }
 export interface CFProductVariant {
     sku: string;
-    price: string;
-    salePrice: string;
+    price: number;
+    salePrice: number;
     isOnSale: boolean;
     barcode?: string;
-    costPrice?: string;
+    costPrice?: number;
     manageStock: boolean;
     externalId?: string;
     inventory?: CFInventory[];
@@ -121,8 +164,10 @@ export interface CFProduct {
     sku?: string;
     productType: CFProductType;
     variants: CFProductVariant[];
-    minPrice?: string;
-    maxPrice?: string;
+    currency: CurrencyCode;
+    minorUnits: number;
+    minPrice?: number;
+    maxPrice?: number;
     status?: string;
     isDeleted?: boolean;
 }
@@ -172,40 +217,42 @@ export interface CFActiveCustomer extends CFCustomer {
     id?: string;
 }
 export interface CFTip {
-    amount: string;
+    amount: number;
     percentage: number;
 }
 export interface CFSummary {
-    discountTotal: string;
-    shippingTotal?: string | null;
-    total: string;
-    totalTaxes: string;
-    subTotal: string;
+    discountTotal: number;
+    shippingTotal?: number | null;
+    total: number;
+    totalTaxes: number;
+    subTotal: number;
     taxes: CFTax[];
     tip?: CFTip | null;
     isTaxInclusive: boolean;
+    /** Portion of order total that is non-revenue (e.g. gift card load), same string money format as `total` */
+    nonRevenueTotal?: string;
 }
 export interface CFCartDiscountItem {
     label: string;
-    amount: string;
+    amount: number;
     percentage: number;
 }
 export interface CFCartFeeItem {
     id: string;
     label: string;
-    amount: string;
+    amount: number;
     percentage: number;
     taxTableId?: string;
-    tax?: string;
+    tax?: number;
     taxName: string;
 }
 export interface CFTipPayment {
-    amount: string;
+    amount: number;
     tipTo: string;
     percentage: number;
 }
 export interface CFRefundedTipPayment {
-    amount: string;
+    amount: number;
     percentage: number;
     transactionId: string;
     tipTo: string;
@@ -213,11 +260,11 @@ export interface CFRefundedTipPayment {
 export interface CFPaymentMethod {
     transactionId: string;
     paymentType: string;
-    amount: string;
+    amount: number;
     timestamp: string;
     processor: string;
     saleId?: string;
-    change?: string | null;
+    change?: number | null;
     tip?: CFTipPayment | null;
     cashRounding?: number;
     emv?: string | null;
@@ -233,13 +280,13 @@ export interface CFPosDataItem {
 }
 export interface CFDiscountDetail {
     percentage: number;
-    amount: string;
+    amount: number;
     label?: string;
 }
 export interface CFFeeDetail {
     percentage: number;
-    amount: string;
-    tax: string;
+    amount: number;
+    tax: number;
     taxTableId: string;
     label?: string;
 }
@@ -258,12 +305,12 @@ export interface CFLineItem {
     internalId?: string;
     name: string;
     quantity: number;
-    price: string;
+    price: number;
     taxes: CFTax[];
     discount: CFDiscountLineItem;
     fee: CFFeeLineItem;
-    totalTax: string;
-    total: string;
+    totalTax: number;
+    total: number;
     metadata: CFMetadataItem[];
     image: string;
     sku: string;
@@ -277,11 +324,11 @@ export interface CFLineItem {
 export interface CFCustomSale {
     customSaleId: string;
     name: string;
-    price: string;
+    price: number;
     quantity: number;
     applyTaxes: boolean;
-    total: string;
-    totalTax: string;
+    total: number;
+    totalTax: number;
     taxes: CFTax[];
     discount: {
         cartDiscount: CFDiscountDetail;
@@ -298,11 +345,11 @@ export interface CFRefundedLineItem {
     internalId?: string;
     name: string;
     quantity: number;
-    price: string;
+    price: number;
     taxes: CFTax[];
     discount: CFDiscountLineItem;
-    totalTax: string;
-    total: string;
+    totalTax: number;
+    total: number;
     image: string;
     sku: string;
     note?: string;
@@ -321,12 +368,15 @@ export interface CFRefundItem {
     timestamp: string | undefined;
     summary?: CFSummary;
     refundPayment: CFPaymentMethod[];
-    balance?: string;
+    balance?: number;
     receiptId?: string;
-    currency?: string;
+    currency: CurrencyCode;
+    minorUnits: number;
 }
 export interface CFOrder {
     _id: string;
+    currency: CurrencyCode;
+    minorUnits: number;
     receiptId?: string;
     companyId: string;
     externalId: string | null;
@@ -348,8 +398,10 @@ export interface CFOrder {
     shipping: CFAddress | null;
     lineItems: CFLineItem[];
     customSales: CFCustomSale[];
+    /** Gift card / liability purchase lines (not product revenue) */
+    nonRevenueItems?: CFNonRevenueItem[];
     refund?: CFRefundItem[];
-    balance: string;
+    balance: number;
     signature?: string | null;
 }
 export interface CFActiveUserRole {
@@ -420,7 +472,6 @@ export interface CFActiveOrder extends CFOrder {
     outlet?: CFActiveOutlet;
     isDeleted?: boolean;
     newOrder?: boolean;
-    currency?: string;
     station?: CFActiveStation;
 }
 export interface CFActiveCustomSales {
@@ -433,6 +484,15 @@ export interface CFActiveCustomSales {
     discount?: any;
     fee?: any;
 }
+/** Non-revenue cart line (e.g. gift card load) — aligned with Render NonRevenueItem */
+export interface CFNonRevenueItem {
+    id: string;
+    amount: number | string;
+    label?: string;
+    metadata?: Record<string, unknown>;
+    applyTaxes?: boolean;
+    taxTableId?: string;
+}
 export interface CFActiveCart extends CFActiveEntity {
     tax?: number;
     total: number;
@@ -441,6 +501,8 @@ export interface CFActiveCart extends CFActiveEntity {
     customFee?: CFCustomFee[];
     products: CFActiveProduct[];
     customSales?: CFActiveCustomSales[];
+    /** Gift card / liability lines — included in cart total */
+    nonRevenueItems?: CFNonRevenueItem[];
     remainingBalance?: number;
     amountToBeCharged: number;
     customer?: Partial<CFCustomer | null> | null;

package/dist/CommonTypes.js

@@ -1,4 +1,48 @@
 export * from "./common-types";
+export var CurrencyCode;
+(function (CurrencyCode) {
+    CurrencyCode["USD"] = "USD";
+    CurrencyCode["EUR"] = "EUR";
+    CurrencyCode["GBP"] = "GBP";
+    CurrencyCode["CAD"] = "CAD";
+    CurrencyCode["AUD"] = "AUD";
+    CurrencyCode["NZD"] = "NZD";
+    CurrencyCode["CHF"] = "CHF";
+    CurrencyCode["CNY"] = "CNY";
+    CurrencyCode["INR"] = "INR";
+    CurrencyCode["MXN"] = "MXN";
+    CurrencyCode["BRL"] = "BRL";
+    CurrencyCode["ZAR"] = "ZAR";
+    CurrencyCode["SGD"] = "SGD";
+    CurrencyCode["HKD"] = "HKD";
+    CurrencyCode["SEK"] = "SEK";
+    CurrencyCode["NOK"] = "NOK";
+    CurrencyCode["DKK"] = "DKK";
+    CurrencyCode["PLN"] = "PLN";
+    CurrencyCode["THB"] = "THB";
+    CurrencyCode["MYR"] = "MYR";
+    CurrencyCode["PHP"] = "PHP";
+    CurrencyCode["IDR"] = "IDR";
+    CurrencyCode["AED"] = "AED";
+    CurrencyCode["SAR"] = "SAR";
+    CurrencyCode["ILS"] = "ILS";
+    CurrencyCode["TRY"] = "TRY";
+    CurrencyCode["RUB"] = "RUB";
+    CurrencyCode["JPY"] = "JPY";
+    CurrencyCode["KRW"] = "KRW";
+    CurrencyCode["VND"] = "VND";
+    CurrencyCode["CLP"] = "CLP";
+    CurrencyCode["ISK"] = "ISK";
+    CurrencyCode["HUF"] = "HUF";
+    CurrencyCode["TWD"] = "TWD";
+    CurrencyCode["KWD"] = "KWD";
+    CurrencyCode["BHD"] = "BHD";
+    CurrencyCode["OMR"] = "OMR";
+    CurrencyCode["JOD"] = "JOD";
+    CurrencyCode["TND"] = "TND";
+    CurrencyCode["LYD"] = "LYD";
+    CurrencyCode["IQD"] = "IQD";
+})(CurrencyCode || (CurrencyCode = {}));
 // Enums
 export var CFProductType;
 (function (CFProductType) {

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

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

package/dist/actions/add-non-revenue-item/action.js

@@ -0,0 +1,4 @@
+import { commandFrameClient } from "../../client";
+export const addNonRevenueItem = async (params) => {
+    return await commandFrameClient.call("addNonRevenueItem", params);
+};

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

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

package/dist/actions/add-non-revenue-item/mock.js

@@ -0,0 +1,41 @@
+import { MOCK_CART } from "../../demo/database";
+export const mockAddNonRevenueItem = async (params) => {
+    console.log("[Mock] addNonRevenueItem called", params);
+    const amount = Number(params.amount);
+    if (!Number.isFinite(amount) || amount <= 0) {
+        throw new Error("amount must be a positive number");
+    }
+    const lineId = `nr-mock-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+    const refId = params.id;
+    const metadata = {
+        ...(params.metadata ?? {}),
+        refId
+    };
+    const row = {
+        id: lineId,
+        amount,
+        applyTaxes: params.applyTaxes === true,
+        ...(params.taxTableId ? { taxTableId: params.taxTableId } : {}),
+        ...(params.label !== undefined ? { label: params.label } : {}),
+        metadata
+    };
+    if (!MOCK_CART.nonRevenueItems) {
+        MOCK_CART.nonRevenueItems = [];
+    }
+    MOCK_CART.nonRevenueItems.push(row);
+    MOCK_CART.total += amount;
+    MOCK_CART.amountToBeCharged = MOCK_CART.total;
+    MOCK_CART.remainingBalance = MOCK_CART.total;
+    MOCK_CART.subtotal = (MOCK_CART.subtotal ?? 0) + amount;
+    return {
+        success: true,
+        id: lineId,
+        refId,
+        amount,
+        label: params.label,
+        metadata,
+        ...(params.applyTaxes === true ? { applyTaxes: true } : {}),
+        ...(params.taxTableId ? { taxTableId: params.taxTableId } : {}),
+        timestamp: new Date().toISOString()
+    };
+};

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

@@ -0,0 +1,36 @@
+/**
+ * Add a non-revenue line to the host cart (e.g. gift card liability / load).
+ * Extensions send id, amount, and optional label/metadata; host sums into cart total.
+ */
+export interface AddNonRevenueItemParams {
+    /**
+     * Reference id from the extension (e.g. product/sku key). Stored in cart line metadata as refId.
+     * 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: number;
+    /** Short label for receipts/UI */
+    label?: string;
+    /** Extra fields (customTableId, cardCode, etc.) */
+    metadata?: Record<string, unknown>;
+    /**
+     * When true, line may be taxed (requires taxTableId when taxing is implemented). Default false — e.g. gift card load is typically not taxed.
+     */
+    applyTaxes?: boolean;
+    taxTableId?: string;
+}
+export interface AddNonRevenueItemResponse {
+    success: true;
+    /** Unique cart line id (use for remove / correlation) */
+    id: string;
+    /** Same as request `id` — extension reference */
+    refId: string;
+    amount: number;
+    label?: string;
+    metadata?: Record<string, unknown>;
+    applyTaxes?: boolean;
+    taxTableId?: string;
+    timestamp: string;
+}
+export type AddNonRevenueItem = (params: AddNonRevenueItemParams) => Promise<AddNonRevenueItemResponse>;

package/dist/actions/add-non-revenue-item/types.js

@@ -0,0 +1 @@
+export {};

package/dist/actions/add-product/mock.js

@@ -1,10 +1,12 @@
-import { CFProductType } from "../../CommonTypes";
+import { CFProductType, CurrencyCode } from "../../CommonTypes";
 export const mockAddProduct = async (params) => {
     console.log("[Mock] addProduct called", params);
     const hasVariants = params.variants && params.variants.length > 0;
     return {
         product: {
             _id: "mock_product_" + Date.now(),
+            currency: CurrencyCode.USD,
+            minorUnits: 2,
             name: params.name,
             description: params.description,
             categories: params.categories || [],
@@ -14,15 +16,15 @@ export const mockAddProduct = async (params) => {
             sku: params.sku,
             productType: hasVariants ? CFProductType.VARIABLE : CFProductType.SIMPLE,
             attributes: [],
-            minPrice: params.price || "0",
-            maxPrice: params.price || "0",
+            minPrice: params.price || 0,
+            maxPrice: params.price || 0,
             variants: hasVariants
                 ? params.variants.map((v, i) => ({ ...v, _id: `mock_variant_${Date.now()}_${i}` }))
                 : [{
                         _id: `mock_variant_${Date.now()}_0`,
                         sku: params.sku || "",
-                        price: params.price || "0",
-                        salePrice: "0",
+                        price: params.price || 0,
+                        salePrice: 0,
                         isOnSale: false,
                         manageStock: params.manageStock || false,
                         attributes: [],

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

@@ -7,9 +7,9 @@ export interface AddProductParams {
     images?: string[];
     status?: 'active' | 'inactive';
     /** For simple products: set price directly */
-    price?: string;
+    price?: number;
     sku?: string;
-    costPrice?: string;
+    costPrice?: number;
     manageStock?: boolean;
     /** For variable products: provide variants array */
     variants?: Omit<CFProductVariant, '_id'>[];

package/dist/actions/edit-product/mock.js

@@ -1,9 +1,11 @@
-import { CFProductType } from "../../CommonTypes";
+import { CFProductType, CurrencyCode } from "../../CommonTypes";
 export const mockEditProduct = async (params) => {
     console.log("[Mock] editProduct called", params);
     return {
         product: {
             _id: params.productId,
+            currency: CurrencyCode.USD,
+            minorUnits: 2,
             name: params.changes.name || "Updated Product",
             description: params.changes.description,
             categories: params.changes.categories || [],

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

@@ -0,0 +1,5 @@
+/**
+ * Generic extension payment — host handles wire action `extensionPayment` and routes by `paymentType`.
+ */
+import type { ExtensionPayment } from "./types";
+export declare const extensionPayment: ExtensionPayment;

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

@@ -0,0 +1,7 @@
+/**
+ * Generic extension payment — host handles wire action `extensionPayment` and routes by `paymentType`.
+ */
+import { commandFrameClient } from "../../client";
+export const extensionPayment = async (params) => {
+    return await commandFrameClient.call("extensionPayment", params);
+};

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

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

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

@@ -0,0 +1,11 @@
+import { MOCK_ORDERS } from "../../demo/database";
+export const mockExtensionPayment = async (params) => {
+    const paymentType = params?.paymentType ?? "redeem";
+    return {
+        success: true,
+        amount: params?.amount ?? null,
+        paymentType,
+        order: MOCK_ORDERS[0],
+        timestamp: new Date().toISOString()
+    };
+};

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

@@ -0,0 +1,19 @@
+import { CFOrder } from "../../CommonTypes";
+/** Params for extension-initiated payments; host routes by `paymentType`. */
+export interface ExtensionPaymentParams {
+    paymentType: string;
+    processor?: string;
+    amount?: number;
+    label?: string;
+    referenceId?: string;
+    extensionId?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface ExtensionPaymentResponse {
+    success: boolean;
+    amount: number | null;
+    paymentType: string;
+    order: CFOrder | null;
+    timestamp: string;
+}
+export type ExtensionPayment = (params?: ExtensionPaymentParams) => Promise<ExtensionPaymentResponse>;

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

@@ -0,0 +1 @@
+export {};

package/dist/actions/extension-refund/constants.d.ts

@@ -0,0 +1,2 @@
+/** postMessage `action` for host → iframe extension refund requests. */
+export declare const EXTENSION_REFUND_REQUEST_ACTION = "extensionRefundRequest";

package/dist/actions/extension-refund/constants.js

@@ -0,0 +1,2 @@
+/** postMessage `action` for host → iframe extension refund requests. */
+export const EXTENSION_REFUND_REQUEST_ACTION = "extensionRefundRequest";

package/dist/actions/extension-refund/extension-refund-listener.d.ts

@@ -0,0 +1,11 @@
+import type { ExtensionRefundParams, ExtensionRefundResponse } from "./types";
+/**
+ * Install a message listener in the **extension iframe** so the host can request refunds.
+ * Validates `event.source === window.parent` before handling.
+ *
+ * Replies with {@link PostMessageResponse}, using `event.origin` as the target origin when posting back to the parent.
+ *
+ * @param handler - Perform the extension-side refund (API call, etc.)
+ * @returns Unsubscribe function
+ */
+export declare function installExtensionRefundListener(handler: (params: ExtensionRefundParams) => Promise<ExtensionRefundResponse>): () => void;

package/dist/actions/extension-refund/extension-refund-listener.js

@@ -0,0 +1,60 @@
+import { EXTENSION_REFUND_REQUEST_ACTION } from "./constants";
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Install a message listener in the **extension iframe** so the host can request refunds.
+ * Validates `event.source === window.parent` before handling.
+ *
+ * Replies with {@link PostMessageResponse}, using `event.origin` as the target origin when posting back to the parent.
+ *
+ * @param handler - Perform the extension-side refund (API call, etc.)
+ * @returns Unsubscribe function
+ */
+export function installExtensionRefundListener(handler) {
+    const onMessage = async (event) => {
+        const raw = event.data;
+        if (!isRecord(raw) || raw.action !== EXTENSION_REFUND_REQUEST_ACTION) {
+            return;
+        }
+        const requestId = raw.requestId;
+        if (typeof requestId !== "string") {
+            return;
+        }
+        if (event.source !== window.parent || !event.source) {
+            return;
+        }
+        const source = event.source;
+        const replyOrigin = typeof event.origin === "string" ? event.origin : "*";
+        const params = raw.params;
+        try {
+            if (!params || typeof params.paymentType !== "string" || typeof params.amount !== "number" || typeof params.saleId !== "string") {
+                const errPayload = {
+                    requestId,
+                    success: false,
+                    error: "Invalid extension refund params"
+                };
+                source.postMessage(errPayload, replyOrigin);
+                return;
+            }
+            const result = await handler(params);
+            const payload = {
+                requestId,
+                success: true,
+                data: result
+            };
+            source.postMessage(payload, replyOrigin);
+        }
+        catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            const errPayload = {
+                requestId,
+                success: false,
+                error: message
+            };
+            source.postMessage(errPayload, replyOrigin);
+        }
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+}