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

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/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-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.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.';
+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;

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

@@ -1,17 +1,33 @@
+import { MOCK_CUSTOM_TABLE_DATA } from '../../demo/mocks/custom-tables';
+import { assertMockCustomTableWriteNotDeclined, mockPublishEvent } from '../../demo/database';
+import { generateMongoID } from '@final-commerce/common';
+/**
+ * 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 const mockUpsertCustomTableData = async (params) => {
+    var _a;
     console.log('[Mock] upsertCustomTableData called', params);
-    const data = params?.data;
+    if (!params?.tableName)
+        throw new Error('tableName is required');
+    assertMockCustomTableWriteNotDeclined(params.tableName);
+    const { _id: givenId, ...fields } = (params.data ?? {});
+    delete fields.createdAt;
+    delete fields.updatedAt;
+    const rows = (MOCK_CUSTOM_TABLE_DATA[_a = params.tableName] ?? (MOCK_CUSTOM_TABLE_DATA[_a] = []));
     const now = new Date().toISOString();
-    // Return the data with _id and timestamps added
-    const resultData = {
-        ...data,
-        _id: data?._id || `mock_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
-        createdAt: data?.createdAt || now,
-        updatedAt: now,
-    };
+    const existing = typeof givenId === 'string' ? rows.find((row) => row._id === givenId) : undefined;
+    const row = existing
+        ? Object.assign(existing, fields, { updatedAt: now })
+        : { _id: typeof givenId === 'string' ? givenId : generateMongoID(), ...fields, createdAt: now, updatedAt: now };
+    if (!existing)
+        rows.push(row);
+    mockPublishEvent('custom-tables', existing ? 'row-updated' : 'row-created', { tableName: params.tableName, ...row });
     return {
         success: true,
-        data: resultData,
+        data: { ...row },
         timestamp: now,
     };
 };

package/dist/demo/database.d.ts

@@ -23,6 +23,17 @@ export interface MockDatabaseConfig {
     orderStatuses?: CFOrderStatusDefinition[];
     /** Products hidden at an outlet (the host's `catalog-visibility`, product-level rows). Empty = sold everywhere. */
     catalogVisibility?: MockCatalogVisibility[];
