@final-commerce/command-frame 0.12.0 → 0.13.1-preprod.1

package/dist/CommonTypes.d.ts

@@ -1,5 +1,5 @@
 export * from './common-types';
-import type { Tax, Tip, Address, MetadataItem, OrderAssignedUser, OrderInCart, OrderCustomStatus, PosDataItem, CartFeeTaxEntry, CartFeeItem, CartDiscountItem, OrderNote, NonRevenueItem, DiscountDetail, FeeDetail, DiscountLineItem, FeeLineItem, LineItem, TipPayment, RefundedTipPayment, PaymentMethod, Discount, CustomFee, Summary, CustomSale, RefundedCustomSale, RefundItem, RefundedLineItem, ActiveStation, ActiveSession, ActiveOutlet, ActiveUser, ActiveUserRole, ActiveOrder, ActiveCart, ActivePark, ActiveCompany, ActiveCustomSales, ActiveProduct, ActiveCustomer, FullProduct, ProductVariant, Inventory, ResolvedModifier, ResolvedModifierChoice, ModifierSelectionType, ModifierSelection, ModifierChoiceSelection, CartLineModifier, ProdModifierBreakdown, OrderLineItemModifier, CustomerNote, Attribute, AttributeOption, Category, Transaction, ActiveSplitPayment, BookingAvailability, BookingSlot, BookingSlotResource, BookingResource, Booking, CartReservation, OrderReservation, Composite, CompositePart, CompositeItem, CompositeChoice, CompositeItemUnavailable, CompositePick, CartLineComponent, OrderLineItemComponent } from '@final-commerce/common/pos-types';
+import type { Tax, Tip, Address, MetadataItem, OrderAssignedUser, OrderInCart, OrderCustomStatus, PosDataItem, CartFeeTaxEntry, CartFeeItem, CartDiscountItem, OrderNote, NonRevenueItem, DiscountDetail, FeeDetail, DiscountLineItem, FeeLineItem, LineItem, TipPayment, RefundedTipPayment, PaymentMethod, Discount, CustomFee, Summary, CustomSale, RefundedCustomSale, RefundItem, RefundedLineItem, ActiveStation, ActiveSession, ActiveOutlet, ActiveUser, ActiveUserRole, ActiveOrder, ActiveCart, ActivePark, ActiveCompany, ActiveCustomSales, ActiveProduct, ActiveCustomer, FullProduct, ProductVariant, Inventory, ResolvedModifier, ResolvedModifierChoice, ModifierSelectionType, ModifierSelection, ModifierChoiceSelection, CartLineModifier, ProdModifierBreakdown, OrderLineItemModifier, CustomerNote, Attribute, AttributeOption, Category, Transaction, ActiveSplitPayment, BookingAvailability, BookingSlot, BookingSlotResource, BookingResource, Booking, CartReservation, OrderReservation, CartAddress, CartShipping, Composite, CompositePart, CompositeItem, CompositeChoice, CompositeItemUnavailable, CompositePick, CartLineComponent, OrderLineItemComponent } from '@final-commerce/common/pos-types';
 export { CurrencyCode, ProductType as CFProductType, UserTypes as CFUserTypes } from '@final-commerce/common';
 /** Open record used as a base for active entities. */
 export type CFActiveEntity = Record<string, unknown>;
@@ -108,6 +108,8 @@ export type CFActiveOrder = ActiveOrder;
 export type CFActiveCustomSales = ActiveCustomSales;
 export type CFNonRevenueItem = NonRevenueItem;
 export type CFActiveCart = ActiveCart;
+export type CFCartAddress = CartAddress;
+export type CFCartShipping = CartShipping;
 export type CFActivePark = ActivePark;
 export type CFActiveCompany = ActiveCompany;
 /** Tile kinds a SmartGrid cell can represent. Mirrors common's `BaseTile['type']`. */
