@final-commerce/command-frame 0.14.1-online.3 → 0.15.0-staging.2

package/README.md

@@ -147,6 +147,16 @@ Each client comes with built-in mock data for local development.
 const client = new RenderClient({ mockMode: true, debug: true });
 ```
 
+**Declines — mock only.** A test that needs to see how a flow treats a refusal sets `declines` in the dataset; a real till never reads it:
+
+```typescript
+setMockDatabase({ declines: { payments: ['terminal', 'tapToPay'], refunds: true, customTableWrites: true } });
+```
+
+- `payments`: those card commands reject with `CLOUD_PAYMENT_FAILED: Card declined` (cloud terminal) or `NATIVE_PAYMENT_FAILED: Card declined`.
+- `refunds: true`: `processPartialRefund` rejects with `Cloud refund failed`.
+- `customTableWrites: true`: `upsertCustomTableData` and `deleteCustomTableData` reject with `Table "<name>" not found`.
+
 ### Debugging
 
 Enable debug logging to see all message passing activity in the console:

package/dist/CommonTypes.d.ts

@@ -1,5 +1,5 @@
 export * from './common-types';
-import type { Tax, Tip, Address, MetadataItem, OrderAssignedUser, OrderInCart, OrderCustomStatus, 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, BookingAvailability, BookingSlot, BookingSlotResource, BookingResource, Booking, CartReservation, OrderReservation, CartAddress, CartShipping, Composite, CompositePart, CompositeItem, CompositeChoice, CompositeItemUnavailable, CompositePick, CartLineComponent, OrderLineItemComponent } from '@final-commerce/common/pos-types';
+import type { Tax, Tip, Address, MetadataItem, OrderAssignedUser, OrderInCart, OrderCustomStatus, 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, BookingAvailability, BookingSlot, BookingSlotResource, BookingResource, Booking, BookingRentalEnd, CartReservation, OrderReservation, CartAddress, CartShipping, Composite, CompositePart, CompositeItem, CompositeChoice, CompositeItemUnavailable, CompositePick, CartLineComponent, OrderLineItemComponent } 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>;
@@ -59,6 +59,7 @@ export type CFBookingSlot = BookingSlot;
 export type CFBookingSlotResource = BookingSlotResource;
 export type CFBookingResource = BookingResource;
 export type CFBooking = Booking;
+export type CFBookingRentalEnd = BookingRentalEnd;
 /** 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. */

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

@@ -37,7 +37,7 @@ export const mockAddBookingToCart = async (params) => {
         bookingId: booking.id,
         productId: params.productId,
         variantId: variant?._id ?? null,
-        resourceId: params.resourceId,
+        resourceId: booking.resourceId,
         name: product.name,
         resourceName: booking.resourceName,
         price,

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

@@ -2,16 +2,45 @@ import { CFBooking } from '../../CommonTypes';
 export interface AddBookingToCartParams {
     /** The bookable product (`productType: 'booking'`). */
     productId: string;
-    /** Which resource serves it: a member of staff, a room, a scooter. */
-    resourceId: string;
+    /**
+     * Which resource serves it: a member of staff, a room, a scooter. Omit for "any free one": the host picks the first
+     * resource, in availability order, with `qty` places free for the whole window (or every session of a course).
+     * A storefront still needs it.
+     */
+    resourceId?: string;
     /** Must be the START of a slot getBookingAvailability offered, ISO 8601. */
     startAt: string;
-    /** End of the window — the slot's own `endAt`, or the last slot's for a stay. */
-    endAt: string;
+    /** End of the window — the slot's own `endAt`, or the last slot's for a stay. Omit it only when you pass `periods`. */
+    endAt?: string;
+    /**
+     * Instead of `endAt`, for date-range rules: how many periods from `startAt` — hours, nights, days, or whole weeks /
+     * months. The host reads the end off its own grid and refuses what the rules refuse (`minStayLength` /
+     * `maxStayLength` from `getBookingAvailability`, each with its own unit — "2 nights", "1 week" — and whole periods).
+     * Pass exactly one of `endAt` and `periods`. A storefront still needs `endAt`.
+     */
+    periods?: number;
     /** The variant being sold. Defaults to the product's only variant. */
     variantId?: string;
     /** Whom the booking is for. Omit for a walk-in. */
     customerId?: string;
+    /**
+     * How many places of the resource this booking takes (seats in a class, spots in a session). A whole
+     * number, default 1. Each place is charged: the reservation's `quantity` counts them and its `total` is
+     * `price × quantity`. Refused above the resource's capacity and above the rule's `maxQtyPerBooking`.
+     * A window of several nights or days (a date range on a till) is charged per period too: `quantity = qty × periods`.
+     */
+    qty?: number;
+    /**
+     * How many people the booking is for (a room for 3, a table for 4). A whole number. Recorded on the booking; it takes
+     * no extra places and does not change the price. Refused above the rule's `maxPartySize`. Omit when not asked.
+     */
+    partySize?: number;
+    /**
+     * Book the whole course (session rules sold as a course): one hold per session, all or nothing. Pass the course's own
+     * `startAt` / `endAt` from `getBookingAvailability` (`availability.course`); other values are refused. Refused on rules
+     * that do not sell a course; a course rule refuses a booking without it.
+     */
+    course?: boolean;
 }
 export interface AddBookingToCartResponse {
     /** False when the command was refused — a taken window, a rule, a booking that is not yours. */

package/dist/actions/attach-checkout-contact/types.d.ts

@@ -1,6 +1,6 @@
 /**
- * Contact for the order. `email` is where the receipt goes and is required. The two boxes are the
- * shopper account's (see `getShopperAccount`); a box never stops the payment, whatever happens to it.
+ * Guest contact for the order. There is no shopper account, so this is the only
+ * way to reach them — `email` is where the receipt goes and is required.
  */
 export interface AttachCheckoutContactParams {
     email: string;
@@ -8,18 +8,6 @@ export interface AttachCheckoutContactParams {
     phone?: string;
     /** Defaults to the outlet the storefront booted against. */
     outletId?: string;
-    /**
-     * The checkout's account box ("Track this order and check out faster next time", from
-     * `getShopperAccount`): links this email to a shopper account at this store. Omitted = not ticked.
-     */
-    accountOptIn?: boolean;
-    /** The news box ("Email me news and offers"): this store's consent, true or false. Omitted = not asked. */
-    marketingOptIn?: boolean;
-    /**
-     * The "Save this address" box (signed-in shoppers): once the order is paid, its shipping address is
-     * saved to the shopper's account. Omitted = not ticked.
-     */
-    saveAddress?: boolean;
 }
 export interface AttachCheckoutContactResponse {
     /**

package/dist/actions/delete-custom-table-data/mock.js

@@ -1,5 +1,7 @@
+import { assertMockCustomTableWriteNotDeclined } from "../../demo/database";
 export const mockDeleteCustomTableData = async (params) => {
     console.log("[Mock] deleteCustomTableData called", params);
+    assertMockCustomTableWriteNotDeclined(params?.tableName ?? "");
     return {
         success: true,
         timestamp: new Date().toISOString()

package/dist/actions/get-active-user/mock.js

@@ -1,6 +1,8 @@
-import { MOCK_USER_MARIO } from "../../demo/database";
+import { MOCK_USER_MARIO, mockPublishEvent } from "../../demo/database";
 export const mockGetActiveUser = async () => {
     console.log("[Mock] getActiveUser called");
+    // Same as the host (kaching get-active-user handler): reading the user publishes `users` / `get-active-user`.
+    mockPublishEvent("users", "get-active-user", { user: MOCK_USER_MARIO });
     return {
         success: true,
         user: MOCK_USER_MARIO,

package/dist/actions/get-booking-rental-ends/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Get booking rental ends action
+ * Calls the getBookingRentalEnds action on the parent window
+ */
+import type { GetBookingRentalEnds } from './types';
+export declare const getBookingRentalEnds: GetBookingRentalEnds;

package/dist/actions/get-booking-rental-ends/action.js

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

package/dist/actions/get-booking-rental-ends/mock.d.ts

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

package/dist/actions/get-booking-rental-ends/mock.js

@@ -0,0 +1,6 @@
+import { MOCK_ONLY_SINGLE_SLOTS } from '../hold-booking/mock';
+// The mock shop has no date-range rules, so no stay can start in it — the same refusal `holdBooking` gives a stay.
+export const mockGetBookingRentalEnds = async (params) => {
+    console.log('[Mock] getBookingRentalEnds called', params);
+    return { success: false, reason: MOCK_ONLY_SINGLE_SLOTS, timestamp: new Date().toISOString() };
+};

package/dist/actions/get-booking-rental-ends/types.d.ts

@@ -0,0 +1,31 @@
+import { CFBookingRentalEnd } from '../../CommonTypes';
+export interface GetBookingRentalEndsParams {
+    /** The bookable product. Date-range rules only (hours, nights, days, weeks, months). */
+    productId: string;
+    /** The chosen check-in: the `startAt` of a slot `getBookingAvailability` offered, ISO 8601. */
+    startAt: string;
+    /**
+     * Last shop day an end may fall on, `YYYY-MM-DD` (the format of `getBookingAvailability`'s `fromDay`). Ends past it are
+     * not computed. Leave one page more than you show — a check-in on the last day, a whole week or month — and never a day
+     * before the chosen check-out; ask again with a later day when the cashier pages or steps past it. The shortest allowed
+     * stay comes even when it ends past it — alone — so a `minStay` longer than what you show still books.
+     */
+    untilDay: string;
+    /** The resource that must serve the whole stay. Omit for "any free one", picked per end exactly as the hold picks it. */
+    resourceId?: string;
+    /** Places the booking takes, as you will pass to `addBookingToCart`. Default 1. */
+    qty?: number;
+}
+export interface GetBookingRentalEndsResponse {
+    /** False when no stay can start here — a taken first night, a `minStay` the free nights do not reach, a non-range rule. */
+    success: boolean;
+    /** Why, in the host's own words. Absent on success. */
+    reason?: string;
+    /**
+     * Every end the stay may have now, ascending, never empty on success. Enable only these as check-out; highlight the
+     * chosen one's `coveredSlots`; send its `endAt` to `addBookingToCart`.
+     */
+    ends?: CFBookingRentalEnd[];
+    timestamp: string;
+}
+export type GetBookingRentalEnds = (params: GetBookingRentalEndsParams) => Promise<GetBookingRentalEndsResponse>;

package/dist/actions/get-booking-rental-ends/types.js

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

package/dist/actions/get-cash-change/action.d.ts

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

package/dist/actions/get-cash-change/action.js

@@ -0,0 +1,8 @@
+/**
+ * Get cash change action — what a cash tender would give back, computed by the till exactly as `cashPayment` computes
+ * it (after cash rounding). Read-only: nothing is paid.
+ */
+import { commandFrameClient } from '../../client';
+export const getCashChange = async (params) => {
+    return await commandFrameClient.call('getCashChange', params);
+};

package/dist/actions/get-cash-change/mock.d.ts

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

package/dist/actions/get-cash-change/mock.js

@@ -0,0 +1,6 @@
+// The mock does no money: change is the till's arithmetic (cash rounding included), so a screen sees the host's
+// refusal instead of a number the mock made up.
+export const mockGetCashChange = async (params) => {
+    console.log('[Mock] getCashChange called', params);
+    throw new Error('Cash change is computed by the till');
+};

package/dist/actions/get-cash-change/types.d.ts

@@ -0,0 +1,23 @@
+export interface GetCashChangeParams {
+    /** Cash handed over, integer MINOR units (e.g. from common `parseAmountToMinorUnits`). */
+    tenderedAmount: number;
+    /** What it is tendered against, MINOR units. Default: the cart's balance due — the same default as `getCashRoundingAmount`. */
+    amount?: number;
+}
+export interface GetCashChangeResponse {
+    success: boolean;
+    /** The amount tendered against, before cash rounding (MINOR units). */
+    amountDue: number;
+    /** After the company's cash-rounding setting — what `cashPayment` charges for cash (MINOR units). */
+    roundedAmountDue: number;
+    /** `roundedAmountDue − amountDue`, signed (MINOR units). 0 without a cash-rounding setting. */
+    cashRounding: number;
+    /** Echo of the tender (MINOR units). */
+    tenderedAmount: number;
+    /** ≥ 0: the change `cashPayment({ tenderedAmount })` returns for this tender. 0 while the tender is short. */
+    change: number;
+    /** ≥ 0: how much the tender is short of `roundedAmountDue`. 0 when it covers it. */
+    remaining: number;
+    timestamp: string;
+}
+export type GetCashChange = (params: GetCashChangeParams) => Promise<GetCashChangeResponse>;

package/dist/actions/get-cash-change/types.js

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

package/dist/actions/get-checkout-status/types.d.ts

@@ -21,15 +21,6 @@ export interface GetCheckoutStatusResponse {
      */
     cancelReason?: CheckoutCancelReason;
     receiptId: string | null;
-    /**
-     * The shopper account line for the confirmation page: "Added to your orders" when signed in, else
-     * (any guest who gave an email) a prompt to get a code; for `sign-in`, call requestShopperCode() with
-     * no params and it goes to that email. Ready to display.
-     */
-    account?: {
-        label: string;
-        action: 'none' | 'sign-in';
-    };
     timestamp: string;
 }
 /** Never throws for an unknown order: answers `status: null`. */

package/dist/actions/get-custom-table-data/mock.d.ts

@@ -1,2 +1,7 @@
 import { GetCustomTableData } from "./types";
+/**
+ * The host's read (kaching get-custom-table-data/handler.ts, customTables.ts:99-113): the table's rows, offset 0 and
+ * limit 100 by default, so a row upsertCustomTableData wrote is read back. The mock filters by plain field equality only
+ * and refuses query operators rather than guess them.
+ */
 export declare const mockGetCustomTableData: GetCustomTableData;

package/dist/actions/get-custom-table-data/mock.js

@@ -1,34 +1,23 @@
+import { MOCK_CUSTOM_TABLE_DATA } from "../../demo/mocks/custom-tables";
+/**
+ * The host's read (kaching get-custom-table-data/handler.ts, customTables.ts:99-113): the table's rows, offset 0 and
+ * limit 100 by default, so a row upsertCustomTableData wrote is read back. The mock filters by plain field equality only
+ * and refuses query operators rather than guess them.
+ */
 export const mockGetCustomTableData = async (params) => {
     console.log("[Mock] getCustomTableData called", params);
-    const mockData = [
-        {
-            _id: "user_data_1",
-            fullName: "John Doe",
-            email: "john.doe@example.com",
-            isActive: true,
-            createdAt: "2024-01-10T10:00:00.000Z",
-            updatedAt: "2024-01-10T10:00:00.000Z"
-        },
-        {
-            _id: "user_data_2",
-            fullName: "Jane Smith",
-            email: "jane.smith@example.com",
-            isActive: true,
-            createdAt: "2024-01-11T11:00:00.000Z",
-            updatedAt: "2024-01-11T11:00:00.000Z"
-        },
-        {
-            _id: "user_data_3",
-            fullName: "Bob Johnson",
-            email: "bob.johnson@example.com",
-            isActive: false,
-            createdAt: "2024-01-12T09:00:00.000Z",
-            updatedAt: "2024-01-15T14:30:00.000Z"
-        }
-    ];
+    if (!params?.tableName)
+        throw new Error("tableName is required");
+    const query = params.query ?? {};
+    const operator = Object.entries(query).find(([key, value]) => key.startsWith("$") || (typeof value === "object" && value !== null));
+    if (operator) {
+        throw new Error(`The mock filters custom-table rows by plain field equality only; "${operator[0]}" is not modelled`);
+    }
+    const rows = (MOCK_CUSTOM_TABLE_DATA[params.tableName] ?? []).filter(row => Object.entries(query).every(([key, value]) => row[key] === value));
+    const offset = params.offset || 0;
     return {
         success: true,
-        data: mockData,
+        data: rows.slice(offset, offset + (params.limit || 100)),
         timestamp: new Date().toISOString()
     };
 };

package/dist/actions/get-orders-summary/action.d.ts

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

package/dist/actions/get-orders-summary/action.js

@@ -0,0 +1,5 @@
+/** Get orders summary action — counts and the money total of the orders `getOrders` would match, from the till. */
+import { commandFrameClient } from '../../client';
+export const getOrdersSummary = async (params) => {
+    return await commandFrameClient.call('getOrdersSummary', params);
+};

package/dist/actions/get-orders-summary/mock.d.ts

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

package/dist/actions/get-orders-summary/mock.js

@@ -0,0 +1,5 @@
+// The mock does no money: totals and shares are the till's, so a screen sees the host's refusal, not mock maths.
+export const mockGetOrdersSummary = async (params) => {
+    console.log('[Mock] getOrdersSummary called', params);
+    throw new Error('The orders summary is computed by the till');
+};

package/dist/actions/get-orders-summary/types.d.ts

@@ -0,0 +1,24 @@
+import type { GetOrdersParams } from '../get-orders/types';
+/** The same filters as `getOrders`; paging and sorting do not apply to a summary. */
+export type GetOrdersSummaryParams = Omit<GetOrdersParams, 'limit' | 'offset' | 'sortBy' | 'sortDirection'>;
+export interface GetOrdersSummaryResponse {
+    success: boolean;
+    /** Matched orders, leaving out those still in a cart, parked or deleted from park (legacy `status`). */
+    orderCount: number;
+    /** Σ `summary.total` of those orders, integer MINOR units. */
+    ordersTotal: number;
+    currency: string;
+    minorUnits: number;
+    /** Legacy `status === 'completed'`; `percentOfOrders` rounded to a whole percent by the till. */
+    completed: {
+        count: number;
+        percentOfOrders: number;
+    };
+    /** Legacy `status` 'refunded' or 'partial-refund'. */
+    refunded: {
+        count: number;
+        percentOfOrders: number;
+    };
+    timestamp: string;
+}
+export type GetOrdersSummary = (params?: GetOrdersSummaryParams) => Promise<GetOrdersSummaryResponse>;

package/dist/actions/get-orders-summary/types.js

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

package/dist/actions/hold-booking/mock.d.ts

@@ -1,2 +1,3 @@
 import { HoldBooking } from './types';
+export declare const MOCK_ONLY_SINGLE_SLOTS = "[Mock] the mock shop sells single 30-minute slots \u2014 pass the slot's endAt";
 export declare const mockHoldBooking: HoldBooking;

package/dist/actions/hold-booking/mock.js

@@ -1,35 +1,49 @@
-import { MOCK_BOOKINGS, MOCK_BOOKING_RESOURCES, mockLiveBookings } from '../../demo/database';
-import { ReservationStatus } from '@final-commerce/common';
+import { MOCK_BOOKINGS, MOCK_BOOKING_RESOURCES, mockBookingAvailability, mockLiveBookings } from '../../demo/database';
+import { ReservationStatus, pickFreeResource } from '@final-commerce/common';
 const BUFFER_MINUTES = 5;
 const HOLD_MINUTES = 10;
+const TAKEN = 'That window has just been taken — pick another slot.';
+export const MOCK_ONLY_SINGLE_SLOTS = "[Mock] the mock shop sells single 30-minute slots — pass the slot's endAt";
 let held = 0;
+const refused = (reason) => ({
+    success: false,
+    reason,
+    timestamp: new Date().toISOString(),
+});
+const offeredSlot = (productId, startAt) => mockBookingAvailability(productId, new Date(startAt), new Date(Date.parse(startAt) + 60000)).slots.find((slot) => slot.startAt === new Date(startAt).toISOString());
+// The mock refuses a taken window like the host does. A mock that always said yes would
+// let a booking screen ship without ever handling the one error it will actually meet.
+const windowIsTaken = (resourceId, startAt, bufferEndAt) => mockLiveBookings().some((entry) => entry.resourceId === resourceId && new Date(entry.startAt) < bufferEndAt && new Date(entry.bufferEndAt) > startAt);
 export const mockHoldBooking = async (params) => {
     console.log('[Mock] holdBooking called', params);
+    if (params.course || (params.periods !== undefined && params.periods !== 1))
+        return refused(MOCK_ONLY_SINGLE_SLOTS);
+    const slot = offeredSlot(params.productId, params.startAt);
+    const resourceId = params.resourceId ?? (slot && pickFreeResource(slot, params.qty)?.resourceId);
+    const end = params.endAt ?? slot?.endAt;
+    if (!resourceId || !end)
+        return refused(TAKEN);
     const startAt = new Date(params.startAt);
-    const endAt = new Date(params.endAt);
+    const endAt = new Date(end);
     const bufferEndAt = new Date(endAt.getTime() + BUFFER_MINUTES * 60000);
-    // The mock refuses a taken window like the host does. A mock that always said yes would
-    // let a booking screen ship without ever handling the one error it will actually meet.
-    const clash = mockLiveBookings().some((entry) => entry.resourceId === params.resourceId &&
-        new Date(entry.startAt) < bufferEndAt &&
-        new Date(entry.bufferEndAt) > startAt);
-    if (clash) {
-        return { success: false, reason: 'That window has just been taken — pick another slot.', timestamp: new Date().toISOString() };
-    }
+    if (windowIsTaken(resourceId, startAt, bufferEndAt))
+        return refused(TAKEN);
     const booking = {
         // A counter, not a clock: two holds in the same millisecond used to share an id, and cancel
         // or remove then acted on the wrong row. Scripted tests hit that routinely.
         id: `bk_mock_${(held += 1)}`,
         productId: params.productId,
-        resourceId: params.resourceId,
+        resourceId,
         variantId: params.variantId,
         startAt: startAt.toISOString(),
         endAt: endAt.toISOString(),
         bufferEndAt: bufferEndAt.toISOString(),
         customerId: params.customerId,
+        qty: params.qty,
+        partySize: params.partySize,
         status: ReservationStatus.HELD,
         expiresAt: new Date(Date.now() + HOLD_MINUTES * 60000).toISOString(),
-        resourceName: MOCK_BOOKING_RESOURCES.find(({ id }) => id === params.resourceId)?.name,
+        resourceName: MOCK_BOOKING_RESOURCES.find(({ id }) => id === resourceId)?.name,
     };
     // Held in the same list availability reads, so the slot really does disappear.
     MOCK_BOOKINGS.push(booking);

package/dist/actions/hold-booking/types.d.ts

@@ -1,20 +1,46 @@
 import { CFBooking } from '../../CommonTypes';
 export interface HoldBookingParams {
     productId: string;
-    /** Which resource serves it: a member of staff, a room, a scooter. */
-    resourceId: string;
+    /**
+     * Which resource serves it: a member of staff, a room, a scooter. Omit for "any free one": the host picks the first
+     * resource, in availability order, with `qty` places free for the whole window (or every session of a course).
+     * A storefront still needs it.
+     */
+    resourceId?: string;
     /** Must be the START of a slot the host offered, ISO 8601. */
     startAt: string;
     /**
-     * End of the window — the `endAt` of the slot you picked, or of the last slot in a stay.
-     * Required: a window that cannot be lined up with the grid is refused, and the till
-     * has no local copy of the rules to derive it from.
+     * End of the window — the `endAt` of the slot you picked, or of the last slot in a stay. A window that cannot be
+     * lined up with the grid is refused. Omit it only when you pass `periods`.
      */
-    endAt: string;
+    endAt?: string;
+    /**
+     * Instead of `endAt`, for date-range rules: how many periods from `startAt` — hours, nights, days, or whole weeks /
+     * months. The host reads the end off its own grid and refuses what the rules refuse (`minStayLength` /
+     * `maxStayLength` from `getBookingAvailability`, each with its own unit — "2 nights", "1 week" — and whole periods).
+     * Pass exactly one of `endAt` and `periods`. A storefront still needs `endAt`.
+     */
+    periods?: number;
     /** The variant being sold, when the flow already knows which one. */
     variantId?: string;
     /** Whom the booking is for. Omit for a walk-in. */
     customerId?: string;
+    /**
+     * How many places of the resource this booking takes (seats in a class, spots in a session). A whole
+     * number, default 1. Refused above the resource's capacity and above the rule's `maxQtyPerBooking`.
+     */
+    qty?: number;
+    /**
+     * How many people the booking is for (a room for 3, a table for 4). A whole number. Recorded on the booking; it takes
+     * no extra places and does not change the price. Refused above the rule's `maxPartySize`. Omit when not asked.
+     */
+    partySize?: number;
+    /**
+     * Book the whole course (session rules sold as a course): one hold per session, all or nothing. Pass the course's own
+     * `startAt` / `endAt` from `getBookingAvailability` (`availability.course`); other values are refused. Refused on rules
+     * that do not sell a course; a course rule refuses a booking without it.
+     */
+    course?: boolean;
 }
 export interface HoldBookingResponse {
     /** False when the command was refused — a taken window, a rule, a booking that is not yours. */
@@ -23,6 +49,9 @@ export interface HoldBookingResponse {
     reason?: string;
     /** The claim. `expiresAt` says how long it survives unpaid; `id` is what you confirm or cancel. */
     booking?: CFBooking;
+    /** A course: the id every session's hold shares, and how many sessions it holds. `booking` is the first session. */
+    groupId?: string;
+    sessions?: number;
     timestamp: string;
 }
 export type HoldBooking = (params: HoldBookingParams) => Promise<HoldBookingResponse>;

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

@@ -6,6 +6,11 @@ export interface PartialPaymentParams {
     isPercent?: boolean;
     /** If true, opens the split payment UI. */
     openUI?: boolean;
+    /**
+     * true: the host refuses an amount above the balance due (the same balance `getCashRoundingAmount()` defaults to) or a
+     * percent above 100, with its own reason. Absent / false: no ceiling, exactly as before.
+     */
+    refuseAboveBalance?: boolean;
 }
 export interface PartialPaymentResponse {
     success: boolean;

package/dist/actions/process-partial-refund/mock.js

@@ -1,3 +1,4 @@
+import { MOCK_DECLINES } from '../../demo/database';
 export const mockProcessPartialRefund = async (params) => {
     // The mock has no split-payment modal or order engine, so `openUI` (default
     // true on the real command), `legs` (the headless per-tender allocation), a
@@ -10,6 +11,10 @@ export const mockProcessPartialRefund = async (params) => {
     if (params?.legs && params?.giftCard) {
         throw new Error('refund.giftCardAndLegs: pass either `legs` (you allocate) or `giftCard` (the engine allocates), not both');
     }
+    if (MOCK_DECLINES.refunds) {
+        console.warn('[Mock] processPartialRefund failed — the mock dataset sets declines.refunds');
+        throw new Error('Cloud refund failed');
+    }
     console.log('[Mock] processPartialRefund called', {
         ...params,
         openUI: params?.openUI ?? true,

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

@@ -1,6 +1,7 @@
-import { applyMockPayment, MOCK_CART } from '../../demo/database';
+import { applyMockPayment, assertMockPaymentNotDeclined, MOCK_CART } from '../../demo/database';
 export const mockTapToPayPayment = async (params) => {
     console.log('[Mock] tapToPayPayment called', params);
+    assertMockPaymentNotDeclined('tapToPay', false);
     // 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;

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

@@ -1,7 +1,8 @@
-import { applyMockPayment, MOCK_CART } from '../../demo/database';
+import { applyMockPayment, assertMockPaymentNotDeclined, MOCK_CART } from '../../demo/database';
 export const mockTerminalPayment = async (params) => {
     console.log('[Mock] terminalPayment called', params);
     const connectionType = params?.paymentType || 'Cloud';
+    assertMockPaymentNotDeclined('terminal', connectionType === 'Cloud');
     // Simulate terminal interaction
     window.alert(`Demo: Processing ${connectionType} Terminal Payment...\n(Please tap, insert, or swipe card on terminal)`);
     const due = params?.amount ?? MOCK_CART.amountToBeCharged ?? MOCK_CART.total;

package/dist/actions/upsert-custom-table-data/mock.d.ts

@@ -1,2 +1,8 @@
 import { UpsertCustomTableData } from './types';
+/**
+ * The host's upsert (kaching upsert-custom-table-data/handler.ts, customTables.ts:120-271): an `_id` of an existing row
+ * updates it, anything else inserts (a given `_id` kept as-is); `createdAt`/`updatedAt` are the host's; the row is
+ * stored, so getCustomTableData reads it back. Not modelled: the table's field schema — the host drops keys that are
+ * not fields of the table and refuses an unknown table; the mock stores every key.
+ */
 export declare const mockUpsertCustomTableData: UpsertCustomTableData;