+    /** MOCK ONLY — the switch a test flips to make the host refuse. Absent = everything succeeds. */
+    declines?: MockDeclines;
+}
+/** MOCK ONLY: what the mock host refuses, so a test can see how a flow treats a failure. A real till never reads this. */
+export interface MockDeclines {
+    /** Card payments that are declined: `terminalPayment` (cloud or reader) and `tapToPayPayment`. Cash never declines. */
+    payments?: ('terminal' | 'tapToPay')[];
+    /** Every `processPartialRefund` fails. */
+    refunds?: boolean;
+    /** Every `upsertCustomTableData` / `deleteCustomTableData` rejects with the till's only refusal text for a table write. */
+    customTableWrites?: boolean;
 }
 export interface MockCatalogVisibility {
     productId: string;
@@ -124,6 +135,11 @@ export declare const MOCK_ORDER_STATUSES: CFOrderStatusDefinition[];
 export declare function setMockDatabase(config: Partial<MockDatabaseConfig>): void;
 export declare const safeSerialize: <T>(data: T) => T;
 type MockEventCallback = (event: any) => void;
+export declare let MOCK_DECLINES: MockDeclines;
+/** MOCK ONLY: the dataset's `declines.payments` switch, failing with the till processor's text (kaching `dispatchPay.ts:208-220`). */
+export declare const assertMockPaymentNotDeclined: (paymentType: "terminal" | "tapToPay", cloud: boolean) => void;
+/** MOCK ONLY: the dataset's `declines.customTableWrites` switch, refusing with the till's text (kaching `customTables.ts:131,291`). */
+export declare const assertMockCustomTableWriteNotDeclined: (tableName: string) => void;
 export declare const mockPublishEvent: (topic: string, eventType: string, data: any) => void;
 export declare const mockSubscribeToTopic: (topic: string, callback: MockEventCallback) => void;
 export declare const createOrderFromCart: (paymentType: string, amount: number, processor?: string) => CFActiveOrder;

package/dist/demo/database.js

@@ -4,7 +4,7 @@
  */
 import { CFProductType, CFUserTypes, CurrencyCode, } from '../CommonTypes';
 import { cheapestCompositeItem, cheapestCompositePrice, extendPrice, resolveUnit, toBase, } from '@final-commerce/common';
-import { BookingRatePeriod, BookingResourceKind, BookingType, ReservationStatus } from '@final-commerce/common';
+import { BookingRatePeriod, BookingResourceKind, ReservationStatus } from '@final-commerce/common';
 export * from './mocks';
 // Asset Imports - Using Remote URLs to avoid build complexity with asset copying
 const ASSETS_BASE_URL = 'https://raw.githubusercontent.com/Final-Commerce/command-frame/refs/heads/main/src/demo/assets';
@@ -1006,6 +1006,8 @@ export function setMockDatabase(config) {
     if (config.catalogVisibility !== undefined) {
         MOCK_CATALOG_VISIBILITY.splice(0, MOCK_CATALOG_VISIBILITY.length, ...config.catalogVisibility);
     }
+    if (config.declines !== undefined)
+        MOCK_DECLINES = config.declines;
     if (MOCK_OUTLETS.length > 0) {
         Object.assign(MOCK_OUTLET_MAIN, MOCK_OUTLETS[0]);
         if (MOCK_OUTLET_MAIN.id === undefined && MOCK_OUTLET_MAIN._id !== undefined) {
@@ -1028,6 +1030,21 @@ export const safeSerialize = (data) => {
     return JSON.parse(JSON.stringify(data));
 };
 const mockTopicSubscribers = {};
+export let MOCK_DECLINES = {};
+/** MOCK ONLY: the dataset's `declines.payments` switch, failing with the till processor's text (kaching `dispatchPay.ts:208-220`). */
+export const assertMockPaymentNotDeclined = (paymentType, cloud) => {
+    if (!MOCK_DECLINES.payments?.includes(paymentType))
+        return;
+    console.warn(`[Mock] ${paymentType}Payment declined — the mock dataset sets declines.payments`);
+    throw new Error(`${cloud ? 'CLOUD_PAYMENT_FAILED' : 'NATIVE_PAYMENT_FAILED'}: Card declined`);
+};
+/** MOCK ONLY: the dataset's `declines.customTableWrites` switch, refusing with the till's text (kaching `customTables.ts:131,291`). */
+export const assertMockCustomTableWriteNotDeclined = (tableName) => {
+    if (!MOCK_DECLINES.customTableWrites)
+        return;
+    console.warn('[Mock] custom table write refused — the mock dataset sets declines.customTableWrites');
+    throw new Error(`Table "${tableName}" not found`);
+};
 export const mockPublishEvent = (topic, eventType, data) => {
     const subscribers = mockTopicSubscribers[topic] || [];
     const event = {
@@ -1338,7 +1355,6 @@ export const mockBookingAvailability = (productId, from, to, resourceId) => {
     return {
         productId,
         bookingRulesId: MOCK_BOOKING_RULES_ID,
-        bookingType: BookingType.APPOINTMENT,
         ratePeriod: BookingRatePeriod.SLOT,
         slots,
         timeZone: MOCK_SHOP_TIME_ZONE,

package/dist/demo/mocks/custom-tables.d.ts

@@ -10,5 +10,8 @@ export interface CustomTableDataRow {
     createdAt: string;
     updatedAt: string;
 }
-export declare const MOCK_CUSTOM_TABLE_DATA: Record<string, CustomTableDataRow[]>;
+/** Rows by table name — what getCustomTableData reads and upsertCustomTableData writes. */
+export declare const MOCK_CUSTOM_TABLE_DATA: Record<string, (Record<string, unknown> & {
+    _id: string;
+})[]>;
 export declare const MOCK_CUSTOM_EXTENSIONS: CustomExtension[];