@final-commerce/command-frame 0.8.0-online.1 → 0.8.0-online.3

package/dist/CommonTypes.d.ts

@@ -1,5 +1,5 @@
 export * from './common-types';
-import type { Tax, Tip, Address, MetadataItem, PosDataItem, CartFeeTaxEntry, CartFeeItem, CartDiscountItem, OrderNote, NonRevenueItem, DiscountDetail, FeeDetail, DiscountLineItem, FeeLineItem, LineItem, TipPayment, RefundedTipPayment, PaymentMethod, Discount, CustomFee, Summary, CustomSale, RefundedCustomSale, RefundItem, RefundedLineItem, ActiveStation, ActiveSession, ActiveOutlet, ActiveUser, ActiveUserRole, ActiveOrder, ActiveCart, ActivePark, ActiveCompany, ActiveCustomSales, ActiveProduct, ActiveCustomer, FullProduct, ProductVariant, Inventory, CustomerNote, Attribute, AttributeOption, Category, Transaction, ActiveSplitPayment } from '@final-commerce/common/pos-types';
+import type { Tax, Tip, Address, MetadataItem, PosDataItem, CartFeeTaxEntry, CartFeeItem, CartDiscountItem, OrderNote, NonRevenueItem, DiscountDetail, FeeDetail, DiscountLineItem, FeeLineItem, LineItem, TipPayment, RefundedTipPayment, PaymentMethod, Discount, CustomFee, Summary, CustomSale, RefundedCustomSale, RefundItem, RefundedLineItem, ActiveStation, ActiveSession, ActiveOutlet, ActiveUser, ActiveUserRole, ActiveOrder, ActiveCart, ActivePark, ActiveCompany, ActiveCustomSales, ActiveProduct, ActiveCustomer, FullProduct, ProductVariant, Inventory, ResolvedModifier, ResolvedModifierChoice, ModifierSelectionType, ModifierSelection, ModifierChoiceSelection, CartLineModifier, ProdModifierBreakdown, OrderLineItemModifier, CustomerNote, Attribute, AttributeOption, Category, Transaction, ActiveSplitPayment } from '@final-commerce/common/pos-types';
 export { CurrencyCode, ProductType as CFProductType, UserTypes as CFUserTypes } from '@final-commerce/common';
 /** Open record used as a base for active entities. */
 export type CFActiveEntity = Record<string, unknown>;
@@ -18,6 +18,19 @@ export type CFTransaction = Transaction;
 export type CFCategory = Category;
 export type CFProductVariant = ProductVariant;
 export type CFProduct = FullProduct;
+/** Modifier (the till question) resolved onto a product — `CFProduct.modifiers`. */
+export type CFResolvedModifier = ResolvedModifier;
+export type CFResolvedModifierChoice = ResolvedModifierChoice;
+export type CFModifierSelectionType = ModifierSelectionType;
+/** One selected modifier choice on an order line item (wire shape). */
+export type CFOrderLineItemModifier = OrderLineItemModifier;
+/** Cart-line modifier answer (pre-pricing) — `CFActiveProduct.modifierSelections`. */
+export type CFModifierSelection = ModifierSelection;
+export type CFModifierChoiceSelection = ModifierChoiceSelection;
+/** One selected choice PRICED onto a cart line — `CFActiveProduct.modifiers` (not the resolved stack). */
+export type CFCartLineModifier = CartLineModifier;
+/** A priced, line-extended modifier row: "Toppings - Avocado" x2, `amount` 1000. */
+export type CFProdModifierBreakdown = ProdModifierBreakdown;
 export type CFActiveProduct = ActiveProduct;
 export type CFCustomer = ActiveCustomer;
 export type CFActiveCustomer = ActiveCustomer;

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

