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

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/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', {});
@@ -973,11 +985,33 @@ 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 },
 ];
+/**
+ * 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 +1034,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 +1055,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 +1080,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 +1093,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.8.0-staging.1",
+  "version": "0.8.0-staging.2",
   "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-staging.2"
   },
   "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"
 }