@final-commerce/command-frame 0.7.0-staging.9 → 0.7.1

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, BookingAvailability, BookingSlot, BookingSlotResource, BookingResource, Booking, CartReservation, OrderReservation } 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,16 +18,19 @@ export type CFTransaction = Transaction;
 export type CFCategory = Category;
 export type CFProductVariant = ProductVariant;
 export type CFProduct = FullProduct;
-export type CFBookingAvailability = BookingAvailability;
-export type CFBookingSlot = BookingSlot;
-export type CFBookingSlotResource = BookingSlotResource;
-export type CFBookingResource = BookingResource;
-export type CFBooking = Booking;
-/** A service sitting in the cart, and the same sale once it is on an order. A flow that draws a
- *  cart or a receipt needs both by name — reaching into the package's dist for them is not an
- *  interface. */
-export type CFCartReservation = CartReservation;
-export type CFOrderReservation = OrderReservation;
+/** 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;
@@ -116,21 +119,6 @@ export interface CFContextRender {
     stationName: string | null;
     outletId: string | null;
     outletName: string | null;
-    /**
-     * IANA zone the SHOP keeps, resolved as the outlet's own zone, else the
-     * company's — never the device's. A booking is stored as an instant, so which
-     * hour and which DAY it reads as is decided entirely by the zone it is printed
-     * in, and the screen's own machine is the one zone that is certainly wrong: a
-     * 17:00 Monday appointment in Vancouver is 21:30 for a till in St John's, and
-     * for some viewers it lands on Tuesday. Without this an app cannot label a
-     * slot or an appointment honestly — it can only guess, and it guesses wrong
-     * for every business that does not sit in the same zone as its screen.
-     *
-     * `null` when neither the outlet nor the company has one configured. Say so
-     * rather than falling back to the device: a missing timezone is a setup
-     * problem, and printing the machine's clock hides it.
-     */
-    timeZone: string | null;
     buildId: string | null;
     buildName: string | null;
     buildVersion: string | null;

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-context/mock.js