@@ -1,4 +1,4 @@
-import { MOCK_CART, MOCK_PRODUCTS, mockPublishEvent } from '../../demo/database';
+import { MOCK_CART, MOCK_PRODUCTS, buildCartLineModifiers, buildModifierRows, mockPublishEvent, } from '../../demo/database';
 import { extendPrice, isValidQuantity, resolveUnit } from '@final-commerce/common';
 export const mockAddProductToCart = async (params) => {
     console.log('[Mock] addProductToCart called', params);
@@ -53,6 +53,18 @@ export const mockAddProductToCart = async (params) => {
         note: note,
         // discount/fee could be added here to mock object if CFActiveProduct supports it
     };
+    // The spread above copied the PRODUCT's `modifiers` — a ResolvedModifier[] menu — into a
+    // field that means "the choices this line carries" (CartLineModifier[]). Two different
+    // shapes, one name. Drop it before anything reads the line, or every surface renders the
+    // whole catalogue as if the cashier had picked all of it.
+    delete activeProduct.modifiers;
+    // Keep the raw answers AND the priced rows, the same pair the real host writes. The cart
+    // TOTAL is deliberately left alone: like a product fee (see add-product-fee), per-line
+    // money is not accumulated by this mock — `total` stays Σ extendPrice(price, quantity).
+    if (params?.modifiers?.length) {
+        activeProduct.modifierSelections = params.modifiers;
+        activeProduct.modifiers = buildCartLineModifiers(product.modifiers, params.modifiers, product.taxTable);
+    }
     MOCK_CART.products.push(activeProduct);
     // Recalculate totals. extendPrice, not a raw multiply: a fractional quantity times an
     // integer-minor price leaves fractional cents, which no order may carry.
@@ -64,6 +76,9 @@ export const mockAddProductToCart = async (params) => {
     MOCK_CART.remainingBalance = MOCK_CART.total;
     // Publish cart event to simulate real behavior
     mockPublishEvent('cart', 'product-added', { product: activeProduct });
+    // Display-ready modifier rows for the line that was just created, so a flow can
+    // show what the modifiers added without re-reading the cart or multiplying.
+    const { rows, modifiersTotal } = buildModifierRows(activeProduct.modifiers, quantity);
     return {
         success: true,
         productId: activeProduct.id,
@@ -71,6 +86,8 @@ export const mockAddProductToCart = async (params) => {
         internalId: activeProduct.internalId,
         name: activeProduct.name,
         quantity: quantity,
+        rows,
+        modifiersTotal,
         timestamp: new Date().toISOString(),
     };
 };

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

@@ -1,5 +1,7 @@
 import type { AddProductDiscountParams } from '../add-product-discount/types';
 import type { AddProductFeeParams } from '../add-product-fee/types';
+import type { ModifierSelection } from '../get-product-modifier-selections/types';
+import type { CFProdModifierBreakdown } from '../../CommonTypes';
 export interface AddProductToCartParams {
     /** ID of the variant to add. */
     variantId: string;
@@ -21,17 +23,25 @@ export interface AddProductToCartParams {
     discounts?: AddProductDiscountParams[];
     /** Array of fees to apply immediately. */
     fees?: AddProductFeeParams[];
+    /** Modifier selections to apply immediately. */
+    modifiers?: ModifierSelection[];
     /** Note or array of notes to add immediately. */
     notes?: string | string[];
 }
 export interface AddProductToCartResponse {
     success: boolean;
+    /** Set when the add was rejected (e.g. a required modifier is unanswered). */
+    reason?: string;
     productId: string;
     variantId: string;
     /** The unique identifier for the specific item instance added to the cart. */
     internalId: string;
     name: string;
     quantity: number;
+    /** The modifiers the line was created with, display-ready. Empty when there are none. */
+    rows: CFProdModifierBreakdown[];
+    /** Sum of `rows[].amount` — what the modifiers added to this line, in minor units. */
+    modifiersTotal: number;
     timestamp: string;
 }
 export type AddProductToCart = (params?: AddProductToCartParams) => Promise<AddProductToCartResponse>;

package/dist/actions/get-product-modifier-selections/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Get product modifier selections action (read-only)
+ * Calls the getProductModifierSelections action on the parent window
+ */
+import type { GetProductModifierSelections } from "./types";
+export declare const getProductModifierSelections: GetProductModifierSelections;

package/dist/actions/get-product-modifier-selections/action.js

@@ -0,0 +1,8 @@
+/**
+ * Get product modifier selections action (read-only)
+ * Calls the getProductModifierSelections action on the parent window
+ */
+import { commandFrameClient } from "../../client";
+export const getProductModifierSelections = async (params) => {
+    return await commandFrameClient.call("getProductModifierSelections", params);
+};

package/dist/actions/get-product-modifier-selections/mock.d.ts

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

package/dist/actions/get-product-modifier-selections/mock.js

@@ -0,0 +1,30 @@
+import { MOCK_CART, buildModifierRows } from "../../demo/database";
+export const mockGetProductModifierSelections = async (params) => {
+    console.log("[Mock] getProductModifierSelections called", params);
+    // Read the line's stored selections from the mock cart (last line when no internalId).
+    const line = params?.internalId
+        ? MOCK_CART.products.find((p) => p.internalId === params.internalId)
+        : MOCK_CART.products[MOCK_CART.products.length - 1];
+    if (!line) {
+        return {
+            success: false,
+            reason: "No matching cart line",
+            internalId: params?.internalId,
+            selections: [],
+            rows: [],
+            modifiersTotal: 0,
+            timestamp: new Date().toISOString()
+        };
+    }
+    // The priced rows already sit on the line; extending them by the line quantity is
+    // the host's job, not the flow's.
+    const { rows, modifiersTotal } = buildModifierRows(line.modifiers, line.quantity);
+    return {
+        success: true,
+        internalId: line.internalId,
+        selections: line.modifierSelections ?? [],
+        rows,
+        modifiersTotal,
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/get-product-modifier-selections/types.d.ts

@@ -0,0 +1,23 @@
+import type { CFModifierSelection, CFModifierChoiceSelection, CFProdModifierBreakdown } from "../../CommonTypes";
+/** Alias of common's — `quantity` is units PER LINE-ITEM UNIT. */
+export type ModifierChoiceSelection = CFModifierChoiceSelection;
+/** Alias of common's — the cashier's answer to one modifier. */
+export type ModifierSelection = CFModifierSelection;
+export interface GetProductModifierSelectionsParams {
+    /** The cart line to read. Defaults to the active product's line. */
+    internalId?: string;
+}
+export interface GetProductModifierSelectionsResponse {
+    success: boolean;
+    /** Set when the read failed (e.g. no such line, no active product). */
+    reason?: string;
+    internalId?: string;
+    /** Raw ids — round-trips back into the setter. No names, no money: use `rows` to display. */
+    selections: ModifierSelection[];
+    /** Display-ready: "Toppings - Avocado" x2, `amount` 1000. One row per chosen choice. */
+    rows: CFProdModifierBreakdown[];
+    /** Sum of `rows[].amount` for THIS line, in minor units. */
+    modifiersTotal: number;
+    timestamp: string;
+}
+export type GetProductModifierSelections = (params?: GetProductModifierSelectionsParams) => Promise<GetProductModifierSelectionsResponse>;

package/dist/actions/get-product-modifier-selections/types.js

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

package/dist/actions/resume-checkout/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Resume Checkout action
+ * Calls the resumeCheckout action on the parent window
+ */
+import type { ResumeCheckout } from './types';
+export declare const resumeCheckout: ResumeCheckout;

package/dist/actions/resume-checkout/action.js

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

package/dist/actions/resume-checkout/mock.d.ts

@@ -0,0 +1,16 @@
+import { ResumeCheckout } from './types';
+/**
+ * Standalone mock of the checkout return leg.
+ *
+ * It reads the SAME query parameters the real provider sends a shopper back
+ * with, so a builder can exercise the redirect path in preview by appending
+ * them by hand:
+ *
+ *   ?sessionId=CS_MOCK&redirectResult=MOCK
+ *
+ * Without them it answers `{ resumed: false }` and does nothing, which is what
+ * the real command does on an ordinary page load. That is the branch a
+ * checkout screen hits on every normal visit, so it is the one worth getting
+ * right in a mock.
+ */
+export declare const mockResumeCheckout: ResumeCheckout;

package/dist/actions/resume-checkout/mock.js

@@ -0,0 +1,51 @@
+import { mockPublishEvent } from '../../demo/database';
+/**
+ * Standalone mock of the checkout return leg.
+ *
+ * It reads the SAME query parameters the real provider sends a shopper back
+ * with, so a builder can exercise the redirect path in preview by appending
+ * them by hand:
+ *
+ *   ?sessionId=CS_MOCK&redirectResult=MOCK
+ *
+ * Without them it answers `{ resumed: false }` and does nothing, which is what
+ * the real command does on an ordinary page load. That is the branch a
+ * checkout screen hits on every normal visit, so it is the one worth getting
+ * right in a mock.
+ */
+export const mockResumeCheckout = async (params) => {
+    console.log('[Mock] resumeCheckout called', params);
+    const href = params?.url ?? (typeof window === 'undefined' ? '' : window.location.href);
+    let redirectResult = null;
+    try {
+        redirectResult = new URL(href).searchParams.get('redirectResult');
+    }
+    catch {
+        redirectResult = null;
+    }
+    if (!redirectResult) {
+        return {
+            success: true,
+            timestamp: new Date().toISOString(),
+            checkout: { resumed: false },
+        };
+    }
+    const suffix = String(Date.now()).slice(-6);
+    const checkout = {
+        resumed: true,
+        orderId: `mock-order-${suffix}`,
+        receiptId: `ON-001-${suffix}`,
+        // `Authorised` is what the real provider reports for a completed redirect.
+        // It is NOT settlement — see the checkout topic docs.
+        resultCode: 'Authorised',
+        sessionResult: `mock-session-result-${suffix}`,
+        orderPassword: `mock-pw-${suffix}`,
+    };
+    mockPublishEvent('checkout', 'payment-completed', {
+        orderId: checkout.orderId,
+        receiptId: checkout.receiptId,
+        resultCode: checkout.resultCode,
+        sessionResult: checkout.sessionResult,
+    });
+    return { success: true, timestamp: new Date().toISOString(), checkout };
+};

package/dist/actions/resume-checkout/types.d.ts

@@ -0,0 +1,59 @@
+export interface ResumeCheckoutParams {
+    /**
+     * Where to read the provider's return data from. Defaults to the current
+     * page URL, which is where the shopper has just landed.
+     *
+     * Only override this if you moved the query string somewhere else before
+     * calling — for example if your router strips it on mount.
+     */
+    url?: string;
+}
+/**
+ * What the return leg produced. Every field past `resumed` is absent when
+ * `resumed` is `false`.
+ */
+export interface ResumeCheckoutResult {
+    /**
+     * `false` means THIS WAS AN ORDINARY PAGE LOAD — no provider return data was
+     * in the URL, so there was nothing to finish and nothing happened. It is not
+     * an error, and it is the answer on every normal visit to the page. Call this
+     * unconditionally when your checkout or confirmation screen mounts and branch
+     * on this field.
+     */
+    resumed: boolean;
+    orderId?: string;
+    receiptId?: string;
+    /**
+     * The provider's result code for the completed attempt, e.g. `Authorised` or
+     * `Refused`. As everywhere else in this topic, `Authorised` is an
+     * authorisation and NOT a settlement.
+     */
+    resultCode?: string;
+    /** Opaque proof of the payment — see `PaymentCompletedPayload.sessionResult`. */
+    sessionResult?: string;
+    /**
+     * The one-time order password from the original checkout, recovered from
+     * browser storage. The page that held it in memory is gone, so this is the
+     * only way back to the order's status after a redirect.
+     */
+    orderPassword?: string;
+}
+export interface ResumeCheckoutResponse {
+    success: boolean;
+    timestamp: string;
+    checkout: ResumeCheckoutResult;
+}
+/**
+ * Finish a checkout the shopper was redirected away from.
+ *
+ * SAFE TO CALL ON EVERY PAGE LOAD, and that is how it is meant to be used: on
+ * an ordinary visit it finds no return data and answers `{ resumed: false }`
+ * without touching the network. Calling it twice for one return is also safe —
+ * the return data is consumed the first time.
+ *
+ * The outcome is ALSO published on the `checkout` topic (`payment-completed` or
+ * `payment-failed`), exactly as it would have been had the shopper never left,
+ * so a page that already subscribes needs no second code path. Subscribe first,
+ * then call this, or the event fires before you are listening.
+ */
+export type ResumeCheckout = (params?: ResumeCheckoutParams) => Promise<ResumeCheckoutResponse>;

package/dist/actions/resume-checkout/types.js

@@ -0,0 +1,13 @@
+// Resume Checkout Types
+//
+// The RETURN LEG of an online checkout. Some payment methods — and 3-D Secure
+// on a card — take the shopper away to their bank or wallet and send them back
+// to `returnUrl` on a FRESH PAGE LOAD. The payment is not finished at that
+// point: the provider hands the browser a one-time result in the URL, and it
+// has to be handed back to the provider to complete the charge.
+//
+// `startCheckout` cannot do this. It ran in the page that is now gone.
+//
+// Served ONLY by the storefront runtime (a published website), like
+// `startCheckout`. On a register it does not exist.
+export {};

package/dist/actions/set-product-modifier-selections/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Set product modifier selections action
+ * Calls the setProductModifierSelections action on the parent window
+ */
+import type { SetProductModifierSelections } from "./types";
+export declare const setProductModifierSelections: SetProductModifierSelections;

package/dist/actions/set-product-modifier-selections/action.js

@@ -0,0 +1,8 @@
+/**
+ * Set product modifier selections action
+ * Calls the setProductModifierSelections action on the parent window
+ */
+import { commandFrameClient } from "../../client";
+export const setProductModifierSelections = async (params) => {
+    return await commandFrameClient.call("setProductModifierSelections", params);
+};

package/dist/actions/set-product-modifier-selections/mock.d.ts

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

package/dist/actions/set-product-modifier-selections/mock.js

@@ -0,0 +1,49 @@
+import { MOCK_CART, MOCK_PRODUCTS, buildCartLineModifiers, buildModifierRows } from "../../demo/database";
+export const mockSetProductModifierSelections = async (params) => {
+    console.log("[Mock] setProductModifierSelections called", params);
+    if (!params?.selections) {
+        return {
+            success: false,
+            reason: "selections is required (pass [] to clear)",
+            internalId: params?.internalId,
+            selections: [],
+            rows: [],
+            modifiersTotal: 0,
+            timestamp: new Date().toISOString()
+        };
+    }
+    // Write the selections onto the mock cart line (last line when no internalId).
+    // The mock does not re-run rule VALIDATION — the real host does — but it does reprice,
+    // because a replacement that left the old rows and the old money behind would make the
+    // cart disagree with itself the moment a cashier edits a line.
+    const line = params.internalId
+        ? MOCK_CART.products.find((p) => p.internalId === params.internalId)
+        : MOCK_CART.products[MOCK_CART.products.length - 1];
+    if (!line) {
+        return {
+            success: false,
+            reason: "No matching cart line",
+            internalId: params.internalId,
+            selections: [],
+            rows: [],
+            modifiersTotal: 0,
+            timestamp: new Date().toISOString()
+        };
+    }
+    // Full replacement — passing [] clears the rows. The line drops the product's resolved
+    // stack when it is built, so the menu is re-read from the catalogue to price against.
+    // Cart totals are not touched, for the same reason addProductToCart does not move them
+    // for modifiers: this mock does not accumulate per-line money.
+    const source = MOCK_PRODUCTS.find((product) => product._id === line.id);
+    line.modifierSelections = params.selections;
+    line.modifiers = buildCartLineModifiers(source?.modifiers, params.selections, source?.taxTable);
+    const { rows, modifiersTotal } = buildModifierRows(line.modifiers, line.quantity);
+    return {
+        success: true,
+        internalId: line.internalId,
+        selections: params.selections,
+        rows,
+        modifiersTotal,
+        timestamp: new Date().toISOString()
+    };
+};

package/dist/actions/set-product-modifier-selections/types.d.ts

@@ -0,0 +1,27 @@
+import type { ModifierSelection } from "../get-product-modifier-selections/types";
+import type { CFProdModifierBreakdown } from "../../CommonTypes";
+export interface SetProductModifierSelectionsParams {
+    /** The cart line to edit. Defaults to the active product's line. */
+    internalId?: string;
+    /**
+     * The line's COMPLETE new answers — replaces every existing selection on the
+     * line (send [] to clear all optional modifiers). Validated against the
+     * product's category-modifier rules exactly like addProductToCart({ modifiers }):
+     * a selection that breaks a rule rejects the edit and the line is unchanged.
+     */
+    selections: ModifierSelection[];
+}
+export interface SetProductModifierSelectionsResponse {
+    success: boolean;
+    /** Set when the edit was rejected (rule violation) — the line is unchanged. */
+    reason?: string;
+    internalId?: string;
+    /** The selections now on the line (the new ones on success, the old ones on rejection). */
+    selections: ModifierSelection[];
+    /** Display-ready — repaint from this instead of re-reading after an edit. */
+    rows: CFProdModifierBreakdown[];
+    /** Sum of `rows[].amount` for THIS line, in minor units. */
+    modifiersTotal: number;
+    timestamp: string;
+}
+export type SetProductModifierSelections = (params?: SetProductModifierSelectionsParams) => Promise<SetProductModifierSelectionsResponse>;

package/dist/actions/set-product-modifier-selections/types.js

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

package/dist/demo/database.d.ts

@@ -2,7 +2,7 @@
  * Mock Database for Standalone/Demo Mode
  * Stores mock data that mimics the Render environment
  */
-import { CFActiveCompany, CFActiveUser, CFActiveStation, CFActiveOutlet, CFActiveOrder, CFCustomer, CFProduct, CFActiveCart, CFCategory, CFActiveProduct, CFSession, CFActiveRefundDetails, CFSmartGridLayout } from '../CommonTypes';
+import { CFActiveCompany, CFActiveUser, CFActiveStation, CFActiveOutlet, CFActiveOrder, CFCustomer, CFProduct, CFActiveCart, CFCategory, CFActiveProduct, CFSession, CFActiveRefundDetails, CFSmartGridLayout, CFCartLineModifier, CFProdModifierBreakdown, CFModifierSelection, CFResolvedModifier } from '../CommonTypes';
 export * from './mocks';
 /** Replace mock catalog / context data in place (same array references mock handlers use). */
 export interface MockDatabaseConfig {
@@ -87,3 +87,26 @@ export declare const createOrderFromCart: (paymentType: string, amount: number,
  * open with `amountToBeCharged` reset to what's left, and returns null.
  */
 export declare const applyMockPayment: (amount: number, paymentType: string, processor?: string) => CFActiveOrder | null;
+/**
+ * Price the cashier's raw modifier answers into the rows a CART line carries (FT-0010).
+ *
+ * Here rather than in an action folder because two mocks need it — addProductToCart and
+ * setProductModifierSelections — and this module is already where the shared mock helpers
+ * live (`safeSerialize`, `resetMockCart`, `mockPublishEvent`).
+ *
+ * Note the two shapes that share the name `modifiers` and are NOT interchangeable:
+ * `FullProduct.modifiers` is `ResolvedModifier[]` (the menu — question + every choice),
+ * `ActiveProduct.modifiers` is `CartLineModifier[]` (one row per CHOSEN choice). The mock
+ * builds a cart line by spreading the product, so the menu must be stripped off the line
+ * before anything reads it, or every surface renders the catalogue as if it were picked.
+ *
+ * Names and unitPrice are snapshotted, as the real host does — a later rename never
+ * rewrites an open cart. No `total`: a cart row is per line UNIT, and the host extends it.
+ * Rule validation (required/min/max) is deliberately not mocked; the real host owns it.
+ */
+/** Extend a line's priced modifier rows by the line quantity. Mirrors kaching's `buildProdModifiers`. */
+export declare const buildModifierRows: (modifiers: CFCartLineModifier[] | undefined, lineQuantity: number | undefined) => {
+    rows: CFProdModifierBreakdown[];
+    modifiersTotal: number;
+};
+export declare const buildCartLineModifiers: (menu: CFResolvedModifier[] | undefined, selections: CFModifierSelection[] | undefined, productTaxTableId?: string) => CFCartLineModifier[];

package/dist/demo/database.js

@@ -914,3 +914,70 @@ export const applyMockPayment = (amount, paymentType, processor = 'cash') => {
     mockPublishEvent('payments', 'payment-done', { order });
     return order;
 };
+/**
+ * Price the cashier's raw modifier answers into the rows a CART line carries (FT-0010).
+ *
+ * Here rather than in an action folder because two mocks need it — addProductToCart and
+ * setProductModifierSelections — and this module is already where the shared mock helpers
+ * live (`safeSerialize`, `resetMockCart`, `mockPublishEvent`).
+ *
+ * Note the two shapes that share the name `modifiers` and are NOT interchangeable:
+ * `FullProduct.modifiers` is `ResolvedModifier[]` (the menu — question + every choice),
+ * `ActiveProduct.modifiers` is `CartLineModifier[]` (one row per CHOSEN choice). The mock
+ * builds a cart line by spreading the product, so the menu must be stripped off the line
+ * before anything reads it, or every surface renders the catalogue as if it were picked.
+ *
+ * Names and unitPrice are snapshotted, as the real host does — a later rename never
+ * rewrites an open cart. No `total`: a cart row is per line UNIT, and the host extends it.
+ * Rule validation (required/min/max) is deliberately not mocked; the real host owns it.
+ */
+/** Extend a line's priced modifier rows by the line quantity. Mirrors kaching's `buildProdModifiers`. */
+export const buildModifierRows = (modifiers, lineQuantity) => {
+    const quantity = lineQuantity ?? 1;
+    const rows = (modifiers ?? []).map((modifier) => ({
+        modifierId: modifier.modifierId,
+        modifierName: modifier.modifierName,
+        choiceId: modifier.choiceId,
+        choiceName: modifier.choiceName,
+        label: modifier.label ?? `${modifier.modifierName} - ${modifier.choiceName}`,
+        unitPrice: modifier.unitPrice,
+        quantity: modifier.quantity,
+        // extendPrice, not a raw multiply: a fractional line quantity (1.5 kg) must not
+        // leave fractional minor units on the row.
+        amount: extendPrice(modifier.unitPrice * modifier.quantity, quantity),
+        tax: 0,
+        ...(modifier.taxTableId ? { taxTableId: modifier.taxTableId } : {}),
+    }));
+    return { rows, modifiersTotal: rows.reduce((sum, row) => sum + row.amount, 0) };
+};
+export const buildCartLineModifiers = (menu, selections, productTaxTableId) => {
+    if (!menu?.length || !selections?.length)
+        return [];
+    const byModifier = new Map(menu.map((modifier) => [modifier._id, modifier]));
+    const rows = [];
+    for (const selection of selections) {
+        const modifier = byModifier.get(selection.modifierId);
+        if (!modifier)
+            continue;
+        const byChoice = new Map(modifier.choices.map((choice) => [choice._id, choice]));
+        for (const picked of selection.choices ?? []) {
+            const choice = byChoice.get(picked.choiceId);
+            // `quantity` is units per ONE line unit; 0 means "not chosen" and carries no row.
+            if (!choice || !(picked.quantity > 0))
+                continue;
+            rows.push({
+                modifierId: modifier._id,
+                modifierName: modifier.name,
+                choiceId: choice._id,
+                choiceName: choice.name,
+                // The cart's display label, like CustomFee.label — "Toppings - Avocado".
+                label: `${modifier.name} - ${choice.name}`,
+                unitPrice: choice.price,
+                quantity: picked.quantity,
+                // Modifier tax follows the parent product's table, as a fee's does.
+                ...(productTaxTableId ? { taxTableId: productTaxTableId } : {}),
+            });
+        }
+    }
+    return rows;
+};

package/dist/index.d.ts

@@ -21,6 +21,8 @@ export declare const command: {
     readonly getFinalContext: import(".").GetFinalContext;
     readonly addProductNote: import(".").AddProductNote;
     readonly addProductFee: import(".").AddProductFee;
+    readonly getProductModifierSelections: import(".").GetProductModifierSelections;
+    readonly setProductModifierSelections: import(".").SetProductModifierSelections;
     readonly setActiveProductFee: import(".").SetActiveProductFee;
     readonly setActiveProductDiscount: import(".").SetActiveProductDiscount;
     readonly getActiveProduct: import(".").GetActiveProduct;
@@ -44,6 +46,7 @@ export declare const command: {
     readonly createPaymentLink: import(".").CreatePaymentLink;
     readonly chargeMoto: import(".").ChargeMoto;
     readonly startCheckout: import(".").StartCheckout;
+    readonly resumeCheckout: import(".").ResumeCheckout;
     readonly addCustomerNote: import(".").AddCustomerNote;
     readonly removeCustomerNote: import(".").RemoveCustomerNote;
     readonly removeCustomerFromCart: import(".").RemoveCustomerFromCart;
@@ -158,6 +161,8 @@ export type { GetContext, GetContextResponse, GetContextResponseManage, GetConte
 export type { GetFinalContext, GetFinalContextResponse } from './actions/get-final-context/types';
 export type { AddProductNote, AddProductNoteParams, AddProductNoteResponse } from './actions/add-product-note/types';
 export type { AddProductFee, AddProductFeeParams, AddProductFeeResponse } from './actions/add-product-fee/types';
+export type { GetProductModifierSelections, GetProductModifierSelectionsParams, GetProductModifierSelectionsResponse, ModifierSelection, ModifierChoiceSelection, } from './actions/get-product-modifier-selections/types';
+export type { SetProductModifierSelections, SetProductModifierSelectionsParams, SetProductModifierSelectionsResponse, } from './actions/set-product-modifier-selections/types';
 export type { SetActiveProductFee, SetActiveProductFeeParams, SetActiveProductFeeResponse, } from './actions/set-active-product-fee/types';
 export type { SetActiveProductDiscount, SetActiveProductDiscountParams, SetActiveProductDiscountResponse, } from './actions/set-active-product-discount/types';
 export type { GetActiveProduct, GetActiveProductResponse } from './actions/get-active-product/types';
@@ -180,6 +185,7 @@ export type { IntegrationPayment, IntegrationPaymentParams, IntegrationPaymentRe
 export type { CreatePaymentLink, CreatePaymentLinkParams, CreatePaymentLinkResponse, } from './actions/create-payment-link/types';
 export type { ChargeMoto, ChargeMotoParams, ChargeMotoResponse, ChargeMotoCardFields, } from './actions/charge-moto/types';
 export type { StartCheckout, StartCheckoutParams, StartCheckoutResponse, StartCheckoutContact, StartCheckoutOrder, } from './actions/start-checkout/types';
+export type { ResumeCheckout, ResumeCheckoutParams, ResumeCheckoutResponse, ResumeCheckoutResult, } from './actions/resume-checkout/types';
 export type { AddCustomerNote, AddCustomerNoteParams, AddCustomerNoteResponse, } from './actions/add-customer-note/types';
 export type { RemoveCustomerNote, RemoveCustomerNoteParams, RemoveCustomerNoteResponse, } from './actions/remove-customer-note/types';
 export type { RemoveCustomerFromCart, RemoveCustomerFromCartResponse } from './actions/remove-customer-from-cart/types';

package/dist/index.js

@@ -20,6 +20,8 @@ import { updateCartItemQuantity } from './actions/update-cart-item-quantity/acti
 // Product Actions
 import { addProductNote } from './actions/add-product-note/action';
 import { addProductFee } from './actions/add-product-fee/action';
+import { getProductModifierSelections } from './actions/get-product-modifier-selections/action';
+import { setProductModifierSelections } from './actions/set-product-modifier-selections/action';
 import { setActiveProductFee } from './actions/set-active-product-fee/action';
 import { setActiveProductDiscount } from './actions/set-active-product-discount/action';
 import { getActiveProduct } from './actions/get-active-product/action';
@@ -44,6 +46,7 @@ import { integrationPayment } from './actions/integration-payment/action';
 import { createPaymentLink } from './actions/create-payment-link/action';
 import { chargeMoto } from './actions/charge-moto/action';
 import { startCheckout } from './actions/start-checkout/action';
+import { resumeCheckout } from './actions/resume-checkout/action';
 // Customer Actions
 import { addCustomerNote } from './actions/add-customer-note/action';
 import { removeCustomerNote } from './actions/remove-customer-note/action';
@@ -158,6 +161,8 @@ export const command = {
     // Product Actions
     addProductNote,
     addProductFee,
+    getProductModifierSelections,
+    setProductModifierSelections,
     setActiveProductFee,
     setActiveProductDiscount,
     getActiveProduct,
@@ -182,6 +187,7 @@ export const command = {
     createPaymentLink,
     chargeMoto,
     startCheckout,
+    resumeCheckout,
     // Customer Actions
     addCustomerNote,
     removeCustomerNote,

package/dist/projects/render/mocks.js

@@ -12,6 +12,8 @@ import { mockAddOrderNote } from '../../actions/add-order-note/mock';
 import { mockRemoveOrderNote } from '../../actions/remove-order-note/mock';
 import { mockAddProductDiscount } from '../../actions/add-product-discount/mock';
 import { mockAddProductFee } from '../../actions/add-product-fee/mock';
+import { mockGetProductModifierSelections } from '../../actions/get-product-modifier-selections/mock';
+import { mockSetProductModifierSelections } from '../../actions/set-product-modifier-selections/mock';
 import { mockRemoveProductDiscount } from '../../actions/remove-product-discount/mock';
 import { mockRemoveProductFee } from '../../actions/remove-product-fee/mock';
 import { mockSetActiveProductFee } from '../../actions/set-active-product-fee/mock';
@@ -32,6 +34,7 @@ import { mockGetCashRoundingAmount } from '../../actions/get-cash-rounding-amoun
 import { mockCreatePaymentLink } from '../../actions/create-payment-link/mock';
 import { mockChargeMoto } from '../../actions/charge-moto/mock';
 import { mockStartCheckout } from '../../actions/start-checkout/mock';
+import { mockResumeCheckout } from '../../actions/resume-checkout/mock';
 import { mockGetTimeClockStatus } from '../../actions/get-time-clock-status/mock';
 import { mockClearCart } from '../../actions/clear-cart/mock';
 import { mockDeleteParkedOrder } from '../../actions/delete-parked-order/mock';
@@ -113,6 +116,8 @@ export const RENDER_MOCKS = {
     addOrderNote: mockAddOrderNote,
     addProductDiscount: mockAddProductDiscount,
     addProductFee: mockAddProductFee,
+    getProductModifierSelections: mockGetProductModifierSelections,
+    setProductModifierSelections: mockSetProductModifierSelections,
     setActiveProductFee: mockSetActiveProductFee,
     setActiveProductDiscount: mockSetActiveProductDiscount,
     getActiveProduct: mockGetActiveProduct,
@@ -130,6 +135,7 @@ export const RENDER_MOCKS = {
     createPaymentLink: mockCreatePaymentLink,
     chargeMoto: mockChargeMoto,
     startCheckout: mockStartCheckout,
+    resumeCheckout: mockResumeCheckout,
     clearCart: mockClearCart,
     deleteParkedOrder: mockDeleteParkedOrder,
     voidOrder: mockVoidOrder,

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, VoidOrder, InitiateRefund, CashPayment, GetCashRoundingAmount, TapToPayPayment, TerminalPayment, ExtensionPayment, RedeemPayment, AddNonRevenueItem, AddCustomerNote, RemoveCustomerNote, RemoveCustomerFromCart, GoToStationHome, OpenCashDrawer, ShowNotification, ShowConfirmation, AuthenticateUser, PartialPayment, SwitchUser, SetRefundStockAction, SelectAllRefundItems, ResetRefundDetails, CalculateRefundTotal, GetRemainingRefundableQuantities, ProcessPartialRefund, RedeemRefund, GetRefundPlan, CheckPermission, 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, ApplyTransition, IntegrationPayment, GetSmartGridLayout, SaveSmartGridLayout, SendEmail, SendSms, CreatePaymentLink, ChargeMoto, StartCheckout, GetTimeClockStatus } 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, GetProductModifierSelections, SetProductModifierSelections, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, AddOrderNote, AddCartFee, ClearCart, ParkOrder, ResumeParkedOrder, DeleteParkedOrder, VoidOrder, InitiateRefund, CashPayment, GetCashRoundingAmount, TapToPayPayment, TerminalPayment, ExtensionPayment, RedeemPayment, AddNonRevenueItem, AddCustomerNote, RemoveCustomerNote, RemoveCustomerFromCart, GoToStationHome, OpenCashDrawer, ShowNotification, ShowConfirmation, AuthenticateUser, PartialPayment, SwitchUser, SetRefundStockAction, SelectAllRefundItems, ResetRefundDetails, CalculateRefundTotal, GetRemainingRefundableQuantities, ProcessPartialRefund, RedeemRefund, GetRefundPlan, CheckPermission, 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, ApplyTransition, IntegrationPayment, GetSmartGridLayout, SaveSmartGridLayout, SendEmail, SendSms, CreatePaymentLink, ChargeMoto, StartCheckout, ResumeCheckout, GetTimeClockStatus } from '../../index';
 export interface RenderProviderActions {
     exampleFunction: ExampleFunction;
     getProducts: GetProducts;
@@ -21,6 +21,8 @@ export interface RenderProviderActions {
     getFinalContext: GetFinalContext;
     addProductNote: AddProductNote;
     addProductFee: AddProductFee;
+    getProductModifierSelections: GetProductModifierSelections;
+    setProductModifierSelections: SetProductModifierSelections;
     setActiveProductFee: SetActiveProductFee;
     setActiveProductDiscount: SetActiveProductDiscount;
     getActiveProduct: GetActiveProduct;
@@ -49,6 +51,12 @@ export interface RenderProviderActions {
      * a register, because the two declare different things to the card networks.
      */
     startCheckout: StartCheckout;
+    /**
+     * The RETURN LEG of an online checkout, after a redirect payment method or
+     * 3-D Secure sent the shopper away and back. Storefront-only, like
+     * `startCheckout`, and safe to call on every page load.
+     */
+    resumeCheckout: ResumeCheckout;
     addNonRevenueItem: AddNonRevenueItem;
     addCustomerNote: AddCustomerNote;
     removeCustomerNote: RemoveCustomerNote;

package/dist/pubsub/topics/cart/product-modifiers-updated/types.d.ts

@@ -0,0 +1,16 @@
+import type { CFActiveProduct, CFModifierSelection } from "../../../../CommonTypes";
+import type { TopicEvent } from "../../../types";
+/**
+ * Payload for product-modifiers-updated event (FT-0010) — fired when a cart
+ * line's modifier selections are replaced via setProductModifierSelections.
+ */
+export interface ProductModifiersUpdatedPayload {
+    product: CFActiveProduct;
+    internalId?: string;
+    /** The line's complete new answers (full replacement). */
+    selections: CFModifierSelection[];
+}
+/**
+ * Typed event for product-modifiers-updated
+ */
+export type ProductModifiersUpdatedEvent = TopicEvent<ProductModifiersUpdatedPayload>;

package/dist/pubsub/topics/cart/product-modifiers-updated/types.js

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

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

@@ -17,6 +17,7 @@ export * from "./product-fee-added/types";
 export * from "./product-fee-removed/types";
 export * from "./product-note-added/types";
 export * from "./product-note-removed/types";
+export * from "./product-modifiers-updated/types";
 import type { CartCreatedPayload } from "./cart-created/types";
 import type { CartCustomerAssignedPayload } from "./customer-assigned/types";
 import type { ProductAddedPayload } from "./product-added/types";
@@ -32,5 +33,6 @@ import type { ProductFeeAddedPayload } from "./product-fee-added/types";
 import type { ProductFeeRemovedPayload } from "./product-fee-removed/types";
 import type { ProductNoteAddedPayload } from "./product-note-added/types";
 import type { ProductNoteRemovedPayload } from "./product-note-removed/types";
-export type CartEventPayload = CartCreatedPayload | CartCustomerAssignedPayload | ProductAddedPayload | ProductDeletedPayload | CartProductUpdatedPayload | CartDiscountAddedPayload | CartDiscountRemovedPayload | CartFeeAddedPayload | CartFeeRemovedPayload | ProductDiscountAddedPayload | ProductDiscountRemovedPayload | ProductFeeAddedPayload | ProductFeeRemovedPayload | ProductNoteAddedPayload | ProductNoteRemovedPayload;
-export type CartEventType = "cart-created" | "customer-assigned" | "customer-unassigned" | "product-added" | "product-deleted" | "product-updated" | "cart-discount-added" | "cart-discount-removed" | "cart-fee-added" | "cart-fee-removed" | "product-discount-added" | "product-discount-removed" | "product-fee-added" | "product-fee-removed" | "product-note-added" | "product-note-removed";
+import type { ProductModifiersUpdatedPayload } from "./product-modifiers-updated/types";
+export type CartEventPayload = CartCreatedPayload | CartCustomerAssignedPayload | ProductAddedPayload | ProductDeletedPayload | CartProductUpdatedPayload | CartDiscountAddedPayload | CartDiscountRemovedPayload | CartFeeAddedPayload | CartFeeRemovedPayload | ProductDiscountAddedPayload | ProductDiscountRemovedPayload | ProductFeeAddedPayload | ProductFeeRemovedPayload | ProductNoteAddedPayload | ProductNoteRemovedPayload | ProductModifiersUpdatedPayload;
+export type CartEventType = "cart-created" | "customer-assigned" | "customer-unassigned" | "product-added" | "product-deleted" | "product-updated" | "cart-discount-added" | "cart-discount-removed" | "cart-fee-added" | "cart-fee-removed" | "product-discount-added" | "product-discount-removed" | "product-fee-added" | "product-fee-removed" | "product-note-added" | "product-note-removed" | "product-modifiers-updated";

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

@@ -18,3 +18,4 @@ export * from "./product-fee-added/types";
 export * from "./product-fee-removed/types";
 export * from "./product-note-added/types";
 export * from "./product-note-removed/types";
+export * from "./product-modifiers-updated/types";

package/dist/pubsub/topics/checkout/payment-completed/types.d.ts

@@ -12,6 +12,18 @@ export interface PaymentCompletedPayload {
     receiptId: string;
     /** The provider's result code, e.g. `Authorised`. */
     resultCode: string;
+    /**
+     * OPAQUE PROOF OF THIS PAYMENT, handed to the browser by the provider and to
+     * nobody else. Pass it to the order-status read and the server verifies it
+     * with the provider before believing a word of it.
+     *
+     * It is the only evidence of an outcome that exists outside the provider's
+     * webhook, so it is what recovers an order whose confirmation never arrived.
+     * Treat it as a credential: do not log it, do not put it in a URL you share.
+     *
+     * Absent when the provider reported no payment (see `resultCode`).
+     */
+    sessionResult?: string;
 }
 /**
  * Typed event for payment-completed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.8.0-online.1",
+  "version": "0.8.0-online.3",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -57,7 +57,7 @@
     "ignoreBranchesMissingTickets": true
   },
   "dependencies": {
-    "@final-commerce/common": "2.2.2"
+    "@final-commerce/common": "2.2.4-preprod.1"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.0.0",