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

package/dist/actions/get-smart-grid-layout/types.d.ts

@@ -1,11 +1,9 @@
-import type { CFSmartGridLayout } from "../../CommonTypes";
-/** Fetch a builder SmartGrid layout by `gridId`. */
+import { CFSmartGridLayout } from "../../CommonTypes";
 export interface GetSmartGridLayoutParams {
     gridId: string;
 }
 export interface GetSmartGridLayoutResponse {
     success: boolean;
-    /** The stored layout, or `null` when no layout exists for the grid. */
     layout: CFSmartGridLayout | null;
     timestamp: string;
 }

package/dist/actions/initiate-refund/types.d.ts

@@ -1,3 +1,4 @@
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface InitiateRefundParams {
     /** The ID of the order to refund. If not provided, uses the currently active order. */
     orderId?: string;
@@ -6,5 +7,7 @@ export interface InitiateRefundResponse {
     success: boolean;
     orderId: string;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type InitiateRefund = (params?: InitiateRefundParams) => Promise<InitiateRefundResponse>;

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

@@ -1,16 +1,56 @@
 import type { ExtensionPaymentResponse } from "../extension-payment/types";
-/** Integration (e.g. Stripe-style terminal) payment — always uses paymentType `"integration"` on the wire. */
+/**
+ * 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;
-    processor?: string;
+    amount: number;
+    emvData: IntegrationEmvData;
+    /** Human-readable label (e.g. "Visa ****4242"); shown in the transaction list. */
     label?: string;
-    referenceId?: 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>;
-    /** EMV tag string from the integration terminal; forwarded to the order PaymentMethod's `emv`. */
-    emvData?: string;
-    /** Processor fee for the integration payment; forwarded to the order PaymentMethod's `processorFee`. */
+    /** Provider fee in minor units — stored on paymentMethod.processorFee. */
     processorFee?: number;
 }
 export type IntegrationPaymentResponse = ExtensionPaymentResponse;
-export type IntegrationPayment = (params?: IntegrationPaymentParams) => Promise<IntegrationPaymentResponse>;
+export type IntegrationPayment = (params: IntegrationPaymentParams) => Promise<IntegrationPaymentResponse>;

package/dist/actions/open-extension-overlay/mock.js

@@ -1 +1 @@
-export const mockOpenExtensionOverlay = () => Promise.resolve(true);
+export const mockOpenExtensionOverlay = async (_params) => true;

package/dist/actions/open-extension-overlay/types.d.ts

@@ -1,7 +1,7 @@
 import type { InterceptorPoint, InterceptorReturn } from "../../interceptors/types";
 export interface OpenExtensionOverlayParams {
     point: InterceptorPoint;
-    payload?: unknown;
+    payload?: any;
     /** Owning extension id. Injected by the host for interceptor-originated calls; optional for direct calls. */
     extensionId?: string;
 }

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

@@ -1,4 +1,4 @@
-import { MOCK_PARKED_ORDERS, createOrderFromCart, MOCK_ORDERS } from "../../demo/database";
+import { MOCK_PARKED_ORDERS, createOrderFromCart, MOCK_ORDERS, mockPublishEvent } from "../../demo/database";
 export const mockParkOrder = async () => {
     console.log("[Mock] parkOrder called");
     // Create a temporary order to capture cart state
@@ -13,6 +13,9 @@ export const mockParkOrder = async () => {
         MOCK_ORDERS.splice(foundIndex, 1);
     }
     MOCK_PARKED_ORDERS.push(tempOrder);
+    // Refresh order lists so the new parked order appears (createOrderFromCart
+    // already published the cart-created event that clears the cart).
+    mockPublishEvent("orders", "order-parked", { order: tempOrder });
     return {
         success: true,
         order: tempOrder,

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

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

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

@@ -1,17 +1,35 @@
-import { MOCK_ORDERS } from "../../demo/database";
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
 export const mockPartialPayment = async (params) => {
     console.log("[Mock] partialPayment called", params);
     const openUI = params?.openUI ?? true;
     if (openUI) {
-        // Simulate UI opening
+        // Split-payment UI is host-owned; nothing to simulate here.
         window.alert("Demo: Split Payment UI would open here.");
+        return {
+            success: true,
+            amount: params?.amount,
+            isPercent: params?.isPercent || false,
+            openUI,
+            order: null,
+            timestamp: new Date().toISOString()
+        };
     }
+    // Queue a partial amount as the next tender. The remaining balance is left
+    // untouched until the payment is actually taken (see applyMockPayment).
+    const remaining = MOCK_CART.remainingBalance ?? MOCK_CART.total;
+    const raw = params?.amount ?? 0;
+    // Mirror render: fixed amount is raw dollars (render does toMinorUnits), so
+    // convert to minor units here; percent is a percentage of the remaining total.
+    const minorFactor = 10 ** (MOCK_CART.minorUnits ?? 2);
+    const charge = params?.isPercent ? Math.round((remaining * raw) / 100) : Math.round(raw * minorFactor);
+    MOCK_CART.amountToBeCharged = Math.min(Math.max(0, charge), remaining);
+    mockPublishEvent("cart", "partial-payment-set", { amountToBeCharged: MOCK_CART.amountToBeCharged });
     return {
         success: true,
         amount: params?.amount,
         isPercent: params?.isPercent || false,
         openUI,
-        order: openUI ? null : MOCK_ORDERS[0],
+        order: null,
         timestamp: new Date().toISOString()
     };
 };

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

@@ -1,4 +1,5 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface PartialPaymentParams {
     /** The payment amount (required if openUI is false). */
     amount?: number;
@@ -6,6 +7,8 @@ export interface PartialPaymentParams {
     isPercent?: boolean;
     /** If true, opens the split payment UI. */
     openUI?: boolean;
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: string;
 }
 export interface PartialPaymentResponse {
     success: boolean;
@@ -14,5 +17,7 @@ export interface PartialPaymentResponse {
     openUI: boolean;
     order: CFOrder | null;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type PartialPayment = (params?: PartialPaymentParams) => Promise<PartialPaymentResponse>;

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

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

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

@@ -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-custom-sale/mock.d.ts

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

package/dist/actions/remove-custom-sale/mock.js

@@ -0,0 +1,29 @@
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
+export const mockRemoveCustomSale = (params) => {
+    console.log("[Mock] removeCustomSale called", params);
+    if (!params?.id) {
+        throw new Error("id is required");
+    }
+    const { id } = params;
+    const sales = MOCK_CART.customSales ?? [];
+    const index = sales.findIndex(s => s.id === id);
+    if (index === -1) {
+        throw new Error(`Custom sale with id ${id} not found`);
+    }
+    const sale = sales[index];
+    // Remove from cart
+    sales.splice(index, 1);
+    // Recalculate totals
+    const lineTotal = sale.price * sale.quantity;
+    MOCK_CART.subtotal -= lineTotal;
+    MOCK_CART.total -= lineTotal;
+    MOCK_CART.amountToBeCharged = MOCK_CART.total;
+    MOCK_CART.remainingBalance = MOCK_CART.total;
+    // Publish custom-sale-removed event so cart subscribers refresh
+    mockPublishEvent("cart", "custom-sale-removed", { customSale: sale, id });
+    return Promise.resolve({
+        success: true,
+        id,
+        timestamp: new Date().toISOString()
+    });
+};

package/dist/actions/remove-customer-from-cart/mock.js

@@ -1,8 +1,10 @@
-import { MOCK_CART } from "../../demo/database";
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
 export const mockRemoveCustomerFromCart = async () => {
     console.log("[Mock] removeCustomerFromCart called");
     // Actually remove the customer from the mock cart
     MOCK_CART.customer = null;
+    // Publish customer-removed event so cart subscribers refresh
+    mockPublishEvent('cart', 'customer-removed', {});
     return {
         success: true,
         timestamp: new Date().toISOString()

package/dist/actions/remove-order-note/mock.d.ts

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

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

@@ -0,0 +1,12 @@
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
+export const mockRemoveOrderNote = () => {
+    console.log("[Mock] removeOrderNote called");
+    // Clear the active cart's note.
+    MOCK_CART.orderNotes = undefined;
+    // Publish order-note-removed event so cart subscribers refresh.
+    mockPublishEvent("cart", "order-note-removed", {});
+    return Promise.resolve({
+        success: true,
+        timestamp: new Date().toISOString()
+    });
+};

package/dist/actions/remove-product-discount/mock.d.ts

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

package/dist/actions/remove-product-discount/mock.js

@@ -0,0 +1,17 @@
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
+export const mockRemoveProductDiscount = (params) => {
+    console.log("[Mock] removeProductDiscount called", params);
+    const item = params?.internalId
+        ? MOCK_CART.products.find(p => p.internalId === params.internalId)
+        : MOCK_CART.products[MOCK_CART.products.length - 1];
+    if (item) {
+        item.discounts = [];
+        // Publish so cart subscribers refresh.
+        mockPublishEvent("cart", "product-discount-removed", { internalId: params?.internalId });
+    }
+    return Promise.resolve({
+        success: true,
+        internalId: params?.internalId,
+        timestamp: new Date().toISOString()
+    });
+};

package/dist/actions/remove-product-fee/mock.d.ts

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

package/dist/actions/remove-product-fee/mock.js

@@ -0,0 +1,17 @@
+import { MOCK_CART, mockPublishEvent } from "../../demo/database";
+export const mockRemoveProductFee = (params) => {
+    console.log("[Mock] removeProductFee called", params);
+    const item = params?.internalId
+        ? MOCK_CART.products.find(p => p.internalId === params.internalId)
+        : MOCK_CART.products[MOCK_CART.products.length - 1];
+    if (item) {
+        item.fees = [];
+        // Publish so cart subscribers refresh.
+        mockPublishEvent("cart", "product-fee-removed", { internalId: params?.internalId });
+    }
+    return Promise.resolve({
+        success: true,
+        internalId: params?.internalId,
+        timestamp: new Date().toISOString()
+    });
+};

package/dist/actions/remove-product-from-cart/mock.js

@@ -1,8 +1,8 @@
 import { MOCK_CART, mockPublishEvent } from "../../demo/database";
-export const mockRemoveProductFromCart = async (params) => {
+export const mockRemoveProductFromCart = (params) => {
     console.log("[Mock] removeProductFromCart called", params);
     if (!params?.internalId) {
-        throw new Error('internalId is required');
+        throw new Error("internalId is required");
     }
     const { internalId } = params;
     // Find the product in the cart
@@ -20,13 +20,13 @@ export const mockRemoveProductFromCart = async (params) => {
     MOCK_CART.amountToBeCharged = MOCK_CART.total;
     MOCK_CART.remainingBalance = MOCK_CART.total;
     // Publish product-deleted event
-    mockPublishEvent('cart', 'product-deleted', {
+    mockPublishEvent("cart", "product-deleted", {
         product: product,
         internalId: internalId
     });
-    return {
+    return Promise.resolve({
         success: true,
         internalId: internalId,
         timestamp: new Date().toISOString()
-    };
+    });
 };

package/dist/actions/resolve-extension-overlay/mock.js

@@ -1 +1 @@
-export const mockResolveExtensionOverlay = () => Promise.resolve({ success: true });
+export const mockResolveExtensionOverlay = async (_params) => ({ success: true });

package/dist/actions/resume-parked-order/mock.js

@@ -1,4 +1,4 @@
-import { MOCK_PARKED_ORDERS, MOCK_CART, resetMockCart } from "../../demo/database";
+import { MOCK_PARKED_ORDERS, MOCK_CART, resetMockCart, mockPublishEvent } from "../../demo/database";
 export const mockResumeParkedOrder = async (params) => {
     console.log("[Mock] resumeParkedOrder called", params);
     const orderId = params?.orderId;
@@ -45,6 +45,9 @@ export const mockResumeParkedOrder = async (params) => {
     MOCK_CART.remainingBalance = MOCK_CART.total;
     // Remove from parked
     MOCK_PARKED_ORDERS.splice(index, 1);
+    // Refresh the restored cart and the order lists.
+    mockPublishEvent("cart", "parked-order-resumed", { orderId });
+    mockPublishEvent("orders", "parked-order-resumed", { orderId });
     return {
         success: true,
         order: orderToResume,

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

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

package/dist/actions/save-smart-grid-layout/mock.d.ts

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

package/dist/actions/save-smart-grid-layout/mock.js

@@ -1,4 +1,7 @@
+import { MOCK_SMART_GRID_LAYOUTS } from "../../demo/database";
 export const mockSaveSmartGridLayout = (params) => {
+    console.log("[Mock] saveSmartGridLayout called", params);
+    MOCK_SMART_GRID_LAYOUTS[params.layout.gridId] = params.layout;
     return Promise.resolve({
         success: true,
         gridId: params.layout.gridId,

package/dist/actions/save-smart-grid-layout/types.d.ts

@@ -1,11 +1,9 @@
-import type { CFSmartGridLayout } from "../../CommonTypes";
-/** Persist a builder SmartGrid layout. The `layout.gridId` identifies the grid. */
+import { CFSmartGridLayout } from "../../CommonTypes";
 export interface SaveSmartGridLayoutParams {
     layout: CFSmartGridLayout;
 }
 export interface SaveSmartGridLayoutResponse {
     success: boolean;
-    /** The gridId that was saved. */
     gridId: string;
     timestamp: string;
 }

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

@@ -1,13 +1,15 @@
-import { MOCK_ORDERS } from "../../demo/database";
+import { applyMockPayment, MOCK_CART } from "../../demo/database";
 export const mockTapToPayPayment = async (params) => {
     console.log("[Mock] tapToPayPayment called", params);
     // Simulate Tap to Pay interaction
     window.alert("Demo: Processing Tap to Pay...\n(Please tap card or device on screen)");
+    const due = params?.amount ?? MOCK_CART.amountToBeCharged ?? MOCK_CART.total;
+    const order = applyMockPayment(due, "card", "tapToPay");
     return {
         success: true,
-        amount: params?.amount || null,
+        amount: due,
         paymentType: "tapToPay",
-        order: MOCK_ORDERS[0],
+        order,
         timestamp: new Date().toISOString()
     };
 };

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

@@ -1,7 +1,10 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface TapToPayPaymentParams {
     /** If not provided, uses the cart total. */
     amount?: number;
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: string;
 }
 export interface TapToPayPaymentResponse {
     success: boolean;
@@ -9,5 +12,7 @@ export interface TapToPayPaymentResponse {
     paymentType: string;
     order: CFOrder | null;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type TapToPayPayment = (params?: TapToPayPaymentParams) => Promise<TapToPayPaymentResponse>;

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

@@ -1,15 +1,14 @@
-import { createOrderFromCart, MOCK_CART } from "../../demo/database";
+import { applyMockPayment, MOCK_CART } from "../../demo/database";
 export const mockTerminalPayment = async (params) => {
     console.log("[Mock] terminalPayment called", params);
     const connectionType = params?.paymentType || "Cloud";
     // Simulate terminal interaction
     window.alert(`Demo: Processing ${connectionType} Terminal Payment...\n(Please tap, insert, or swipe card on terminal)`);
-    const amount = params?.amount || MOCK_CART.total;
-    // Mocking terminal payment success immediately
-    const order = createOrderFromCart("card", amount, "stripe_terminal");
+    const due = params?.amount ?? MOCK_CART.amountToBeCharged ?? MOCK_CART.total;
+    const order = applyMockPayment(due, "card", "stripe_terminal");
     return {
         success: true,
-        amount: amount,
+        amount: due,
         paymentType: "terminal",
         order,
         timestamp: new Date().toISOString()

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

@@ -1,9 +1,12 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface TerminalPaymentParams {
     /** If not provided, uses the cart total. */
     amount?: number;
     /** "Bluetooth" or "Cloud". Defaults to "Cloud". */
     paymentType?: 'Bluetooth' | 'Cloud';
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: string;
 }
 export interface TerminalPaymentResponse {
     success: boolean;
@@ -11,5 +14,7 @@ export interface TerminalPaymentResponse {
     paymentType: string;
     order: CFOrder | null;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type TerminalPayment = (params?: TerminalPaymentParams) => Promise<TerminalPaymentResponse>;

package/dist/actions/update-cart-item-quantity/mock.js

@@ -1,11 +1,11 @@
 import { MOCK_CART, mockPublishEvent } from "../../demo/database";
-export const mockUpdateCartItemQuantity = async (params) => {
+export const mockUpdateCartItemQuantity = (params) => {
     console.log("[Mock] updateCartItemQuantity called", params);
     if (!params?.internalId) {
-        throw new Error('internalId is required');
+        throw new Error("internalId is required");
     }
     if (params.quantity === undefined || params.quantity === null) {
-        throw new Error('quantity is required');
+        throw new Error("quantity is required");
     }
     const { internalId, quantity } = params;
     // Find the product in the cart
@@ -25,16 +25,16 @@ export const mockUpdateCartItemQuantity = async (params) => {
         MOCK_CART.amountToBeCharged = MOCK_CART.total;
         MOCK_CART.remainingBalance = MOCK_CART.total;
         // Publish product-deleted event
-        mockPublishEvent('cart', 'product-deleted', {
+        mockPublishEvent("cart", "product-deleted", {
             product: product,
             internalId: internalId
         });
-        return {
+        return Promise.resolve({
             success: true,
             internalId: internalId,
             quantity: 0,
             timestamp: new Date().toISOString()
-        };
+        });
     }
     // Update quantity
     const quantityDelta = quantity - previousQuantity;
@@ -46,15 +46,15 @@ export const mockUpdateCartItemQuantity = async (params) => {
     MOCK_CART.amountToBeCharged = MOCK_CART.total;
     MOCK_CART.remainingBalance = MOCK_CART.total;
     // Publish product-updated event
-    mockPublishEvent('cart', 'product-updated', {
+    mockPublishEvent("cart", "product-updated", {
         product: product,
         previousQuantity: previousQuantity,
         newQuantity: quantity
     });
-    return {
+    return Promise.resolve({
         success: true,
         internalId: internalId,
         quantity: quantity,
         timestamp: new Date().toISOString()
-    };
+    });
 };

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

@@ -1,7 +1,10 @@
 import { CFOrder } from "../../CommonTypes";
+import type { CFTransitionResult } from "../../common-types/order-state";
 export interface VendaraPaymentParams {
     /** If not provided, uses the cart total. */
     amount?: number;
+    /** Override the fulfillment state after full payment. Render resolves the cascade. */
+    checkoutFulfillmentTarget?: string;
 }
 export interface VendaraPaymentResponse {
     success: boolean;
@@ -9,5 +12,7 @@ export interface VendaraPaymentResponse {
     paymentType: string;
     order: CFOrder | null;
     timestamp: string;
+    /** Present when the state machine blocked or forced the transition. */
+    transitionResult?: CFTransitionResult;
 }
 export type VendaraPayment = (params?: VendaraPaymentParams) => Promise<VendaraPaymentResponse>;

package/dist/common-types/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./custom-tables";
 export * from "./custom-extensions";
+export * from "./order-state";

package/dist/common-types/index.js

@@ -1,2 +1,3 @@
 export * from "./custom-tables";
 export * from "./custom-extensions";
+export * from "./order-state";

package/dist/common-types/order-state.d.ts

@@ -0,0 +1,32 @@
+/**
+ * State machine protocol types for the command-frame boundary.
+ * These mirror @final-commerce/common shapes but carry no logic.
+ * command-frame must NOT depend on common.
+ */
+export interface CFStatePair {
+    payment: string;
+    fulfillment: string;
+}
+export type CFBlockedBy = "financial_invariant" | "cross_axis_rule" | "path" | "condition";
+export interface CFTransitionResult {
+    allowed: boolean;
+    blockedBy?: CFBlockedBy;
+    guard?: string;
+    reason?: string;
+    failedConditions?: CFFailedCondition[];
+}
+export interface CFFailedCondition {
+    field: string;
+    operator: string;
+    value: unknown;
+    reason?: string;
+}
+export interface CFConditionStatus {
+    met: boolean;
+    description: string;
+}
+export interface CFAvailableTransition {
+    to: CFStatePair;
+    displayLabel: string;
+    conditions: CFConditionStatus[];
+}