@final-commerce/command-frame 0.1.63 → 0.1.72

package/dist/CommonTypes.d.ts

@@ -60,8 +60,7 @@ export declare enum CFUserTypes {
     CASHIER = "cashier",
     RESELLER = "reseller"
 }
-export interface CFActiveEntity {
-}
+export type CFActiveEntity = Record<string, unknown>;
 export interface CFDiscount {
     value: number;
     label?: string;
@@ -97,8 +96,26 @@ export interface CFTax {
     amount: number;
     taxTableName: string;
     taxTableId: string;
+    /** Whether this tax compounds on top of others. */
+    compounding?: boolean;
+    /** Application order; lower numbers apply first. */
+    priority?: number;
+}
+/** Per-rate tax entry on a cart fee (gst, hst, etc.). Same shape as `CFTax`; declared
+ *  separately to match the host's distinct `CartFeeTaxEntry` type. */
+export interface CFCartFeeTaxEntry {
+    id: string;
+    name: string;
+    percentage: number;
+    amount: number;
+    taxTableId: string;
+    taxTableName: string;
+    compounding?: boolean;
+    priority?: number;
 }
 export interface CFInventory {
+    /** Warehouse identifier the stock is held at. */
+    warehouse: string;
     outletId: string;
     stock?: number | null;
     _id?: string;
@@ -116,6 +133,29 @@ export interface CFOrderNote {
     addedByUser?: string;
     dateCreated?: string;
 }
+export interface CFAttributeOption {
+    name: string;
+    order?: number;
+}
+export interface CFAttribute {
+    _id: string;
+    companyId?: string;
+    optionName: string;
+    sortingOrder: number;
+    options: CFAttributeOption[];
+}
+export interface CFTransaction {
+    _id: string;
+    companyId?: string;
+    orderId?: string;
+    amount: number;
+    currency?: string;
+    status?: string;
+    paymentMethod?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    [key: string]: unknown;
+}
 export interface CFCategory {
     _id: string;
     companyId: string;
@@ -132,7 +172,8 @@ export interface CFProductVariant {
     barcode?: string;
     costPrice?: number;
     manageStock: boolean;
-    externalId?: string;
+    /** External variant identifier — required by host. */
+    externalId: string;
     inventory?: CFInventory[];
     allowBackorder?: boolean;
     images?: string[];
@@ -145,11 +186,15 @@ export interface CFProductVariant {
         value: string;
     }[];
     _id: string;
+    isDeleted?: boolean;
+    currency?: CurrencyCode;
+    minorUnits?: number;
 }
 export interface CFProduct {
     _id: string;
     companyId?: string;
-    externalId?: string;
+    /** External product identifier — required by host. */
+    externalId: string;
     taxTable: string;
     name: string;
     description?: string;
@@ -169,8 +214,12 @@ export interface CFProduct {
     minorUnits: number;
     minPrice?: number;
     maxPrice?: number;
+    /** Catalog-level price (rare; usually only on simple products). */
+    price?: number;
     status?: string;
     isDeleted?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
 }
 export interface CFActiveProduct extends CFActiveEntity {
     id: string;
@@ -196,6 +245,13 @@ export interface CFActiveProduct extends CFActiveEntity {
     isUnlimited?: boolean;
     attributes?: string;
     localQuantity?: number;
+    /** Mongo-style id when the active product retains the catalog `_id`. */
+    _id?: string;
+    productType?: CFProductType;
+    /** Currency code for the line price. */
+    currency?: CurrencyCode;
+    /** Number of minor units (decimal places) for the line currency. */
+    minorUnits?: number;
 }
 export interface CFCustomer {
     _id: string;
@@ -246,6 +302,8 @@ export interface CFCartFeeItem {
     taxTableId?: string;
     tax?: number;
     taxName: string;
+    /** Per-rate breakdown so summary/refund views can show correct amounts per rate. */
+    taxes?: CFCartFeeTaxEntry[];
 }
 export interface CFTipPayment {
     amount: number;
@@ -269,6 +327,30 @@ export interface CFPaymentMethod {
     tip?: CFTipPayment | null;
     cashRounding?: number;
     emv?: string | null;
+    /** Processor fee charged on this payment. */
+    processorFee?: number | null;
+}
+/**
+ * Status of an in-progress payment / split-payment session. Mirrors render's
+ * `PaymentStatus` enum (`failed | success | canceled | inProgress`).
+ */
+export type CFPaymentStatus = "failed" | "success" | "canceled" | "inProgress";
+/**
+ * In-progress split-payment session state. Mirrors render's `ActiveSplitPayment`.
+ * Published over the `split-payments` topic whenever the slice mutates so that
+ * builder consumers can render partial-payment progress (e.g. a cart-payments
+ * repeater) without owning the underlying Redux state.
+ */
+export interface CFSplitPayment {
+    amountRemaining?: number | null;
+    amountToBeCharged?: number | null;
+    splitNumber?: null | number;
+    currentSplit?: number;
+    status?: CFPaymentStatus;
+    isFixed?: boolean;
+    payments?: null | CFPaymentMethod[];
+    paidAmount?: number;
+    tip?: number | null;
 }
 export interface CFPosDataItem {
     outlet: string;
@@ -404,6 +486,10 @@ export interface CFOrder {
     refund?: CFRefundItem[];
     balance: number;
     signature?: string | null;
+    /** ISO timestamp at which a parked order's stock reservation expires. */
+    parkExpiryDate?: string;
+    /** Park stock-reduction policy (host-defined string flag). */
+    parkReduceStock?: string;
 }
 export interface CFActiveUserRole {
     id?: string;
@@ -465,6 +551,12 @@ export interface CFActiveStation {
     createdAt?: string;
     updatedAt?: string;
     stripeTerminalId?: string;
+    /** Stripe serial-reader identifier when paired. */
+    serialReaderId?: string;
+    /** User id of whoever enrolled the station. */
+    enrolledBy?: string;
+    /** Whether the station is virtual (no physical terminal). */
+    isVirtual?: boolean;
 }
 /** Cash register session (station session), aligned with Render `Session`. */
 export interface CFSession {
@@ -530,6 +622,8 @@ export interface CFNonRevenueItem {
 }
 export interface CFActiveCart extends CFActiveEntity {
     tax?: number;
+    /** Per-rate tax breakdown for the cart. Same shape as line item taxes. */
+    taxes?: CFTax[];
     total: number;
     subtotal: number;
     discount?: CFDiscount;
@@ -545,6 +639,22 @@ export interface CFActiveCart extends CFActiveEntity {
     cartTotal?: number;
     orderTotal?: number;
     orderId?: string;
+    /** Currency code for amounts on this cart. */
+    currency?: CurrencyCode;
+    /** Number of minor units (decimal places) for the cart's currency. */
+    minorUnits?: number;
+}
+/** A parked order. Extends `CFActiveCart` with parking-specific fields. */
+export interface CFActivePark extends CFActiveCart {
+    /** Required on parked orders (overrides the optional `orderId` on the parent). */
+    orderId: string;
+    receiptId: string;
+    servedBy: string | {
+        _id?: string;
+        firstName: string;
+        lastName: string;
+    } | undefined;
+    createdAt: string | number;
 }
 export interface CFActiveCompany extends CFActiveEntity {
     id?: string;
@@ -568,10 +678,16 @@ export interface CFContextRender {
     buildSourceId: string | null;
     buildIsPremium: boolean;
     isOffline: boolean;
-    user: Record<string, any> | null;
-    company: Omit<Record<string, any>, 'settings'> | null;
-    station: Record<string, any> | null;
-    outlet: Record<string, any> | null;
+    currency: string | null;
+    currencySymbol: string | null;
+    currencyPrefix: string | null;
+    currencySuffix: string | null;
+    thousandSeparator: string | null;
+    decimalSeparator: string | null;
+    user: Record<string, unknown> | null;
+    company: Omit<Record<string, unknown>, "settings"> | null;
+    station: Record<string, unknown> | null;
+    outlet: Record<string, unknown> | null;
     timestamp: string;
 }
 export interface CFOutletInfo {
@@ -591,11 +707,11 @@ export interface CFOutletInfo {
     country?: string;
 }
 export interface CFContextManage {
-    user: any;
-    company: any;
-    menuItem?: any;
+    user: unknown;
+    company: unknown;
+    menuItem?: unknown;
     extensionId: string;
-    outlets?: any[];
+    outlets?: unknown[];
     timestamp: string;
 }
 export type CFContext = CFContextRender;

package/dist/actions/add-customer-note/mock.js

@@ -1,23 +1,32 @@
-import { MOCK_CUSTOMERS } from "../../demo/database";
-export const mockAddCustomerNote = async (params) => {
+import { MOCK_CUSTOMERS, mockPublishEvent } from "../../demo/database";
+function generateNoteId() {
+    return `mock_note_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+}
+export const mockAddCustomerNote = (params) => {
     console.log("[Mock] addCustomerNote called", params);
-    if (params?.customerId && params.note) {
-        const customer = MOCK_CUSTOMERS.find(c => c._id === params.customerId);
-        if (customer) {
-            if (!customer.notes) {
-                customer.notes = [];
-            }
-            customer.notes.push({
-                _id: `mock_note_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`,
-                message: params.note,
-                createdAt: new Date().toISOString()
-            });
-        }
+    if (!params?.note) {
+        throw new Error("addCustomerNote: note is required");
     }
-    return {
+    const target = params.customerId ? MOCK_CUSTOMERS.find(c => c._id === params.customerId) : MOCK_CUSTOMERS[0];
+    if (!target) {
+        throw new Error("addCustomerNote: no target customer (provide customerId or seed at least one mock customer)");
+    }
+    const noteId = generateNoteId();
+    const note = {
+        _id: noteId,
+        message: params.note,
+        createdAt: new Date().toISOString()
+    };
+    target.notes = [...(target.notes || []), note];
+    mockPublishEvent("customers", "customer-note-added", {
+        customer: target,
+        note
+    });
+    return Promise.resolve({
         success: true,
-        customerId: params?.customerId || "",
-        note: params?.note || "",
+        customerId: target._id,
+        noteId,
+        note: params.note,
         timestamp: new Date().toISOString()
-    };
+    });
 };

package/dist/actions/add-customer-note/types.d.ts

@@ -1,11 +1,12 @@
 export interface AddCustomerNoteParams {
-    customerId: string;
     note: string;
+    customerId?: string;
 }
 export interface AddCustomerNoteResponse {
     success: boolean;
     customerId: string;
+    noteId: string;
     note: string;
     timestamp: string;
 }
-export type AddCustomerNote = (params?: AddCustomerNoteParams) => Promise<AddCustomerNoteResponse>;
+export type AddCustomerNote = (params: AddCustomerNoteParams) => Promise<AddCustomerNoteResponse>;

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

@@ -1,10 +1,13 @@
 import { CFProductType, CurrencyCode } from "../../CommonTypes";
+// eslint-disable-next-line @typescript-eslint/require-await
 export const mockAddProduct = async (params) => {
     console.log("[Mock] addProduct called", params);
     const hasVariants = params.variants && params.variants.length > 0;
+    const productId = "mock_product_" + Date.now();
     return {
         product: {
-            _id: "mock_product_" + Date.now(),
+            _id: productId,
+            externalId: `ext_${productId}`,
             currency: CurrencyCode.USD,
             minorUnits: 2,
             name: params.name,
@@ -20,16 +23,19 @@ export const mockAddProduct = async (params) => {
             maxPrice: params.price || 0,
             variants: hasVariants
                 ? params.variants.map((v, i) => ({ ...v, _id: `mock_variant_${Date.now()}_${i}` }))
-                : [{
+                : [
+                    {
                         _id: `mock_variant_${Date.now()}_0`,
+                        externalId: `ext_variant_${Date.now()}_0`,
                         sku: params.sku || "",
                         price: params.price || 0,
                         salePrice: 0,
                         isOnSale: false,
                         manageStock: params.manageStock || false,
-                        attributes: [],
-                    }],
+                        attributes: []
+                    }
+                ]
         },
-        timestamp: new Date().toISOString(),
+        timestamp: new Date().toISOString()
     };
 };

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

@@ -1,9 +1,11 @@
 import { CFProductType, CurrencyCode } from "../../CommonTypes";
+// eslint-disable-next-line @typescript-eslint/require-await
 export const mockEditProduct = async (params) => {
     console.log("[Mock] editProduct called", params);
     return {
         product: {
             _id: params.productId,
+            externalId: `ext_${params.productId}`,
             currency: CurrencyCode.USD,
             minorUnits: 2,
             name: params.changes.name || "Updated Product",
@@ -14,8 +16,8 @@ export const mockEditProduct = async (params) => {
             status: params.changes.status || "active",
             productType: CFProductType.SIMPLE,
             attributes: [],
-            variants: [],
+            variants: []
         },
-        timestamp: new Date().toISOString(),
+        timestamp: new Date().toISOString()
     };
 };

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

@@ -8,6 +8,10 @@ export interface ExtensionPaymentParams {
     referenceId?: string;
     extensionId?: string;
     metadata?: Record<string, unknown>;
+    /** 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. */
+    processorFee?: number;
 }
 export interface ExtensionPaymentResponse {
     success: boolean;

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

@@ -1,8 +1,8 @@
 import { MOCK_COMPANY, MOCK_OUTLET, MOCK_STATION, MOCK_USER } from "../../demo/database";
 // Mock for Render context (POS terminal)
-export const mockGetContext = async () => {
+export const mockGetContext = () => {
     console.log("[Mock] getContext called (Render)");
-    return {
+    return Promise.resolve({
         userId: MOCK_USER.id || null,
         companyId: MOCK_COMPANY.id || null,
         companyName: MOCK_COMPANY.name || null,
@@ -17,17 +17,23 @@ export const mockGetContext = async () => {
         buildSourceId: "mock_source_id",
         buildIsPremium: true,
         isOffline: false,
+        currency: "USD",
+        currencySymbol: "$",
+        currencyPrefix: "$",
+        currencySuffix: "",
+        thousandSeparator: ",",
+        decimalSeparator: ".",
         user: null,
         company: null,
         station: null,
         outlet: null,
         timestamp: new Date().toISOString()
-    };
+    });
 };
 // Mock for Manage context (Hub/BuilderHub)
-export const mockGetContextManage = async () => {
+export const mockGetContextManage = () => {
     console.log("[Mock] getContext called (Manage)");
-    return {
+    return Promise.resolve({
         user: {
             _id: MOCK_USER.id,
             id: MOCK_USER.id,
@@ -47,5 +53,5 @@ export const mockGetContextManage = async () => {
         extensionId: "mock_extension_id",
         outlets: [MOCK_OUTLET],
         timestamp: new Date().toISOString()
-    };
+    });
 };

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

@@ -24,8 +24,13 @@ export const mockGetProducts = async (params) => {
             products = products.filter(p => (p.categories || []).includes(containsVal));
         }
     }
+    const total = products.length;
+    const offset = params?.offset ?? 0;
+    const limit = params?.limit ?? 100;
+    const paged = products.slice(offset, offset + limit);
     return {
-        products: safeSerialize(products),
+        products: safeSerialize(paged),
+        total,
         timestamp: new Date().toISOString()
     };
 };

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

@@ -29,6 +29,8 @@ export interface GetProductsParams {
 }
 export interface GetProductsResponse {
     products: CFProduct[];
+    /** Total number of products matching the query, ignoring offset/limit. Optional — hosts that cannot cheaply compute the total may omit it. */
+    total?: number;
     timestamp: string;
 }
 export type GetProducts = (params?: GetProductsParams) => Promise<GetProductsResponse>;

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

@@ -0,0 +1,5 @@
+/**
+ * Integration payment — thin wrapper over {@link extensionPayment} with `paymentType: "integration"`.
+ */
+import type { IntegrationPayment } from "./types";
+export declare const integrationPayment: IntegrationPayment;

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

@@ -0,0 +1,7 @@
+/**
+ * Integration payment — thin wrapper over {@link extensionPayment} with `paymentType: "integration"`.
+ */
+import { extensionPayment } from "../extension-payment/action";
+export const integrationPayment = async (params) => {
+    return extensionPayment({ ...params, paymentType: "integration" });
+};

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

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

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

@@ -0,0 +1,4 @@
+import { mockExtensionPayment } from "../extension-payment/mock";
+export const mockIntegrationPayment = async (params) => {
+    return mockExtensionPayment({ ...params, paymentType: "integration" });
+};

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

@@ -0,0 +1,56 @@
+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;
+ * 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
+ * extension passes camelCase, the order's persisted shape is unchanged from the
+ * native card flow.
+ *
+ * All fields are optional; the more you supply, the richer the receipt and the
+ * transactions row will be. At minimum, supplying `brand` and `cardNumberLast4`
+ * produces the typical "Visa **** **** **** 4242" row.
+ */
+export interface IntegrationEmvData {
+    /** Card brand, e.g. "Visa", "MasterCard". → "Brand" */
+    brand?: string;
+    /** Cardholder name as printed on the card. → "Cardholder Name" */
+    cardholderName?: string;
+    /** Issuing country (ISO 3166-1 alpha-2), e.g. "US". → "Country" */
+    country?: string;
+    /** Display expiry, e.g. "12/26". → "Expiry date" */
+    expiryDate?: string;
+    /** Issuer / bank name. → "Issuer" */
+    issuer?: string;
+    /** Last 4 digits of the card. Render 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.
+ *
+ * Required fields (compile-time enforced by TS, runtime-enforced by the host handler):
+ *   - `amount` — minor units of the captured amount
+ *   - `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.
+ */
+export interface IntegrationPaymentParams {
+    amount: number;
+    emvData: IntegrationEmvData;
+    /** Human-readable label (e.g. "Visa ****4242"); shown in the transaction list. */
+    label?: string;
+    /** Identifier of the extension making the call; audit/debug link. */
+    extensionId?: string;
+    /** Label/name of the integration (e.g. "Stripe", "AMP"). Stored on the order's paymentMethod.processor. */
+    processor?: string;
+    referenceId?: string;
+    metadata?: Record<string, unknown>;
+    /** Provider fee in minor units — stored on paymentMethod.processorFee. */
+    processorFee?: number;
+}
+export type IntegrationPaymentResponse = ExtensionPaymentResponse;
+export type IntegrationPayment = (params: IntegrationPaymentParams) => Promise<IntegrationPaymentResponse>;

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

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

package/dist/actions/print/mock.js

@@ -1,4 +1,4 @@
-export const mockPrint = async (params) => {
+export const mockPrint = (params) => {
     console.log("[Mock] print called", params);
     if (!params) {
         throw new Error("Print parameters are required");
@@ -11,16 +11,13 @@ export const mockPrint = async (params) => {
         case "html":
             console.log("[Mock] Would print HTML:", params.data.html?.substring(0, 100) + "...");
             break;
-        case "selector":
-            console.log("[Mock] Would print element with selector:", params.data.selector);
-            break;
         case "receipt":
             console.log("[Mock] Would print receipt for order:", params.data.order);
             break;
     }
-    return {
+    return Promise.resolve({
         success: true,
         timestamp: new Date().toISOString(),
         type: params.type
-    };
+    });
 };

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

@@ -1,5 +1,5 @@
 import type { CFActiveOrder } from "../../CommonTypes";
-export type PrintType = "image" | "html" | "selector" | "receipt";
+export type PrintType = "image" | "html" | "receipt";
 export type PrintParams = {
     type: "image";
     data: {
@@ -12,12 +12,6 @@ export type PrintParams = {
         html: string;
     };
     options?: PrintOptions;
-} | {
-    type: "selector";
-    data: {
-        selector: string;
-    };
-    options?: PrintOptions;
 } | {
     type: "receipt";
     data: {

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

@@ -1,12 +1,16 @@
 import type { ExtensionPaymentResponse } from "../extension-payment/types";
-/** Redeem (e.g. gift card) — always uses paymentType `"redeem"` on the wire. */
+/**
+ * Redeem (e.g. gift card) — always uses paymentType `"redeem"` on the wire.
+ * `amount` is required so the persisted payment never silently falls back to the cart
+ * total. The host handler also re-validates this at runtime to catch raw-postMessage callers.
+ */
 export interface RedeemPaymentParams {
-    amount?: number;
-    processor?: string;
+    amount: number;
     label?: string;
-    referenceId?: string;
     extensionId?: string;
+    processor?: string;
+    referenceId?: string;
     metadata?: Record<string, unknown>;
 }
 export type RedeemPaymentResponse = ExtensionPaymentResponse;
-export type RedeemPayment = (params?: RedeemPaymentParams) => Promise<RedeemPaymentResponse>;
+export type RedeemPayment = (params: RedeemPaymentParams) => Promise<RedeemPaymentResponse>;

package/dist/actions/remove-customer-note/mock.js

@@ -1,13 +1,22 @@
-export const mockRemoveCustomerNote = async (params) => {
+import { MOCK_CUSTOMERS, mockPublishEvent } from "../../demo/database";
+export const mockRemoveCustomerNote = (params) => {
     console.log("[Mock] removeCustomerNote called", params);
     const noteId = params?.noteId ?? "";
     const timestamp = new Date().toISOString();
     if (!noteId) {
-        return { success: false, noteId, timestamp };
+        return Promise.resolve({ success: false, noteId, timestamp });
     }
-    return {
-        success: true,
-        noteId,
-        timestamp
-    };
+    for (const customer of MOCK_CUSTOMERS) {
+        const before = customer.notes?.length ?? 0;
+        const removed = (customer.notes || []).find(n => n._id === noteId);
+        customer.notes = (customer.notes || []).filter(n => n._id !== noteId);
+        if ((customer.notes?.length ?? 0) !== before) {
+            mockPublishEvent("customers", "customer-note-deleted", {
+                customer,
+                note: removed
+            });
+            return Promise.resolve({ success: true, noteId, timestamp });
+        }
+    }
+    return Promise.resolve({ success: false, noteId, timestamp });
 };