@final-commerce/command-frame 0.3.2-beta.1 → 0.3.2-preprod.1

package/README.md

@@ -96,7 +96,7 @@ const context = await client.getContext();
 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.
 
 - **[Pub/Sub Documentation](./src/pubsub/README.md)**
-- **Topics:** Cart (16), Customers (8), Orders (4), 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 (5), Payments (2), Products (4), Refunds (4), Print (3), Custom Tables (3), Outlet (2), Station (2), Session (2), Users (2).
 
 ```typescript
 import { topics } from "@final-commerce/command-frame";

package/dist/actions/void-order/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Void order action
+ * Calls the voidOrder action on the parent window
+ */
+import type { VoidOrder } from './types';
+export declare const voidOrder: VoidOrder;

package/dist/actions/void-order/action.js

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

package/dist/actions/void-order/mock.d.ts

@@ -0,0 +1,2 @@
+import { VoidOrder } from './types';
+export declare const mockVoidOrder: VoidOrder;

package/dist/actions/void-order/mock.js

@@ -0,0 +1,23 @@
+import { MOCK_ORDERS, mockPublishEvent } from '../../demo/database';
+// Payment states in which an order is still open — mirrors the runtime gate
+// (kaching's OPEN_PAYMENT_STATES / handler.ts). Anything outside this set
+// (paid, partially_refunded, refunded, voided, or unknown) is ORDER_NOT_VOIDABLE.
+const OPEN_PAYMENT_STATES = ['unpaid', 'payment_pending', 'partially_paid'];
+export const mockVoidOrder = async (params) => {
+    console.log('[Mock] voidOrder called', params);
+    const order = params?.orderId ? MOCK_ORDERS.find((o) => o._id === params.orderId) : MOCK_ORDERS[0];
+    if (!order) {
+        throw new Error(`Order with ID ${params?.orderId} not found`);
+    }
+    const orderId = order._id;
+    // Only OPEN orders are voidable — mirror the runtime gate.
+    if (!OPEN_PAYMENT_STATES.includes(order.paymentState)) {
+        throw new Error(`ORDER_NOT_VOIDABLE: order ${orderId} is '${order.paymentState}' — use the refund flow for completed orders`);
+    }
+    const hasCapturedLegs = (order.paymentMethods?.length ?? 0) > 0;
+    const outcome = hasCapturedLegs ? 'refunded' : 'voided';
+    order.paymentState = outcome;
+    order.fulfillmentState = 'cancelled';
+    mockPublishEvent('orders', 'order-voided', { orderId, outcome, reason: params?.reason });
+    return { success: true, orderId, outcome, timestamp: new Date().toISOString() };
+};

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

@@ -0,0 +1,27 @@
+import type { CFTransitionResult } from '../../common-types/order-state';
+export type VoidOrderOutcome = 'voided' | 'refunded';
+export interface VoidOrderParams {
+    /** Order to void; defaults to the active order. */
+    orderId?: string;
+    /**
+     * Optional cashier-facing reason. On a pure void, recorded on the void audit
+     * row and carried on the `order-voided` event. On the refund branch it rides
+     * the event only — the refund dispatcher does not consume it.
+     */
+    reason?: string;
+}
+export interface VoidOrderResponse {
+    success: boolean;
+    orderId: string;
+    /**
+     * `voided`   — nothing was captured; pure state transition to voided × cancelled.
+     * `refunded` — captured split legs were refunded to their original tenders;
+     *              order lands refunded × cancelled (financially equivalent to a
+     *              void, but the capture + payout stay on the audit trail).
+     */
+    outcome: VoidOrderOutcome;
+    timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
+}
+export type VoidOrder = (params?: VoidOrderParams) => Promise<VoidOrderResponse>;

package/dist/actions/void-order/types.js

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

package/dist/demo/database.d.ts

@@ -51,6 +51,7 @@ export declare const MOCK_PRODUCT_BLACK_GARLIC: import("@final-commerce/common/p
 export declare const MOCK_ORDER_1: CFActiveOrder;
 export declare const MOCK_ORDER_2: CFActiveOrder;
 export declare const MOCK_ORDER_3: CFActiveOrder;
+export declare const MOCK_ORDER_4: CFActiveOrder;
 export declare const MOCK_PARKED_ORDER_1: CFActiveOrder;
 export declare const MOCK_PARKED_ORDER_2: CFActiveOrder;
 export declare const MOCK_USERS: import("@final-commerce/common/pos-types").ActiveUser[];

package/dist/demo/database.js

@@ -486,6 +486,59 @@ export const MOCK_ORDER_3 = {
     station: MOCK_STATION_1,
     createdAt: new Date(Date.now() - 7200000).toISOString()
 };
+// Open order with one captured deposit leg — voidable via the refund branch
+// (demoes voidOrder's `refunded` outcome). Copied from MOCK_ORDER_1, id/state/
+// paymentMethods changed.
+export const MOCK_ORDER_4 = {
+    _id: "order_1004",
+    currency: CurrencyCode.USD,
+    minorUnits: 2,
+    receiptId: "1001-0004",
+    companyId: MOCK_COMPANY.id,
+    externalId: null,
+    status: "in_progress",
+    paymentState: "partially_paid",
+    fulfillmentState: "pending",
+    displayState: "Partially Paid",
+    customer: MOCK_CUSTOMER_5,
+    summary: {
+        total: 2500,
+        subtotalAfterFees: 2500,
+        discountTotal: 0,
+        shippingTotal: 0,
+        totalTaxes: 0,
+        taxes: [],
+        isTaxInclusive: false
+    },
+    cartDiscount: null,
+    cartFees: [],
+    paymentMethods: [
+        {
+            transactionId: "trans_cash_2",
+            paymentType: "cash",
+            amount: 1000,
+            timestamp: new Date(Date.now() - 600000).toISOString(),
+            processor: "cash"
+        }
+    ],
+    source: "pos",
+    posData: {
+        outlet: MOCK_OUTLET_MAIN.id,
+        station: MOCK_STATION_2._id,
+        employee: MOCK_USER_MARIO.id
+    },
+    sessionId: "sess_4",
+    metadata: [],
+    billing: null,
+    shipping: null,
+    lineItems: [createLineItem(MOCK_PRODUCT_RED_PEPPER, 0, 1)],
+    customSales: [],
+    balance: 1500,
+    user: MOCK_USER_MARIO,
+    outlet: MOCK_OUTLET_MAIN,
+    station: MOCK_STATION_2,
+    createdAt: new Date(Date.now() - 600000).toISOString()
+};
 export const MOCK_PARKED_ORDER_1 = {
     _id: "parked_2001",
     currency: CurrencyCode.USD,
@@ -592,7 +645,7 @@ export const MOCK_PRODUCTS = [
     MOCK_PRODUCT_HABANERO,
     MOCK_PRODUCT_BLACK_GARLIC
 ];
-export const MOCK_ORDERS = [MOCK_ORDER_1, MOCK_ORDER_2, MOCK_ORDER_3];
+export const MOCK_ORDERS = [MOCK_ORDER_1, MOCK_ORDER_2, MOCK_ORDER_3, MOCK_ORDER_4];
 export const MOCK_PARKED_ORDERS = [MOCK_PARKED_ORDER_1, MOCK_PARKED_ORDER_2];
 // Compatibility Exports (reassigned by setMockDatabase)
 export let MOCK_USER = MOCK_USERS[0];

package/dist/index.d.ts

@@ -33,6 +33,7 @@ export declare const command: {
     readonly parkOrder: import(".").ParkOrder;
     readonly resumeParkedOrder: import(".").ResumeParkedOrder;
     readonly deleteParkedOrder: import(".").DeleteParkedOrder;
+    readonly voidOrder: import(".").VoidOrder;
     readonly cashPayment: import(".").CashPayment;
     readonly getCashRoundingAmount: import(".").GetCashRoundingAmount;
     readonly tapToPayPayment: import(".").TapToPayPayment;
@@ -161,6 +162,7 @@ export type { ClearCart, ClearCartResponse } from './actions/clear-cart/types';
 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 { VoidOrder, VoidOrderParams, VoidOrderResponse, VoidOrderOutcome } from './actions/void-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';
@@ -240,7 +242,7 @@ export { transactionsTopic } from './pubsub/topics/transactions';
 export { categoriesTopic } from './pubsub/topics/categories';
 export { attributesTopic } from './pubsub/topics/attributes';
 export type { CustomerCreatedPayload, CustomerUpdatedPayload, CustomerNoteAddedPayload, CustomerNoteDeletedPayload, CustomerAssignedPayload, CustomerUnassignedPayload, CustomerActiveSetPayload, CustomerActiveGetPayload, CustomerCreatedEvent, CustomerUpdatedEvent, CustomerNoteAddedEvent, CustomerNoteDeletedEvent, CustomerAssignedEvent, CustomerUnassignedEvent, CustomerActiveSetEvent, CustomerActiveGetEvent, CustomersEventType, CustomersEventPayload, } from './pubsub/topics/customers/types';
-export type { OrderCreatedPayload, OrderUpdatedPayload, OrderActiveSetPayload, OrderActiveGetPayload, OrderCreatedEvent, OrderUpdatedEvent, OrderActiveSetEvent, OrderActiveGetEvent, OrderStateTransitionCompletedPayload, OrderStateTransitionBlockedPayload, OrderStateTransitionCompletedEvent, OrderStateTransitionBlockedEvent, OrdersEventType, OrdersEventPayload, } from './pubsub/topics/orders/types';
+export type { OrderCreatedPayload, OrderUpdatedPayload, OrderVoidedPayload, OrderActiveSetPayload, OrderActiveGetPayload, OrderCreatedEvent, OrderUpdatedEvent, OrderVoidedEvent, OrderActiveSetEvent, OrderActiveGetEvent, OrderStateTransitionCompletedPayload, OrderStateTransitionBlockedPayload, OrderStateTransitionCompletedEvent, OrderStateTransitionBlockedEvent, OrdersEventType, OrdersEventPayload, } from './pubsub/topics/orders/types';
 export type { RefundCreatedPayload, RefundUpdatedPayload, RefundActiveSetPayload, RefundActiveGetPayload, RefundCreatedEvent, RefundUpdatedEvent, RefundActiveSetEvent, RefundActiveGetEvent, RefundsEventType, RefundsEventPayload, } from './pubsub/topics/refunds/types';
 export type { ProductCreatedPayload, ProductUpdatedPayload, ProductSetActivePayload, ProductGetActivePayload, ProductCreatedEvent, ProductUpdatedEvent, ProductSetActiveEvent, ProductGetActiveEvent, ProductsEventType, ProductsEventPayload, } from './pubsub/topics/products/types';
 export type { OutletActiveSetPayload, OutletActiveGetPayload, OutletActiveSetEvent, OutletActiveGetEvent, OutletEventType, OutletEventPayload, } from './pubsub/topics/outlet/types';

package/dist/index.js

@@ -33,6 +33,7 @@ import { clearCart } from './actions/clear-cart/action';
 import { parkOrder } from './actions/park-order/action';
 import { resumeParkedOrder } from './actions/resume-parked-order/action';
 import { deleteParkedOrder } from './actions/delete-parked-order/action';
+import { voidOrder } from './actions/void-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';
@@ -163,6 +164,7 @@ export const command = {
     parkOrder,
     resumeParkedOrder,
     deleteParkedOrder,
+    voidOrder,
     cashPayment,
     getCashRoundingAmount,
     tapToPayPayment,

package/dist/projects/render/mocks.js

@@ -31,6 +31,7 @@ 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 { mockVoidOrder } from '../../actions/void-order/mock';
 import { mockExampleFunction } from '../../actions/example-function/mock';
 import { mockGetCategories } from '../../actions/get-categories/mock';
 import { mockGetContext } from '../../actions/get-context/mock';
@@ -123,6 +124,7 @@ export const RENDER_MOCKS = {
     getCashRoundingAmount: mockGetCashRoundingAmount,
     clearCart: mockClearCart,
     deleteParkedOrder: mockDeleteParkedOrder,
+    voidOrder: mockVoidOrder,
     exampleFunction: mockExampleFunction,
     getCategories: mockGetCategories,
     getContext: mockGetContext,

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

@@ -1,4 +1,4 @@
-import type { ExampleFunction, GetProducts, AddCustomSale, EditCustomSale, 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 { ExampleFunction, GetProducts, AddCustomSale, EditCustomSale, 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, VoidOrder, 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 {
@@ -34,6 +34,7 @@ export interface RenderProviderActions {
     parkOrder: ParkOrder;
     resumeParkedOrder: ResumeParkedOrder;
     deleteParkedOrder: DeleteParkedOrder;
+    voidOrder: VoidOrder;
     initiateRefund: InitiateRefund;
     openExtensionOverlay: OpenExtensionOverlay;
     resolveExtensionOverlay: ResolveExtensionOverlay;

package/dist/pubsub/topics/orders/index.js

@@ -36,6 +36,11 @@ export const ordersTopic = {
             id: "state-transition-blocked",
             name: "State Transition Blocked",
             description: "Published when an order state transition is blocked by the state machine"
+        },
+        {
+            id: "order-voided",
+            name: "Order Voided",
+            description: "Published when an open order is voided (pure void, or captured legs refunded)"
         }
     ]
 };

package/dist/pubsub/topics/orders/order-voided/types.d.ts

@@ -0,0 +1,14 @@
+import type { TopicEvent } from '../../../types';
+/**
+ * Order Voided Event Types
+ */
+export interface OrderVoidedPayload {
+    orderId: string;
+    /** 'voided' = nothing captured; 'refunded' = captured legs were refunded. */
+    outcome: 'voided' | 'refunded';
+    reason?: string;
+}
+/**
+ * Typed event for order-voided
+ */
+export type OrderVoidedEvent = TopicEvent<OrderVoidedPayload>;

package/dist/pubsub/topics/orders/order-voided/types.js

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

package/dist/pubsub/topics/orders/types.d.ts

@@ -4,15 +4,17 @@
  */
 export * from "./order-created/types";
 export * from "./order-updated/types";
+export * from "./order-voided/types";
 export * from "./set-active-order/types";
 export * from "./get-active-order/types";
 export * from "./state-transition-completed/types";
 export * from "./state-transition-blocked/types";
 import type { OrderCreatedPayload } from "./order-created/types";
 import type { OrderUpdatedPayload } from "./order-updated/types";
+import type { OrderVoidedPayload } from "./order-voided/types";
 import type { OrderActiveSetPayload } from "./set-active-order/types";
 import type { OrderActiveGetPayload } from "./get-active-order/types";
 import type { OrderStateTransitionCompletedPayload } from "./state-transition-completed/types";
 import type { OrderStateTransitionBlockedPayload } from "./state-transition-blocked/types";
-export type OrdersEventPayload = OrderCreatedPayload | OrderUpdatedPayload | OrderActiveSetPayload | OrderActiveGetPayload | OrderStateTransitionCompletedPayload | OrderStateTransitionBlockedPayload;
-export type OrdersEventType = "order-created" | "order-updated" | "set-active-order" | "get-active-order" | "state-transition-completed" | "state-transition-blocked";
+export type OrdersEventPayload = OrderCreatedPayload | OrderUpdatedPayload | OrderVoidedPayload | OrderActiveSetPayload | OrderActiveGetPayload | OrderStateTransitionCompletedPayload | OrderStateTransitionBlockedPayload;
+export type OrdersEventType = "order-created" | "order-updated" | "order-voided" | "set-active-order" | "get-active-order" | "state-transition-completed" | "state-transition-blocked";

package/dist/pubsub/topics/orders/types.js

@@ -5,6 +5,7 @@
 // Re-export all event types
 export * from "./order-created/types";
 export * from "./order-updated/types";
+export * from "./order-voided/types";
 export * from "./set-active-order/types";
 export * from "./get-active-order/types";
 export * from "./state-transition-completed/types";

package/package.json

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