@@ -11,10 +11,6 @@ export const mockGetContext = () => {
         stationName: MOCK_STATION.name,
         outletId: MOCK_OUTLET.id,
         outletName: MOCK_OUTLET.name || null,
-        // Deliberately NOT the developer's own zone: an app that quietly formats with
-        // the machine's clock looks correct in preview and is wrong on every till that
-        // sits in a different city. Here it cannot look correct by accident.
-        timeZone: "America/Vancouver",
         buildId: "mock_build_id",
         buildName: "Mock Build",
         buildVersion: "1.0.0-mock",

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-refund-plan/mock.d.ts

@@ -15,5 +15,9 @@ import { GetRefundPlan } from './types';
  * and no company cash-rounding setting, so it always describes a FULL refund
  * with `rounding: 0` and no cash `payout`. Against real kaching the allocation
  * tracks the live selection and carries the drawer snap.
+ *
+ * `rows` / `allocation.breakdown` follow the engine's reading of the order
+ * (`line.total` includes the line's tax) but prorate by plain quantity share;
+ * the engine's remainder carry across earlier partial refunds is not modelled.
  */
 export declare const mockGetRefundPlan: GetRefundPlan;

package/dist/actions/get-refund-plan/mock.js

@@ -1,4 +1,5 @@
 import { MOCK_ORDERS } from '../../demo/database';
+import { mockRefundBreakdown, mockRefundRows } from './mockRows';
 /**
  * Demo derivation of the runtime `getRefundPlan`. Builds the per-source rows
  * from the mock order's `paymentMethods`, mirroring the runtime's capacity
@@ -15,6 +16,10 @@ import { MOCK_ORDERS } from '../../demo/database';
  * and no company cash-rounding setting, so it always describes a FULL refund
  * with `rounding: 0` and no cash `payout`. Against real kaching the allocation
  * tracks the live selection and carries the drawer snap.
+ *
+ * `rows` / `allocation.breakdown` follow the engine's reading of the order
+ * (`line.total` includes the line's tax) but prorate by plain quantity share;
+ * the engine's remainder carry across earlier partial refunds is not modelled.
  */
 export const mockGetRefundPlan = async (params) => {
     console.log('[Mock] getRefundPlan called', params);
@@ -62,16 +67,19 @@ export const mockGetRefundPlan = async (params) => {
         requiresGiftCardDestination: s.paymentType === 'redeem',
     }));
     const budget = legs.reduce((sum, l) => sum + l.amount, 0);
+    const rows = mockRefundRows(order);
     return {
         success: true,
         orderId: order._id,
         sources,
+        rows,
         allocation: {
             budget,
             // No cash rounding in the demo, so the goods value and the budget agree.
             itemTotal: budget,
             rounding: 0,
             legs,
+            breakdown: mockRefundBreakdown(rows, params?.items),
         },
         // Demo: no prior refunds, so remaining = captured minus the non-revenue load.
         remainingRefundable: Math.max(0, totalCaptured - nonRefundableLiability),

package/dist/actions/get-refund-plan/mockRows.d.ts

@@ -0,0 +1,6 @@
+import type { CFActiveOrder } from '../../CommonTypes';
+import type { GetRefundPlanParams, RefundPlanBreakdown, RefundPlanRow } from './types';
+/** Every row of a demo order. The demo has no refund ledger, so everything is refundable. */
+export declare function mockRefundRows(order: CFActiveOrder): RefundPlanRow[];
+/** The selection's breakdown; no `items` means everything, like the demo's full-refund legs. */
+export declare function mockRefundBreakdown(rows: RefundPlanRow[], items?: GetRefundPlanParams['items']): RefundPlanBreakdown;

package/dist/actions/get-refund-plan/mockRows.js

@@ -0,0 +1,114 @@
+// Demo derivation of `getRefundPlan`'s `rows` and `allocation.breakdown`, for
+// local/standalone mode only. See the note on `mockGetRefundPlan`.
+const minor = (v) => Math.round(Number(v ?? 0)) || 0;
+/** A line's whole-quantity money, reading `total` as tax-inclusive (the engine's reading). */
+function lineAmounts(line) {
+    const tax = minor(line.totalTax);
+    const itemDiscount = (line.discount?.itemDiscounts ?? []).reduce((s, d) => s + minor(d.amount), 0);
+    const cartDiscount = minor(line.discount?.cartDiscount?.amount);
+    const net = Math.max(0, minor(line.total) - tax);
+    const taxes = (line.taxes ?? []).map((t) => ({
+        name: String(t.name ?? 'Tax'),
+        percentage: t.percentage,
+        amount: minor(t.amount),
+    }));
+    return { subtotal: net + itemDiscount + cartDiscount, itemDiscount, cartDiscount, tax, taxes, total: net + tax };
+}
+function scale(a, share) {
+    if (share >= 1)
+        return a;
+    const r = (n) => Math.round(n * share);
+    const out = {
+        subtotal: r(a.subtotal),
+        itemDiscount: r(a.itemDiscount),
+        cartDiscount: r(a.cartDiscount),
+        tax: r(a.tax),
+        taxes: a.taxes.map((t) => ({ ...t, amount: r(t.amount) })),
+    };
+    return { ...out, total: out.subtotal - out.itemDiscount - out.cartDiscount + out.tax };
+}
+/** Every row of a demo order. The demo has no refund ledger, so everything is refundable. */
+export function mockRefundRows(order) {
+    const rows = [];
+    for (const li of order.lineItems ?? []) {
+        const itemKey = String(li.internalId || li.variantId || '');
+        if (!itemKey || !(li.quantity > 0))
+            continue;
+        rows.push({
+            type: 'product',
+            itemKey,
+            label: String(li.name ?? 'Item'),
+            ...(li.sku ? { sku: li.sku } : {}),
+            ...(li.attributes ? { attributes: li.attributes } : {}),
+            quantity: li.quantity,
+            refundableQuantity: li.quantity,
+            amounts: lineAmounts(li),
+        });
+    }
+    for (const cs of order.customSales ?? []) {
+        if (!cs.customSaleId || !(cs.quantity > 0))
+            continue;
+        rows.push({
+            type: 'customSale',
+            itemKey: cs.customSaleId,
+            label: String(cs.name ?? 'Custom sale'),
+            quantity: cs.quantity,
+            refundableQuantity: cs.quantity,
+            amounts: lineAmounts(cs),
+        });
+    }
+    for (const fee of order.cartFees ?? []) {
+        const amount = minor(fee.amount);
+        const tax = minor(fee.tax);
+        rows.push({
+            type: 'fee',
+            itemKey: String(fee.id),
+            label: String(fee.label || 'Cart fee'),
+            quantity: 1,
+            refundableQuantity: 1,
+            amounts: { subtotal: amount, itemDiscount: 0, cartDiscount: 0, tax, taxes: [], total: amount + tax },
+        });
+    }
+    for (const pm of order.paymentMethods ?? []) {
+        const tip = minor(pm.tip?.amount);
+        if (tip <= 0)
+            continue;
+        rows.push({
+            type: 'tip',
+            itemKey: pm.transactionId,
+            label: 'Tip',
+            paymentType: pm.paymentType,
+            quantity: 1,
+            refundableQuantity: 1,
+            amounts: { subtotal: tip, itemDiscount: 0, cartDiscount: 0, tax: 0, taxes: [], total: tip },
+        });
+    }
+    return rows;
+}
+/** The selection's breakdown; no `items` means everything, like the demo's full-refund legs. */
+export function mockRefundBreakdown(rows, items) {
+    const picked = new Map((items ?? []).map((i) => [i.itemKey, i.quantity]));
+    const selected = rows
+        .map((row) => {
+        const quantity = items?.length
+            ? Math.min(picked.get(row.itemKey) ?? 0, row.refundableQuantity)
+            : row.refundableQuantity;
+        return { type: row.type, itemKey: row.itemKey, quantity, amounts: scale(row.amounts, quantity / row.quantity) };
+    })
+        .filter((r) => r.quantity > 0);
+    const totals = { items: 0, discounts: 0, fees: 0, tax: 0, tip: 0, total: 0 };
+    for (const r of selected) {
+        const a = r.amounts;
+        if (r.type === 'fee')
+            totals.fees += a.subtotal;
+        else if (r.type === 'tip')
+            totals.tip += a.subtotal;
+        else {
+            totals.items += a.subtotal;
+            totals.discounts += a.itemDiscount + a.cartDiscount;
+        }
+        totals.tax += a.tax;
+        totals.total += a.total;
+    }
+    return { rows: selected, totals };
+}

package/dist/actions/get-refund-plan/types.d.ts

@@ -18,14 +18,11 @@ export interface GetRefundPlanParams {
      * nothing staged, no `allocation` comes back.
      */
     items?: {
-        /**
-         * `internalId` / `variantId` for a product, `customSaleId`, cart-fee id, tip
-         * `transactionId`, or a booking's own `internalId` on `order.reservations[]`.
-         */
+        /** `internalId` / `variantId` for a product, `customSaleId`, cart-fee id, or tip `transactionId`. */
         itemKey: string;
         quantity: number;
         /** Optional hint; inferred from the order when omitted. */
-        type?: 'product' | 'customSale' | 'fee' | 'tip' | 'reservation';
+        type?: 'product' | 'customSale' | 'fee' | 'tip';
     }[];
 }
 export interface RefundPlanSource {
@@ -79,6 +76,81 @@ export interface RefundPlanLeg {
         rounding: number;
     };
 }
+export type RefundPlanRowType = 'product' | 'customSale' | 'fee' | 'tip';
+/** One tax rate's share of a row's refund (minor units). */
+export interface RefundPlanTaxLine {
+    name: string;
+    /** Decimal rate as stored on the order (e.g. `0.15`), when the order recorded one. */
+    percentage?: number;
+    amount: number;
+}
+/**
+ * The money a row refunds, split the way a receipt shows it. Every field is
+ * minor units and already rounded; `subtotal − itemDiscount − cartDiscount +
+ * tax === total` always holds. DISPLAY IT — never re-add or prorate it.
+ */
+export interface RefundPlanAmounts {
+    /** Before discounts, tax excluded. For a tip row, the tip itself. */
+    subtotal: number;
+    /** Per-item discounts on the refunded quantity (positive). */
+    itemDiscount: number;
+    /** Cart discount share on the refunded quantity (positive). */
+    cartDiscount: number;
+    /** Tax on the refunded quantity. Zero for a tip. */
+    tax: number;
+    /** `tax` per rate — the price breakdown's tax lines. */
+    taxes: RefundPlanTaxLine[];
+    /** What the row refunds. */
+    total: number;
+}
+/**
+ * One refundable row of the order — a line item, custom sale, cart fee or tip —
+ * served ready to render. Rows with nothing left to refund are not listed.
+ */
+export interface RefundPlanRow {
+    type: RefundPlanRowType;
+    /** The key `items[].itemKey` takes, for this call and for `processPartialRefund`. */
+    itemKey: string;
+    /** Line or fee name; `Tip` for a tip. */
+    label: string;
+    /** Product lines only, when the order recorded them. */
+    sku?: string;
+    attributes?: string;
+    /** Tip rows only: the tender that took the tip (`card`, `cash`, …). */
+    paymentType?: string;
+    /** Quantity originally sold. Fees and tips are `1` — all or nothing. */
+    quantity: number;
+    /** Quantity still refundable — the stepper's max. */
+    refundableQuantity: number;
+    /** The money for refunding ALL of `refundableQuantity`. */
+    amounts: RefundPlanAmounts;
+}
+/** One selected row and what refunding the selected quantity of it moves. */
+export interface RefundPlanSelectedRow {
+    type: RefundPlanRowType;
+    itemKey: string;
+    quantity: number;
+    amounts: RefundPlanAmounts;
+}
+/**
+ * The selection's goods value broken down for display. Minor units;
+ * `items − discounts + fees + tax + tip === total === allocation.itemTotal`.
+ */
+export interface RefundPlanTotals {
+    /** Σ selected line subtotals (before discounts, tax excluded). */
+    items: number;
+    /** Σ item + cart discounts on the selected lines (positive). */
+    discounts: number;
+    /** Σ selected cart fees, tax excluded. */
+    fees: number;
+    tax: number;
+    tip: number;
+    total: number;
+}
+export interface RefundPlanBreakdown {
+    rows: RefundPlanSelectedRow[];
+    totals: RefundPlanTotals;
+}
 /**
  * The engine's own allocation of the CURRENT refund selection across the
  * order's captures — what a flow renders and submits instead of computing a
@@ -106,11 +178,25 @@ export interface RefundPlanAllocation {
     rounding: number;
     /** One leg per source that receives money. Submit as `legs`, unchanged. */
     legs: RefundPlanLeg[];
+    /**
+     * What the selection refunds, per row and in total — the numbers a refund
+     * dialog's rows and footer render. Optional so an older runtime still
+     * type-checks; kaching 1.12.1+ always sends it.
+     */
+    breakdown?: RefundPlanBreakdown;
 }
 export interface GetRefundPlanResponse {
     success: boolean;
     orderId: string;
     sources: RefundPlanSource[];
+    /**
+     * Every row still refundable on the order, with the money for refunding all
+     * of it — what a refund dialog lists before anything is selected. Replaces
+     * reading line totals off the order and deciding whether they include tax.
+     * Optional so an older runtime still type-checks; kaching 1.12.1+ always
+     * sends it.
+     */
+    rows?: RefundPlanRow[];
     /**
      * Ready-to-submit allocation of the current selection. Present only when a
      * refund selection exists on the active order. See {@link RefundPlanAllocation}.

package/dist/actions/get-remaining-refundable-quantities/mock.js

@@ -6,7 +6,6 @@ export const mockGetRemainingRefundableQuantities = async (_params) => {
         customSales: {},
         cartFees: {},
         tips: {},
-        reservations: {},
         timestamp: new Date().toISOString(),
     };
 };

package/dist/actions/get-remaining-refundable-quantities/types.d.ts

@@ -18,14 +18,6 @@ export interface GetRemainingRefundableQuantitiesResponse {
      * 0/1 semantics: `1` = still refundable, `0` = already refunded.
      */
     tips: Record<string, number>;
-    /**
-     * Remaining refundable bookings, keyed by `order.reservations[].internalId` —
-     * the same key `processPartialRefund` takes for `type: 'reservation'` items.
-     * A service is sold as a reservation rather than a line item, so without this
-     * map a refund screen can show everything on the order EXCEPT the appointment.
-     * 0/1 semantics: `1` = still refundable, `0` = already refunded.
-     */
-    reservations: Record<string, number>;
     timestamp: string;
 }
 export type GetRemainingRefundableQuantities = (params?: GetRemainingRefundableQuantitiesParams) => Promise<GetRemainingRefundableQuantitiesResponse>;

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

@@ -131,10 +131,10 @@ export interface ProcessPartialRefundParams {
     };
     /** Optional items to refund. */
     items?: {
-        /** internalId or variantId, customSaleId, or a booking's own internalId. */
+        /** internalId or variantId or customSaleId. */
         itemKey: string;
         quantity: number;
-        type?: 'product' | 'customSale' | 'fee' | 'tip' | 'reservation';
+        type?: 'product' | 'customSale' | 'fee' | 'tip';
         /**
          * Per-item stock disposition for a refunded **product** line — the
          * headless equivalent of the old refund popup's per-row restock/damaged

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()
+    };
+};