@@ -150,6 +152,7 @@ export interface CFActiveRefundDetails {
     buttonsDisabled?: Record<string, boolean>;
     isRefund?: boolean;
     customSalesQuantities?: Record<string, number>;
+    /** Keyed by cart-fee id, plus the reserved key `'shipping'` for the order's shipping. 0/1 each. */
     cartFeesRefunds?: Record<string, number>;
     tipsRefunds?: Record<string, number>;
     refundProcessingStatus?: CFRefundProcessingStatus | null;
@@ -217,9 +220,23 @@ export interface CFOutletInfo {
         state?: string;
         postCode?: string;
     };
+    address2?: string;
     city?: string;
     state?: string;
     country?: string;
+    postCode?: string;
+    phone?: string;
+    /** Short display alias, when the merchant set one (e.g. `DTWN`). */
+    alias?: string;
+    /**
+     * Whether this location can take an ONLINE payment. Storefront only — it is
+     * absent on a register, where it has no meaning.
+     *
+     * `false` means the outlet has no completed payment connection, so starting a
+     * checkout against it WILL fail. A pickup picker must not offer it as a
+     * selectable location, or must show it as unavailable.
+     */
+    connected?: boolean;
 }
 export interface CFContextManage {
     user: unknown;

package/dist/actions/assign-order-user/mock.js

@@ -1,3 +1,4 @@
+import { applyAssignment } from '@final-commerce/common';
 import { MOCK_ORDERS, MOCK_PARKED_ORDERS, MOCK_USERS, mockPublishEvent } from '../../demo/database';
 export const mockAssignOrderUser = async (params) => {
     console.log('[Mock] assignOrderUser called', params);
@@ -11,20 +12,19 @@ export const mockAssignOrderUser = async (params) => {
     if (!order) {
         throw new Error(`Order with ID ${params.orderId} not found`);
     }
-    if (params.userId === null) {
-        order.assignedUser = null;
-    }
-    else if (order.assignedUser?.userId !== params.userId) {
-        if (!MOCK_USERS.some((u) => u.id === params.userId)) {
-            throw new Error(`User with ID ${params.userId} not found`);
-        }
-        order.assignedUser = { userId: params.userId, assignedAt: new Date().toISOString() };
+    if (params.userId !== null && !MOCK_USERS.some((u) => u.id === params.userId)) {
+        throw new Error(`User with ID ${params.userId} not found`);
     }
+    order.assignedUser = applyAssignment(order, {
+        userId: params.userId,
+        label: params.label,
+        at: new Date().toISOString(),
+    });
     mockPublishEvent('orders', 'order-updated', { order });
     return {
         success: true,
         orderId: order._id,
-        assignedUser: order.assignedUser ?? null,
+        assignedUser: order.assignedUser,
         timestamp: new Date().toISOString(),
     };
 };

package/dist/actions/assign-order-user/types.d.ts

@@ -2,14 +2,25 @@ import type { CFOrderAssignedUser } from '../../CommonTypes';
 export interface AssignOrderUserParams {
     /** Order to assign. Omit to target the live cart's order — it must already exist (parked, paid or transitioned). */
     orderId?: string;
-    /** User to assign (e.g. the driver), or null to unassign. Replaces any current assignee. */
+    /**
+     * User to assign (e.g. the driver), or null to unassign. Assigning replaces the current
+     * assignee with the same `label`; the replaced one stays in the order's record, ended.
+     */
     userId: string | null;
+    /**
+     * Why the user is assigned, free text — e.g. 'delivery'. Omit for an unlabeled assignment.
+     * When unassigning, ends only this label's assignee; omit it to end every current assignment.
+     */
+    label?: string | null;
 }
 export interface AssignOrderUserResponse {
     success: boolean;
     orderId: string;
-    /** The order's assignee after the call; null when unassigned. */
-    assignedUser: CFOrderAssignedUser | null;
+    /**
+     * Everyone who has had the order after the call, oldest first. Entries without
+     * `unassignedAt` are the current assignees.
+     */
+    assignedUser: CFOrderAssignedUser[];
     timestamp: string;
 }
 export type AssignOrderUser = (params: AssignOrderUserParams) => Promise<AssignOrderUserResponse>;

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

@@ -0,0 +1,6 @@
+/**
+ * Attach Checkout Contact action
+ * Calls the attachCheckoutContact action on the parent window
+ */
+import type { AttachCheckoutContact } from './types';
+export declare const attachCheckoutContact: AttachCheckoutContact;

package/dist/actions/attach-checkout-contact/action.js

@@ -0,0 +1,8 @@
+/**
+ * Attach Checkout Contact action
+ * Calls the attachCheckoutContact action on the parent window
+ */
+import { commandFrameClient } from '../../client';
+export const attachCheckoutContact = async (params) => {
+    return await commandFrameClient.call('attachCheckoutContact', params);
+};

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

@@ -0,0 +1,15 @@
+import type { AttachCheckoutContact } from './types';
+/**
+ * Standalone mock of attaching contact to an online order.
+ *
+ * It mirrors the one REFUSAL the real command makes — a missing email — because
+ * that is the mistake a builder actually hits, and a mock that accepted anything
+ * would let a checkout screen look finished and lose receipts on the published
+ * site.
+ *
+ * It does NOT mirror "no order to attach to". The real command answers
+ * `attached: false` there rather than throwing, precisely so a flow can call it
+ * optimistically and still let the shopper pay; the mock always has a checkout
+ * to attach to, so it reports `true`.
+ */
+export declare const mockAttachCheckoutContact: AttachCheckoutContact;

package/dist/actions/attach-checkout-contact/mock.js

@@ -0,0 +1,22 @@
+/**
+ * Standalone mock of attaching contact to an online order.
+ *
+ * It mirrors the one REFUSAL the real command makes — a missing email — because
+ * that is the mistake a builder actually hits, and a mock that accepted anything
+ * would let a checkout screen look finished and lose receipts on the published
+ * site.
+ *
+ * It does NOT mirror "no order to attach to". The real command answers
+ * `attached: false` there rather than throwing, precisely so a flow can call it
+ * optimistically and still let the shopper pay; the mock always has a checkout
+ * to attach to, so it reports `true`.
+ */
+export const mockAttachCheckoutContact = async (params) => {
+    console.log('[Mock] attachCheckoutContact called', params);
+    if (!params)
+        throw new Error('Params required');
+    if (!params.email || !params.email.trim()) {
+        throw new Error('attachCheckoutContact: email is required — it is where the receipt goes');
+    }
+    return { attached: true, timestamp: new Date().toISOString() };
+};

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

@@ -0,0 +1,35 @@
+/**
+ * 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;
+    name?: string;
+    phone?: string;
+    /** Defaults to the outlet the storefront booted against. */
+    outletId?: string;
+}
+export interface AttachCheckoutContactResponse {
+    /**
+     * `false` means there was nothing to attach to — no checkout had been started
+     * for this cart. It is NOT a failure to record the contact on an order that
+     * exists, and it never means the shopper was charged.
+     */
+    attached: boolean;
+    timestamp: string;
+}
+/**
+ * Put the shopper's contact on the order `startCheckout` already created.
+ *
+ * Call it BEFORE paying, whenever the email is known — on blur, on submit, or
+ * as the shopper leaves the contact step. It reuses the order's idempotency
+ * key, so it updates that order rather than creating a second one.
+ *
+ * SAFE TO CALL TWICE. The server only ever ADDS contact to an order that has
+ * none, so a later call cannot redirect a receipt that was already addressed.
+ *
+ * NEVER THROWS FOR A MISSING ORDER. Failing to record an email must not stop a
+ * payment the shopper is trying to make, so the caller gets `attached: false`
+ * and can carry on to pay.
+ */
+export type AttachCheckoutContact = (params: AttachCheckoutContactParams) => Promise<AttachCheckoutContactResponse>;

package/dist/actions/attach-checkout-contact/types.js

@@ -0,0 +1,16 @@
+// Attach Checkout Contact Types
+//
+// The second half of the online checkout. `startCheckout` creates the order and
+// mounts the payment fields the moment a shopper ARRIVES; this puts their email
+// on that same order once they have typed it.
+//
+// WHY THESE ARE TWO COMMANDS. The card fields cannot render without a payment
+// session, a session needs a server-priced amount, and an amount needs an order.
+// So the order has to exist before the shopper has typed anything. Demanding an
+// email first is what forced the old "fill the form, then see the card fields"
+// checkout — and it also meant every cart edit minted a NEW order, because the
+// idempotency key moved with the cart.
+//
+// Served ONLY by the storefront runtime (a published website), like
+// `startCheckout` itself. On a register it does not exist.
+export {};

package/dist/actions/get-address-options/action.d.ts

@@ -0,0 +1,6 @@
+/**
+ * GetAddressOptions action
+ * Calls the getAddressOptions action on the parent window
+ */
+import type { GetAddressOptions } from './types';
+export declare const getAddressOptions: GetAddressOptions;

package/dist/actions/get-address-options/action.js

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

package/dist/actions/get-address-options/mock.d.ts

@@ -0,0 +1,3 @@
+import type { GetAddressOptions } from './types';
+/** Standalone mock: the same country and province lists the runtime serves. The demo store is in Canada. */
+export declare const mockGetAddressOptions: GetAddressOptions;

package/dist/actions/get-address-options/mock.js

@@ -0,0 +1,15 @@
+import { CANADA_PROVINCES, listCountries } from '@final-commerce/common';
+/** Standalone mock: the same country and province lists the runtime serves. The demo store is in Canada. */
+export const mockGetAddressOptions = async (params) => {
+    console.log('[Mock] getAddressOptions called', params);
+    const french = params?.locale?.toLowerCase().startsWith('fr') ?? false;
+    const provinces = CANADA_PROVINCES.map((p) => ({ code: p.code, name: french ? p.nameFr : p.name }));
+    return {
+        countries: listCountries(params?.locale ?? 'en').map((c) => ({
+            ...c,
+            provinces: c.code === 'CA' ? provinces : [],
+        })),
+        defaultCountry: 'CA',
+        timestamp: new Date().toISOString(),
+    };
+};

package/dist/actions/get-address-options/types.d.ts

@@ -0,0 +1,25 @@
+export interface AddressProvinceOption {
+    /** Province code, e.g. `QC`. This is what goes in the address's `state`. */
+    code: string;
+    /** In the requested locale where we have it (English or French). */
+    name: string;
+}
+export interface AddressCountryOption {
+    /** ISO 3166-1 alpha-2, e.g. `CA`. This is what goes in the address's `country`. */
+    code: string;
+    name: string;
+    /** Empty when the country has no province list; the form then shows a free text field. */
+    provinces: AddressProvinceOption[];
+}
+export interface GetAddressOptionsParams {
+    /** BCP 47 locale for the names, e.g. `fr-CA`. Defaults to `en`. */
+    locale?: string;
+}
+export interface GetAddressOptionsResponse {
+    /** Sorted by name in the requested locale. */
+    countries: AddressCountryOption[];
+    /** The store's own country, to preselect. Null when it isn't known. */
+    defaultCountry: string | null;
+    timestamp: string;
+}
+export type GetAddressOptions = (params?: GetAddressOptionsParams) => Promise<GetAddressOptionsResponse>;

package/dist/actions/get-address-options/types.js

@@ -0,0 +1,8 @@
+// Get Address Options Types
+//
+// What an address form offers: countries, and the provinces of the countries that
+// have them (Canada today). A flow renders these as dropdowns and keeps no list of
+// its own, so what the shopper picks is always a code the shipping rules match.
+//
+// Served by the till and by the storefront runtime.
+export {};

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

@@ -0,0 +1,6 @@
+/**
+ * Get Checkout Status action
+ * Calls the getCheckoutStatus action on the parent window
+ */
+import type { GetCheckoutStatus } from './types';
+export declare const getCheckoutStatus: GetCheckoutStatus;

package/dist/actions/get-checkout-status/action.js

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

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

@@ -0,0 +1,3 @@
+import { GetCheckoutStatus } from './types';
+/** Standalone mock: every order the preview knows about is already paid. */
+export declare const mockGetCheckoutStatus: GetCheckoutStatus;

package/dist/actions/get-checkout-status/mock.js

@@ -0,0 +1,11 @@
+/** Standalone mock: every order the preview knows about is already paid. */
+export const mockGetCheckoutStatus = async (params) => {
+    console.log('[Mock] getCheckoutStatus called', params);
+    return {
+        success: true,
+        status: 'paid',
+        paid: true,
+        receiptId: params?.receiptId ?? 'ON-001-000001',
+        timestamp: new Date().toISOString(),
+    };
+};

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

@@ -0,0 +1,27 @@
+/** The shopper-facing vocabulary: never the platform's payment / fulfilment states. */
+export type CheckoutOrderStatus = 'awaiting_payment' | 'confirming' | 'payment_failed' | 'paid' | 'fulfilled' | 'partially_refunded' | 'refunded' | 'cancelled';
+/** Why the server cancelled an order the shopper paid for. */
+export type CheckoutCancelReason = 'sold_out';
+export interface GetCheckoutStatusParams {
+    /**
+     * The receipt `startCheckout` returned, to name which order. Omitted: the checkout in flight,
+     * else the last one this tab finished.
+     */
+    receiptId?: string;
+}
+export interface GetCheckoutStatusResponse {
+    success: boolean;
+    /** `null` when this tab placed no such order, or the server could not be asked. */
+    status: CheckoutOrderStatus | null;
+    /** True once the money is in: `paid`, `fulfilled`, or refunded since. */
+    paid: boolean;
+    /**
+     * Why a `cancelled` order was cancelled, when the server cancelled it. `sold_out`: the stock ran out
+     * before the payment was captured, so the payment was released and nothing was charged.
+     */
+    cancelReason?: CheckoutCancelReason;
+    receiptId: string | null;
+    timestamp: string;
+}
+/** Never throws for an unknown order: answers `status: null`. */
+export type GetCheckoutStatus = (params?: GetCheckoutStatusParams) => Promise<GetCheckoutStatusResponse>;

package/dist/actions/get-checkout-status/types.js

@@ -0,0 +1,12 @@
+// Get Checkout Status Types
+//
+// Where an online order stands NOW, as the server holds it. A confirmation page uses it to move
+// from "we're confirming your payment" to "paid" once the payment provider's notification has
+// landed, which the browser alone can never know: it only ever sees that the provider ACCEPTED
+// a payment.
+//
+// The runtime asks about a checkout THIS TAB placed (it keeps the checkout's key), so a page can
+// only ever ask about its own order. No password: the server no longer issues one.
+//
+// Served ONLY by the storefront runtime (a published website). On a register it does not exist.
+export {};

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

@@ -1,3 +1,4 @@
+import { currentAssignees } from '@final-commerce/common';
 import { MOCK_ORDERS, MOCK_PARKED_ORDERS, MOCK_USERS, MOCK_STATIONS, MOCK_OUTLETS, safeSerialize, } from '../../demo/database';
 export const mockGetOrders = async (params) => {
     console.log('[Mock] getOrders called', params);
@@ -5,7 +6,7 @@ export const mockGetOrders = async (params) => {
     let orders = safeSerialize([...MOCK_ORDERS, ...MOCK_PARKED_ORDERS]);
     // Filter simulation
     if (params) {
-        const { customerId, status, sessionId, paymentState, fulfillmentState, outletId, assignedUserId, inCart, orderType, customStatusId, customStatusKey, scheduled, scheduledFrom, scheduledTo, searchValue, limit, offset, sortBy, sortDirection, } = params;
+        const { customerId, status, sessionId, paymentState, fulfillmentState, outletId, assignedUserId, assignedUserLabel, inCart, orderType, customStatusId, customStatusKey, scheduled, scheduledFrom, scheduledTo, searchValue, limit, offset, sortBy, sortDirection, } = params;
         // 1. Filtering
         if (customerId) {
             orders = orders.filter((o) => o.customer && '_id' in o.customer && o.customer._id === customerId);
@@ -27,11 +28,13 @@ export const mockGetOrders = async (params) => {
         if (outletId) {
             orders = orders.filter((o) => o.posData?.outlet === outletId);
         }
-        if (assignedUserId) {
-            orders = orders.filter((o) => o.assignedUser?.userId === assignedUserId);
-        }
-        else if (assignedUserId === null) {
-            orders = orders.filter((o) => o.assignedUser == null);
+        if (assignedUserId || assignedUserId === null || assignedUserLabel !== undefined) {
+            orders = orders.filter((o) => {
+                const holders = currentAssignees(o, assignedUserLabel);
+                if (assignedUserId === null)
+                    return holders.length === 0;
+                return assignedUserId ? holders.some((a) => a.userId === assignedUserId) : holders.length > 0;
+            });
         }
         if (orderType !== undefined) {
             const types = Array.isArray(orderType) ? orderType : [orderType];

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

@@ -11,10 +11,16 @@ export interface GetOrdersParams {
     /** Only orders placed at this outlet (`posData.outlet`). Without it, orders from every outlet in the company are returned. */
     outletId?: string;
     /**
-     * Only orders assigned to this user (`assignedUser.userId`), e.g. a driver's deliveries.
-     * `null`: only orders nobody is assigned to yet (e.g. deliveries awaiting a driver).
+     * Only orders this user is assigned to now (a current `assignedUser` entry), e.g. a driver's deliveries.
+     * `null`: only orders nobody is assigned to now (e.g. deliveries awaiting a driver).
      */
     assignedUserId?: string | null;
+    /**
+     * Narrows the assignee test to assignments with this label, e.g. 'delivery': with `assignedUserId`, that
+     * user must hold the order under this label; with `assignedUserId: null`, nobody holds it under this label;
+     * alone, someone holds it under this label. `null` means unlabeled assignments.
+     */
+    assignedUserLabel?: string | null;
     /**
      * true: only orders loaded in a cart; false: only orders that aren't. Reads `order.inCart` when the order
      * carries it, otherwise the legacy reading (fulfillment 'draft' / status 'in-cart').

package/dist/actions/get-outlets/action.js

@@ -1,4 +1,4 @@
 import { commandFrameClient } from "../../client";
-export const getOutlets = async () => {
-    return await commandFrameClient.call("getOutlets");
+export const getOutlets = async (params) => {
+    return await commandFrameClient.call("getOutlets", params ?? {});
 };

package/dist/actions/get-outlets/mock.d.ts

@@ -1,2 +1,14 @@
 import { GetOutlets } from "./types";
+/**
+ * A second location that CANNOT take an online payment.
+ *
+ * The shared demo data has exactly one outlet, so without this a pickup picker
+ * built against mocks would never render the case that matters: an outlet a
+ * shopper must not be allowed to check out against. `setOutlet` refuses this id,
+ * so the two mocks tell the same story.
+ *
+ * Mock-only, and deliberately NOT added to `MOCK_OUTLETS` — that array is shared
+ * with every other outlet mock and `MOCK_OUTLET`.
+ */
+export declare const MOCK_UNCONNECTED_OUTLET_ID = "outlet-mock-unconnected";
 export declare const mockGetOutlets: GetOutlets;

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

@@ -1,16 +1,40 @@
 import { MOCK_OUTLETS, safeSerialize } from "../../demo/database";
-export const mockGetOutlets = async () => {
-    console.log("[Mock] getOutlets called");
+/**
+ * A second location that CANNOT take an online payment.
+ *
+ * The shared demo data has exactly one outlet, so without this a pickup picker
+ * built against mocks would never render the case that matters: an outlet a
+ * shopper must not be allowed to check out against. `setOutlet` refuses this id,
+ * so the two mocks tell the same story.
+ *
+ * Mock-only, and deliberately NOT added to `MOCK_OUTLETS` — that array is shared
+ * with every other outlet mock and `MOCK_OUTLET`.
+ */
+export const MOCK_UNCONNECTED_OUTLET_ID = "outlet-mock-unconnected";
+const UNCONNECTED_OUTLET = {
+    _id: MOCK_UNCONNECTED_OUTLET_ID,
+    name: "Airport (not connected)",
+    address: "2 Terminal Road",
+    city: "San Francisco",
+    state: "CA",
+    country: "US",
+    postCode: "94128",
+    connected: false
+};
+export const mockGetOutlets = async (params) => {
+    console.log("[Mock] getOutlets called", params);
     const outlets = safeSerialize(MOCK_OUTLETS).map((o) => ({
         _id: o._id || o.id,
         name: o.name || "",
         address: o.address,
         city: o.city,
         state: o.state,
-        country: o.country
+        country: o.country,
+        connected: true
     }));
+    const all = [...outlets, UNCONNECTED_OUTLET];
     return {
-        outlets,
+        outlets: params?.connectedOnly ? all.filter((o) => o.connected) : all,
         timestamp: new Date().toISOString()
     };
 };

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

@@ -1,6 +1,24 @@
 import { CFOutletInfo } from "../../CommonTypes";
+export interface GetOutletsParams {
+    /**
+     * Return only locations that can take an online payment. Storefront only.
+     * Default `false`, so a flow sees every outlet and decides how to present
+     * the ones it cannot sell from.
+     */
+    connectedOnly?: boolean;
+}
 export interface GetOutletsResponse {
     outlets: CFOutletInfo[];
     timestamp: string;
 }
-export type GetOutlets = () => Promise<GetOutletsResponse>;
+/**
+ * List the company's outlets.
+ *
+ * ON A STOREFRONT this is the pickup picker's source. Each outlet carries
+ * `connected`, and an outlet with `connected: false` cannot take a payment, so
+ * `setOutlet` refuses it — filter those out rather than relying on the refusal.
+ *
+ * There are no coordinates on an outlet, so "closest branch" is not something
+ * this can answer; sort on the address fields or let the shopper choose.
+ */
+export type GetOutlets = (params?: GetOutletsParams) => Promise<GetOutletsResponse>;

package/dist/actions/get-product-modifier-selections/mock.js

@@ -13,6 +13,8 @@ export const mockGetProductModifierSelections = async (params) => {
             selections: [],
             rows: [],
             modifiersTotal: 0,
+            lineTotal: 0,
+            unitTotal: 0,
             timestamp: new Date().toISOString(),
         };
     }
@@ -25,18 +27,23 @@ export const mockGetProductModifierSelections = async (params) => {
             selections: [],
             rows: [],
             modifiersTotal: 0,
+            lineTotal: 0,
+            unitTotal: 0,
             timestamp: new Date().toISOString(),
         };
     }
     // The priced rows already sit on the line; extending them by the line quantity is
     // the host's job, not the flow's.
     const { rows, modifiersTotal } = buildModifierRows(line.modifiers, line.quantity);
+    const { modifiersTotal: unitModifiers } = buildModifierRows(line.modifiers, 1);
     return {
         success: true,
         internalId: line.internalId,
         selections: line.modifierSelections ?? [],
         rows,
         modifiersTotal,
+        lineTotal: line.price * line.quantity + modifiersTotal,
+        unitTotal: line.price + unitModifiers,
         timestamp: new Date().toISOString(),
     };
 };

package/dist/actions/get-product-modifier-selections/types.d.ts

@@ -18,6 +18,10 @@ export interface GetProductModifierSelectionsResponse {
     rows: CFProdModifierBreakdown[];
     /** Sum of `rows[].amount` for THIS line, in minor units. */
     modifiersTotal: number;
+    /** The whole line as the cart prices it (item, its discounts, fees and modifiers), in minor units. */
+    lineTotal: number;
+    /** The same for ONE unit, for an "each" price. */
+    unitTotal: number;
     timestamp: string;
 }
 export type GetProductModifierSelections = (params?: GetProductModifierSelectionsParams) => Promise<GetProductModifierSelectionsResponse>;

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

@@ -44,20 +44,20 @@ export interface GetProductsParams {
         externalId?: string;
         /**
          * Product-level flag filter. `true` = only products flagged `notSoldInPos`; `false` = only
-         * products NOT flagged (a missing field counts as not flagged). Naming it switches off the
-         * default `notSoldInPos` exclusion, so `true` works without `includeUnlisted`.
+         * products NOT flagged (a missing field counts as not flagged). On a till, naming it switches off
+         * the default exclusion, so `true` works without `includeUnlisted`.
          */
         notSoldInPos?: boolean;
-        /** Product-level flag filter: `true` = flagged `notSoldOnline`; `false` = sold online (missing counts). */
+        /** Product-level flag filter: `true` = flagged `notSoldOnline`; `false` = sold online (missing counts). On a storefront, naming it switches off the default exclusion. */
         notSoldOnline?: boolean;
         [key: string]: any;
     };
     /**
-     * Products flagged `notSoldInPos` are left out unless this is `true` (default `false`) or the
-     * query names `notSoldInPos`. They still cannot be sold: `addProductToCart` / `addBookingToCart`
-     * refuse a product or a variant flagged `notSoldInPos`. Without it, flagged variants are also
-     * stripped from `variants[]` and a product whose every variant is flagged is left out — whatever
-     * `query.notSoldInPos` says.
+     * The sales-channel flag follows the host channel: `notSoldInPos` on a till, `notSoldOnline` on a
+     * storefront. Products with that flag are left out unless this is `true` (default `false`) or the
+     * query names that flag. They still cannot be sold: `addProductToCart` / `addBookingToCart` refuse a
+     * product or a variant with it. Without it, flagged variants are also stripped from `variants[]`
+     * and a product whose every variant is flagged is left out — whatever the query says.
      */
     includeUnlisted?: boolean;
     /** Defaults to 0. */

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

@@ -96,7 +96,7 @@ export function mockRefundBreakdown(rows, items) {
         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 };
+    const totals = { items: 0, discounts: 0, fees: 0, shipping: 0, tax: 0, tip: 0, total: 0 };
     for (const r of selected) {
         const a = r.amounts;
         if (r.type === 'fee')