@final-commerce/command-frame 0.8.0-staging.1 → 0.8.0

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

@@ -5,24 +5,41 @@ export const mockAddBookingToCart = async (params) => {
     // One call, two effects — the window is claimed AND the service is in the cart. The claim goes
     // first and its refusal propagates: a cart line for a window somebody else took is worse than
     // no line at all.
-    const { booking } = await mockHoldBooking(params);
+    const held = await mockHoldBooking(params);
+    if (!held.success || !held.booking) {
+        return { success: false, reason: held.reason, timestamp: new Date().toISOString() };
+    }
+    const booking = held.booking;
+    // An unknown product used to be sold as "Booking" at zero. The host refuses it, and a mock that
+    // quietly sells something no catalogue contains teaches a screen a case that cannot happen.
     const product = MOCK_PRODUCTS.find(({ _id }) => _id === params.productId);
+    if (!product) {
+        return { success: false, reason: `No product ${params.productId}`, timestamp: new Date().toISOString() };
+    }
+    // A named variant is honoured or refused, never substituted — the host does the same.
     const variant = params.variantId
-        ? product?.variants?.find(({ _id }) => _id === params.variantId)
-        : product?.variants?.[0];
-    const price = variant?.price ?? product?.minPrice ?? 0;
+        ? product.variants?.find(({ _id }) => _id === params.variantId)
+        : product.variants?.[0];
+    if (params.variantId && !variant) {
+        return {
+            success: false,
+            reason: `${product.name} has no variant ${params.variantId}`,
+            timestamp: new Date().toISOString(),
+        };
+    }
+    const price = variant?.price ?? product.minPrice ?? 0;
     const reservation = {
         internalId: `res_${booking.id}`,
         bookingId: booking.id,
         productId: params.productId,
         variantId: variant?._id ?? null,
         resourceId: params.resourceId,
-        name: product?.name ?? 'Booking',
+        name: product.name,
         resourceName: booking.resourceName,
         price,
         quantity: 1,
         total: price,
-        taxTableId: product?.taxTable,
+        taxTableId: product.taxTable,
         startAt: booking.startAt,
         endAt: booking.endAt,
         bufferEndAt: booking.bufferEndAt,
@@ -37,6 +54,13 @@ export const mockAddBookingToCart = async (params) => {
     MOCK_CART.remainingBalance = MOCK_CART.total;
     // The cart topic, not the bookings one: a screen that only watches bookings still has to
     // repaint its cart, and every other cart mutation announces itself the same way.
-    mockPublishEvent('cart', 'reservation-added', { reservation });
-    return { booking, reservationInternalId: reservation.internalId, timestamp: new Date().toISOString() };
+    // `cart-created`, as the host publishes: the cart topic carries the whole cart, and a screen
+    // written against the host's event was not listening for a name only the mock used.
+    mockPublishEvent('cart', 'cart-created', { cart: MOCK_CART });
+    return {
+        success: true,
+        booking,
+        reservationInternalId: reservation.internalId,
+        timestamp: new Date().toISOString(),
+    };
 };

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

@@ -14,10 +14,14 @@ export interface AddBookingToCartParams {
     customerId?: string;
 }
 export interface AddBookingToCartResponse {
+    /** False when the command was refused — a taken window, a rule, a booking that is not yours. */
+    success: boolean;
+    /** Why it was refused, in words a cashier can act on. Absent on success. */
+    reason?: string;
     /** The claim the cart now stands on: `id` cancels or releases it, `expiresAt` is your clock. */
-    booking: CFBooking;
+    booking?: CFBooking;
     /** Identity of the reservation inside the cart and, later, the order. */
-    reservationInternalId: string;
+    reservationInternalId?: string;
     timestamp: string;
 }
 export type AddBookingToCart = (params: AddBookingToCartParams) => Promise<AddBookingToCartResponse>;

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

@@ -1,10 +1,31 @@
-import { MOCK_BOOKINGS } from '../../demo/database';
+import { MOCK_BOOKINGS, MOCK_CART, mockPublishEvent } from '../../demo/database';
 import { ReservationStatus } from '@final-commerce/common';
 export const mockCancelBooking = async (params) => {
     console.log('[Mock] cancelBooking called', params);
     const booking = MOCK_BOOKINGS.find(({ id }) => id === params.bookingId);
-    if (!booking)
-        throw new Error(`No booking ${params.bookingId}`);
+    if (!booking) {
+        return { success: false, reason: `No booking ${params.bookingId}`, timestamp: new Date().toISOString() };
+    }
+    // A paid booking is not cancellable: the window would be freed while the money stays taken.
+    if (booking.status === ReservationStatus.CONFIRMED && booking.orderId) {
+        return {
+            success: false,
+            reason: `That booking is paid for on order ${booking.orderId} — refund the service instead`,
+            timestamp: new Date().toISOString(),
+        };
+    }
     booking.status = ReservationStatus.CANCELLED;
-    return { booking, timestamp: new Date().toISOString() };
+    // A window given away may be the one an open cart is selling, so the cart follows — the host
+    // does this, and a mock that left the line behind sold time that had just been released.
+    const index = (MOCK_CART.reservations ?? []).findIndex((entry) => entry.bookingId === params.bookingId);
+    if (index >= 0) {
+        const [removed] = MOCK_CART.reservations.splice(index, 1);
+        const line = removed.total || removed.price * (removed.quantity ?? 1);
+        MOCK_CART.subtotal -= line;
+        MOCK_CART.total -= line;
+        MOCK_CART.amountToBeCharged = MOCK_CART.total;
+        MOCK_CART.remainingBalance = MOCK_CART.total;
+        mockPublishEvent('cart', 'cart-created', { cart: MOCK_CART });
+    }
+    return { success: true, booking, timestamp: new Date().toISOString() };
 };

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

@@ -4,7 +4,11 @@ export interface CancelBookingParams {
     bookingId: string;
 }
 export interface CancelBookingResponse {
-    booking: CFBooking;
+    /** False when the command was refused — a taken window, a rule, a booking that is not yours. */
+    success: boolean;
+    /** Why it was refused, in words a cashier can act on. Absent on success. */
+    reason?: string;
+    booking?: CFBooking;
     timestamp: string;
 }
 export type CancelBooking = (params: CancelBookingParams) => Promise<CancelBookingResponse>;

package/dist/actions/get-booking-availability/mock.js

@@ -1,6 +1,12 @@
 import { mockBookingAvailability } from '../../demo/database';
 export const mockGetBookingAvailability = async (params) => {
     console.log('[Mock] getBookingAvailability called', params);
-    const availability = mockBookingAvailability(params.productId, new Date(params.from), new Date(params.to), params.resourceId);
-    return { availability, timestamp: new Date().toISOString() };
+    // `fromDay` + `days` is the shape a calendar actually asks in; the mock resolves it on the
+    // machine's clock, which is the only one it has.
+    const start = params.fromDay ? new Date(`${params.fromDay}T00:00:00`) : params.from ? new Date(params.from) : new Date();
+    const end = params.to
+        ? new Date(params.to)
+        : new Date(start.getFullYear(), start.getMonth(), start.getDate() + Math.max(1, params.days ?? 1));
+    const availability = mockBookingAvailability(params.productId, start, end, params.resourceId);
+    return { success: true, availability, timestamp: new Date().toISOString() };
 };

package/dist/actions/get-booking-availability/types.d.ts

@@ -2,17 +2,36 @@ import { CFBookingAvailability } from '../../CommonTypes';
 export interface GetBookingAvailabilityParams {
     /** The bookable product (`productType: 'booking'`) whose calendar you are drawing. */
     productId: string;
-    /** Range start, ISO 8601. */
-    from: string;
-    /** Range end, ISO 8601. */
-    to: string;
+    /**
+     * Range start, ISO 8601. Optional when `fromDay` is given.
+     *
+     * Prefer `fromDay`: a calendar asks about DAYS, and turning "this day at this shop" into two
+     * instants needs the shop's zone — which the host has and the caller has to go and find. A
+     * caller that widened the range by a day at each end and filtered the answer afterwards was
+     * working around the absence of `fromDay`.
+     */
+    from?: string;
+    /** Range end, ISO 8601. Optional when `fromDay` is given. */
+    to?: string;
+    /**
+     * First shop day to cover, `YYYY-MM-DD`. Resolved to local midnight in the shop's own zone,
+     * so a day that is 23 or 25 hours long because the clocks moved is still exactly one day.
+     * Omit both this and `from`/`to` to get today at the shop.
+     */
+    fromDay?: string;
+    /** How many shop days from `fromDay`. Default 1. */
+    days?: number;
     /** Narrow the answer to one resource — "only Marco", "only room 4". */
     resourceId?: string;
     /** Narrow to the resources standing at one outlet. */
     outletId?: string;
 }
 export interface GetBookingAvailabilityResponse {
-    availability: CFBookingAvailability;
+    /** False when the command was refused — a taken window, a rule, a booking that is not yours. */
+    success: boolean;
+    /** Why it was refused, in words a cashier can act on. Absent on success. */
+    reason?: string;
+    availability?: CFBookingAvailability;
     timestamp: string;
 }
 export type GetBookingAvailability = (params: GetBookingAvailabilityParams) => Promise<GetBookingAvailabilityResponse>;

package/dist/actions/get-booking-resources/mock.js

@@ -3,5 +3,5 @@ export const mockGetBookingResources = async (params) => {
     console.log('[Mock] getBookingResources called', params);
     // A resource knows nothing about outlets — where it works lives in its own records, which the
     // host reads. The mock has no such records, so `outletId` narrows nothing here.
-    return { resources: MOCK_BOOKING_RESOURCES, timestamp: new Date().toISOString() };
+    return { success: true, resources: MOCK_BOOKING_RESOURCES, timestamp: new Date().toISOString() };
 };

package/dist/actions/get-booking-resources/types.d.ts

@@ -6,7 +6,11 @@ export interface GetBookingResourcesParams {
     outletId?: string;
 }
 export interface GetBookingResourcesResponse {
-    resources: CFBookingResource[];
+    /** False when the command was refused — a taken window, a rule, a booking that is not yours. */
+    success: boolean;
+    /** Why it was refused, in words a cashier can act on. Absent on success. */
+    reason?: string;
+    resources?: CFBookingResource[];
     timestamp: string;
 }
 export type GetBookingResources = (params?: GetBookingResourcesParams) => Promise<GetBookingResourcesResponse>;

package/dist/actions/get-bookings/mock.js

@@ -16,5 +16,5 @@ export const mockGetBookings = async (params) => {
         const to = new Date(params.to);
         bookings = bookings.filter((entry) => new Date(entry.startAt) < to);
     }
-    return { bookings, timestamp: new Date().toISOString() };
+    return { success: true, bookings, timestamp: new Date().toISOString() };
 };

package/dist/actions/get-bookings/types.d.ts

@@ -12,7 +12,11 @@ export interface GetBookingsParams {
     includeExpired?: boolean;
 }
 export interface GetBookingsResponse {
-    bookings: CFBooking[];
+    /** False when the command was refused — a taken window, a rule, a booking that is not yours. */
+    success: boolean;
+    /** Why it was refused, in words a cashier can act on. Absent on success. */
+    reason?: string;
+    bookings?: CFBooking[];
     timestamp: string;
 }
 export type GetBookings = (params?: GetBookingsParams) => Promise<GetBookingsResponse>;

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

@@ -79,6 +79,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 +181,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/hold-booking/mock.js

@@ -2,6 +2,7 @@ import { MOCK_BOOKINGS, MOCK_BOOKING_RESOURCES, mockLiveBookings } from '../../d
 import { ReservationStatus } from '@final-commerce/common';
 const BUFFER_MINUTES = 5;
 const HOLD_MINUTES = 10;
+let held = 0;
 export const mockHoldBooking = async (params) => {
     console.log('[Mock] holdBooking called', params);
     const startAt = new Date(params.startAt);
@@ -12,10 +13,13 @@ export const mockHoldBooking = async (params) => {
     const clash = mockLiveBookings().some((entry) => entry.resourceId === params.resourceId &&
         new Date(entry.startAt) < bufferEndAt &&
         new Date(entry.bufferEndAt) > startAt);
-    if (clash)
-        throw new Error('That window has just been taken — pick another slot.');
+    if (clash) {
+        return { success: false, reason: 'That window has just been taken — pick another slot.', timestamp: new Date().toISOString() };
+    }
     const booking = {
-        id: `bk_mock_${Date.now()}`,
+        // 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,
         variantId: params.variantId,
@@ -29,5 +33,5 @@ export const mockHoldBooking = async (params) => {
     };
     // Held in the same list availability reads, so the slot really does disappear.
     MOCK_BOOKINGS.push(booking);
-    return { booking, timestamp: new Date().toISOString() };
+    return { success: true, booking, timestamp: new Date().toISOString() };
 };

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

@@ -7,7 +7,7 @@ export interface HoldBookingParams {
     startAt: string;
     /**
      * End of the window — the `endAt` of the slot you picked, or of the last slot in a stay.
-     * Required: the server refuses a window it cannot line up with its own grid, and the till
+     * 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.
      */
     endAt: string;
@@ -17,8 +17,12 @@ export interface HoldBookingParams {
     customerId?: string;
 }
 export interface HoldBookingResponse {
+    /** False when the command was refused — a taken window, a rule, a booking that is not yours. */
+    success: boolean;
+    /** Why it was refused, in words a cashier can act on. Absent on success. */
+    reason?: string;
     /** The claim. `expiresAt` says how long it survives unpaid; `id` is what you confirm or cancel. */
-    booking: CFBooking;
+    booking?: CFBooking;
     timestamp: string;
 }
 export type HoldBooking = (params: HoldBookingParams) => Promise<HoldBookingResponse>;

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

@@ -1,3 +1,4 @@
+import { ReservationStatus } from '@final-commerce/common';
 import { MOCK_BOOKINGS, MOCK_CART, mockPublishEvent } from '../../demo/database';
 export const mockRemoveBookingFromCart = async (params) => {
     console.log('[Mock] removeBookingFromCart called', params);
@@ -10,15 +11,28 @@ export const mockRemoveBookingFromCart = async (params) => {
         MOCK_CART.total -= line;
         MOCK_CART.amountToBeCharged = MOCK_CART.total;
         MOCK_CART.remainingBalance = MOCK_CART.total;
-        mockPublishEvent('cart', 'reservation-removed', { reservation: removed });
+        mockPublishEvent('cart', 'cart-created', { cart: MOCK_CART });
     }
     // The hold has to go back, or the mock is a trap: `addBookingToCart` pushes into the very list
     // availability reads, so add → remove → add the same slot used to refuse forever with "that
     // window has just been taken". The reservation id is `res_<booking.id>`, the link back to the row.
     const bookingId = removed?.bookingId ?? params.reservationInternalId.replace(/^res_/, '');
-    const index = MOCK_BOOKINGS.findIndex(({ id }) => id === bookingId);
-    const [released] = index >= 0 ? MOCK_BOOKINGS.splice(index, 1) : [];
+    // CANCELLED, not deleted — the host releases a window by moving the row, and a mock that
+    // erased it hid both the trail and the fact that a released booking is still a booking.
+    const released = MOCK_BOOKINGS.find(({ id }) => id === bookingId);
+    if (released)
+        released.status = ReservationStatus.CANCELLED;
+    // An id the cart does not have is a refusal, as it is on the host — resolving with an empty
+    // booking made a failed remove look like a successful one.
+    if (!removed) {
+        return {
+            success: false,
+            reason: `Reservation ${params.reservationInternalId} is not in the cart`,
+            timestamp: new Date().toISOString(),
+        };
+    }
     return {
+        success: true,
         reservationInternalId: params.reservationInternalId,
         booking: released,
         timestamp: new Date().toISOString(),

package/dist/actions/remove-booking-from-cart/types.d.ts

@@ -4,7 +4,11 @@ export interface RemoveBookingFromCartParams {
     reservationInternalId: string;
 }
 export interface RemoveBookingFromCartResponse {
-    reservationInternalId: string;
+    /** False when the command was refused — a taken window, a rule, a booking that is not yours. */
+    success: boolean;
+    /** Why it was refused, in words a cashier can act on. Absent on success. */
+    reason?: string;
+    reservationInternalId?: string;
     /** The released hold, so the caller can see it is no longer held. */
     booking?: CFBooking;
     timestamp: string;

package/dist/demo/database.d.ts

@@ -94,6 +94,12 @@ export declare const createOrderFromCart: (paymentType: string, amount: number,
 export declare const applyMockPayment: (amount: number, paymentType: string, processor?: string) => CFActiveOrder | null;
 export declare const MOCK_BOOKING_RULES_ID = "rule_salon_30";
 export declare const MOCK_BOOKING_RESOURCES: CFBookingResource[];
+/**
+ * The clock this mock shop keeps — the same one `getContext` reports. They used to disagree: the
+ * slot hours were built with `setHours`, which is the MACHINE's clock, while the context claimed
+ * Vancouver. On a machine in Paris a correct screen showed a salon open from midnight to nine.
+ */
+export declare const MOCK_SHOP_TIME_ZONE = "America/Vancouver";
 export declare const MOCK_BOOKINGS: CFBooking[];
 /** Live = confirmed, or held and not yet expired. An expired hold occupies nothing. */
 export declare const mockLiveBookings: () => CFBooking[];

package/dist/demo/database.js

@@ -928,6 +928,18 @@ export const createOrderFromCart = (paymentType, amount, processor = 'cash') =>
         createdAt: new Date().toISOString(),
     };
     MOCK_ORDERS.push(newOrder);
+    // Payment is what turns a held window into a kept appointment, so the ROW moves too — the
+    // comment above said CONFIRMED while nothing set it. Left held, a paid appointment dropped out
+    // of `getBookings` when its deadline passed and the window could be taken again, which is the
+    // one transition a booking screen most needs to be able to test.
+    for (const reservation of newOrder.reservations ?? []) {
+        const row = MOCK_BOOKINGS.find(({ id }) => id === reservation.bookingId);
+        if (row) {
+            row.status = ReservationStatus.CONFIRMED;
+            row.orderId = newOrder._id;
+            row.expiresAt = undefined;
+        }
+    }
     resetMockCart();
     // Publish cart-created event after cart is reset (simulates new empty cart)
     mockPublishEvent('cart', 'cart-created', {});
@@ -970,14 +982,38 @@ const CLOSE_HOUR = 18;
 // Rooms, not people: a resource is whatever is scarce, and a room is the case that
 // reads the same in every vertical a dataset might describe.
 export const MOCK_BOOKING_RESOURCES = [
-    { id: 'res_room_1', name: 'Room 1', kind: BookingResourceKind.ROOM },
-    { id: 'res_room_2', name: 'Room 2', kind: BookingResourceKind.ROOM },
+    // Two different photos, from the assets this demo already ships: a screen that picks a
+    // resource by sight has to be fed two that look apart, not one repeated.
+    { id: 'res_room_1', name: 'Room 1', kind: BookingResourceKind.ROOM, image: beetImg },
+    { id: 'res_room_2', name: 'Room 2', kind: BookingResourceKind.ROOM, image: roastedTomatoImg },
 ];
+/**
+ * The clock this mock shop keeps — the same one `getContext` reports. They used to disagree: the
+ * slot hours were built with `setHours`, which is the MACHINE's clock, while the context claimed
+ * Vancouver. On a machine in Paris a correct screen showed a salon open from midnight to nine.
+ */
+export const MOCK_SHOP_TIME_ZONE = 'America/Vancouver';
 const at = (dayOffset, hour, minute = 0) => {
-    const date = new Date();
-    date.setDate(date.getDate() + dayOffset);
-    date.setHours(hour, minute, 0, 0);
-    return date;
+    // The shop's wall clock, not this machine's. Two passes, because the offset is a function of
+    // the instant and the instant is what we are solving for.
+    const naive = Date.UTC(new Date().getUTCFullYear(), new Date().getUTCMonth(), new Date().getUTCDate() + dayOffset, hour, minute);
+    const offsetAt = (instant) => {
+        const parts = {};
+        for (const part of new Intl.DateTimeFormat('en-US', {
+            timeZone: MOCK_SHOP_TIME_ZONE,
+            hour12: false,
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+        }).formatToParts(new Date(instant))) {
+            parts[part.type] = part.value;
+        }
+        const asUtc = Date.UTC(Number(parts.year), Number(parts.month) - 1, Number(parts.day), Number(parts.hour) % 24, Number(parts.minute));
+        return asUtc - instant;
+    };
+    return new Date(naive - offsetAt(naive - offsetAt(naive)));
 };
 const booking = (id, resourceId, start, status, customerName) => ({
     id,
@@ -1000,6 +1036,19 @@ export const MOCK_BOOKINGS = [
 export const mockLiveBookings = () => MOCK_BOOKINGS.filter(({ status, expiresAt }) => status === ReservationStatus.CONFIRMED ||
     (status === ReservationStatus.HELD && (!expiresAt || new Date(expiresAt) > new Date())));
 const takenBy = (resourceId, startAt, bufferEndAt) => mockLiveBookings().some((entry) => entry.resourceId === resourceId && new Date(entry.startAt) < bufferEndAt && new Date(entry.bufferEndAt) > startAt);
+/** The mock's shop day for an instant, `YYYY-MM-DD`, built from parts so it never reads as D/M/Y. */
+const shopDayOf = (instant) => {
+    const parts = {};
+    for (const part of new Intl.DateTimeFormat('en-CA', {
+        timeZone: MOCK_SHOP_TIME_ZONE,
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).formatToParts(instant)) {
+        parts[part.type] = part.value;
+    }
+    return `${parts.year}-${parts.month}-${parts.day}`;
+};
 export const mockBookingAvailability = (productId, from, to, resourceId) => {
     const serving = resourceId
         ? MOCK_BOOKING_RESOURCES.filter((resource) => resource.id === resourceId)
@@ -1008,9 +1057,12 @@ export const mockBookingAvailability = (productId, from, to, resourceId) => {
     const step = (SLOT_MINUTES + BUFFER_MINUTES) * 60000;
     for (let day = 0; day < 14; day += 1) {
         const open = at(day, OPEN_HOUR);
-        if (open < from || open > to)
-            continue;
         const close = at(day, CLOSE_HOUR);
+        // Overlap, not containment. Asking from noon used to return nothing for today, because the
+        // day's opening hour lay before the range start — so an afternoon question got an empty
+        // calendar and read as "fully booked".
+        if (close <= from || open >= to)
+            continue;
         for (let start = open.getTime(); start + SLOT_MINUTES * 60000 <= close.getTime(); start += step) {
             const startAt = new Date(start);
             const endAt = new Date(start + SLOT_MINUTES * 60000);
@@ -1030,6 +1082,10 @@ export const mockBookingAvailability = (productId, from, to, resourceId) => {
                 booked: resources.reduce((sum, entry) => sum + entry.booked, 0),
                 free: resources.reduce((sum, entry) => sum + entry.free, 0),
                 resources,
+                // The shop day, as the real host stamps it. The mock keeps one shop on the machine's
+                // own clock, so here that is the machine's day — the point is that the FIELD is there,
+                // so a screen built against the mock never learns to work the day out for itself.
+                dayKey: shopDayOf(startAt),
             });
         }
     }
@@ -1039,6 +1095,8 @@ export const mockBookingAvailability = (productId, from, to, resourceId) => {
         bookingType: BookingType.APPOINTMENT,
         ratePeriod: BookingRatePeriod.SLOT,
         slots,
+        timeZone: MOCK_SHOP_TIME_ZONE,
+        days: [...new Set(slots.map((slot) => slot.dayKey))],
     };
 };
 /**

package/dist/index.d.ts

@@ -160,7 +160,7 @@ export type { CalculateRefundTotal, CalculateRefundTotalParams, CalculateRefundT
 export type { GetRemainingRefundableQuantities, GetRemainingRefundableQuantitiesParams, GetRemainingRefundableQuantitiesResponse, } from './actions/get-remaining-refundable-quantities/types';
 export type { ProcessPartialRefund, ProcessPartialRefundParams, ProcessPartialRefundResponse, } from './actions/process-partial-refund/types';
 export type { RedeemRefund, RedeemRefundParams, RedeemRefundResponse } from './actions/redeem-refund/types';
-export type { GetRefundPlan, GetRefundPlanParams, GetRefundPlanResponse, RefundPlanSource, RefundPlanAllocation, RefundPlanLeg, } from './actions/get-refund-plan/types';
+export type { GetRefundPlan, GetRefundPlanParams, GetRefundPlanResponse, RefundPlanSource, RefundPlanAllocation, RefundPlanLeg, RefundPlanRowType, RefundPlanTaxLine, RefundPlanAmounts, RefundPlanRow, RefundPlanSelectedRow, RefundPlanTotals, RefundPlanBreakdown, } from './actions/get-refund-plan/types';
 export type { CheckPermission, CheckPermissionParams, CheckPermissionResponse } from './actions/check-permission/types';
 export type { InitiateRefund, InitiateRefundParams, InitiateRefundResponse } from './actions/initiate-refund/types';
 export type { GetCurrentCart, GetCurrentCartResponse } from './actions/get-current-cart/types';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.8.0-staging.1",
+  "version": "0.8.0",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -57,7 +57,7 @@
     "ignoreBranchesMissingTickets": true
   },
   "dependencies": {
-    "@final-commerce/common": "2.4.0-staging.1"
+    "@final-commerce/common": "2.4.0"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.0.0",
@@ -73,5 +73,8 @@
     "typescript-eslint": "^8.0.0",
     "vitest": "^4.0.0"
   },
+  "overrides": {
+    "js-yaml": "^4.3.2"
+  },
   "prettier": "@final-commerce/common/prettier"
 }