@final-commerce/command-frame 0.8.0 → 0.8.1-online.2

package/dist/CommonTypes.d.ts

@@ -181,9 +181,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/add-booking-to-cart/mock.js

@@ -2,14 +2,6 @@ import { MOCK_CART, MOCK_PRODUCTS, mockPublishEvent } from '../../demo/database'
 import { mockHoldBooking } from '../hold-booking/mock';
 export const mockAddBookingToCart = async (params) => {
     console.log('[Mock] addBookingToCart called', 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 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);
@@ -27,6 +19,18 @@ export const mockAddBookingToCart = async (params) => {
             timestamp: new Date().toISOString(),
         };
     }
+    // Same refusal and text as the host (kaching add-booking-to-cart).
+    if (product.notSoldInPos || variant?.notSoldInPos) {
+        return { success: false, reason: `${product.name} is not sold in POS`, timestamp: new Date().toISOString() };
+    }
+    // One call, two effects — the window is claimed AND the service is in the cart. Like the host, the
+    // claim comes after the product checks and before the line; its refusal propagates: a cart line for
+    // a window somebody else took is worse than no line at all.
+    const held = await mockHoldBooking(params);
+    if (!held.success || !held.booking) {
+        return { success: false, reason: held.reason, timestamp: new Date().toISOString() };
+    }
+    const booking = held.booking;
     const price = variant?.price ?? product.minPrice ?? 0;
     const reservation = {
         internalId: `res_${booking.id}`,

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

@@ -21,6 +21,10 @@ export const mockAddProductToCart = async (params) => {
             }
         }
     }
+    // Same refusal and text as the host (kaching add-product-to-cart).
+    if (product.notSoldInPos || variant.notSoldInPos) {
+        throw new Error(`${product.name} is not sold in POS`);
+    }
     // A measured variant carries a resolved unit; the host does the same. What the unit can
     // express is its precision — 1.5 of a kilogram is a sale, 1.5 of a piece is a typo.
     const unit = variant.unitId ? resolveUnit(variant.unitId) : undefined;

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-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-products/mock.js

@@ -11,6 +11,19 @@ export const mockGetProducts = async (params) => {
     if (!JSON.stringify(query).includes('productType')) {
         products = products.filter((p) => p.productType !== 'booking');
     }
+    // Same as the host: `true` = flagged, `false` = not flagged (missing counts).
+    for (const flag of ['notSoldInPos', 'notSoldOnline']) {
+        if (typeof query[flag] === 'boolean')
+            products = products.filter((p) => !!p[flag] === query[flag]);
+    }
+    if (!params?.includeUnlisted) {
+        // Same as the host: flagged variants are stripped, a product left with none is dropped.
+        if (query.notSoldInPos === undefined)
+            products = products.filter((p) => !p.notSoldInPos);
+        products = products
+            .filter((p) => !p.variants.length || p.variants.some((v) => !v.notSoldInPos))
+            .map((p) => ({ ...p, variants: p.variants.filter((v) => !v.notSoldInPos) }));
+    }
     if (query.searchValue) {
         const search = String(query.searchValue).toLowerCase();
         products = products.filter((p) => p.name.toLowerCase().includes(search) || p.sku?.toLowerCase().includes(search));

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

@@ -42,8 +42,24 @@ export interface GetProductsParams {
         };
         supplier?: string;
         externalId?: string;
+        /**
+         * Product-level flag filter. `true` = only products flagged `notSoldInPos`; `false` = only
+         * 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). On a storefront, naming it switches off the default exclusion. */
+        notSoldOnline?: boolean;
         [key: string]: any;
     };
+    /**
+     * 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. */
     offset?: number;
     /** Defaults to 100. */

package/dist/actions/resume-checkout/action.d.ts

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

package/dist/actions/resume-checkout/action.js

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

package/dist/actions/resume-checkout/mock.d.ts

@@ -0,0 +1,16 @@
+import { ResumeCheckout } from './types';
+/**
+ * Standalone mock of the checkout return leg.
+ *
+ * It reads the SAME query parameters the real provider sends a shopper back
+ * with, so a builder can exercise the redirect path in preview by appending
+ * them by hand:
+ *
+ *   ?sessionId=CS_MOCK&redirectResult=MOCK
+ *
+ * Without them it answers `{ resumed: false }` and does nothing, which is what
+ * the real command does on an ordinary page load. That is the branch a
+ * checkout screen hits on every normal visit, so it is the one worth getting
+ * right in a mock.
+ */
+export declare const mockResumeCheckout: ResumeCheckout;

package/dist/actions/resume-checkout/mock.js

@@ -0,0 +1,51 @@
+import { mockPublishEvent } from '../../demo/database';
+/**
+ * Standalone mock of the checkout return leg.
+ *
+ * It reads the SAME query parameters the real provider sends a shopper back
+ * with, so a builder can exercise the redirect path in preview by appending
+ * them by hand:
+ *
+ *   ?sessionId=CS_MOCK&redirectResult=MOCK
+ *
+ * Without them it answers `{ resumed: false }` and does nothing, which is what
+ * the real command does on an ordinary page load. That is the branch a
+ * checkout screen hits on every normal visit, so it is the one worth getting
+ * right in a mock.
+ */
+export const mockResumeCheckout = async (params) => {
+    console.log('[Mock] resumeCheckout called', params);
+    const href = params?.url ?? (typeof window === 'undefined' ? '' : window.location.href);
+    let redirectResult = null;
+    try {
+        redirectResult = new URL(href).searchParams.get('redirectResult');
+    }
+    catch {
+        redirectResult = null;
+    }
+    if (!redirectResult) {
+        return {
+            success: true,
+            timestamp: new Date().toISOString(),
+            checkout: { resumed: false },
+        };
+    }
+    const suffix = String(Date.now()).slice(-6);
+    const checkout = {
+        resumed: true,
+        orderId: `mock-order-${suffix}`,
+        receiptId: `ON-001-${suffix}`,
+        // `Authorised` is what the real provider reports for a completed redirect.
+        // It is NOT settlement — see the checkout topic docs.
+        resultCode: 'Authorised',
+        sessionResult: `mock-session-result-${suffix}`,
+        orderPassword: `mock-pw-${suffix}`,
+    };
+    mockPublishEvent('checkout', 'payment-completed', {
+        orderId: checkout.orderId,
+        receiptId: checkout.receiptId,
+        resultCode: checkout.resultCode,
+        sessionResult: checkout.sessionResult,
+    });
+    return { success: true, timestamp: new Date().toISOString(), checkout };
+};

package/dist/actions/resume-checkout/types.d.ts

@@ -0,0 +1,59 @@
+export interface ResumeCheckoutParams {
+    /**
+     * Where to read the provider's return data from. Defaults to the current
+     * page URL, which is where the shopper has just landed.
+     *
+     * Only override this if you moved the query string somewhere else before
+     * calling — for example if your router strips it on mount.
+     */
+    url?: string;
+}
+/**
+ * What the return leg produced. Every field past `resumed` is absent when
+ * `resumed` is `false`.
+ */
+export interface ResumeCheckoutResult {
+    /**
+     * `false` means THIS WAS AN ORDINARY PAGE LOAD — no provider return data was
+     * in the URL, so there was nothing to finish and nothing happened. It is not
+     * an error, and it is the answer on every normal visit to the page. Call this
+     * unconditionally when your checkout or confirmation screen mounts and branch
+     * on this field.
+     */
+    resumed: boolean;
+    orderId?: string;
+    receiptId?: string;
+    /**
+     * The provider's result code for the completed attempt, e.g. `Authorised` or
+     * `Refused`. As everywhere else in this topic, `Authorised` is an
+     * authorisation and NOT a settlement.
+     */
+    resultCode?: string;
+    /** Opaque proof of the payment — see `PaymentCompletedPayload.sessionResult`. */
+    sessionResult?: string;
+    /**
+     * The one-time order password from the original checkout, recovered from
+     * browser storage. The page that held it in memory is gone, so this is the
+     * only way back to the order's status after a redirect.
+     */
+    orderPassword?: string;
+}
+export interface ResumeCheckoutResponse {
+    success: boolean;
+    timestamp: string;
+    checkout: ResumeCheckoutResult;
+}
+/**
+ * Finish a checkout the shopper was redirected away from.
+ *
+ * SAFE TO CALL ON EVERY PAGE LOAD, and that is how it is meant to be used: on
+ * an ordinary visit it finds no return data and answers `{ resumed: false }`
+ * without touching the network. Calling it twice for one return is also safe —
+ * the return data is consumed the first time.
+ *
+ * The outcome is ALSO published on the `checkout` topic (`payment-completed` or
+ * `payment-failed`), exactly as it would have been had the shopper never left,
+ * so a page that already subscribes needs no second code path. Subscribe first,
+ * then call this, or the event fires before you are listening.
+ */
+export type ResumeCheckout = (params?: ResumeCheckoutParams) => Promise<ResumeCheckoutResponse>;

package/dist/actions/resume-checkout/types.js

@@ -0,0 +1,13 @@
+// Resume Checkout Types
+//
+// The RETURN LEG of an online checkout. Some payment methods — and 3-D Secure
+// on a card — take the shopper away to their bank or wallet and send them back
+// to `returnUrl` on a FRESH PAGE LOAD. The payment is not finished at that
+// point: the provider hands the browser a one-time result in the URL, and it
+// has to be handed back to the provider to complete the charge.
+//
+// `startCheckout` cannot do this. It ran in the page that is now gone.
+//
+// Served ONLY by the storefront runtime (a published website), like
+// `startCheckout`. On a register it does not exist.
+export {};

package/dist/actions/resume-parked-order/mock.d.ts

@@ -1,2 +1,2 @@
-import { ResumeParkedOrder } from "./types";
+import { ResumeParkedOrder } from './types';
 export declare const mockResumeParkedOrder: ResumeParkedOrder;

package/dist/actions/resume-parked-order/mock.js

@@ -1,11 +1,11 @@
-import { MOCK_PARKED_ORDERS, MOCK_CART, resetMockCart, mockPublishEvent } from "../../demo/database";
+import { MOCK_PARKED_ORDERS, MOCK_CART, MOCK_PRODUCTS, resetMockCart, mockPublishEvent } from '../../demo/database';
 export const mockResumeParkedOrder = async (params) => {
-    console.log("[Mock] resumeParkedOrder called", params);
+    console.log('[Mock] resumeParkedOrder called', params);
     const orderId = params?.orderId;
     let orderToResume = null;
     let index = -1;
     if (orderId) {
-        index = MOCK_PARKED_ORDERS.findIndex(o => o._id === orderId);
+        index = MOCK_PARKED_ORDERS.findIndex((o) => o._id === orderId);
         if (index !== -1)
             orderToResume = MOCK_PARKED_ORDERS[index];
     }
@@ -17,8 +17,14 @@ export const mockResumeParkedOrder = async (params) => {
         }
     }
     if (!orderToResume) {
-        throw new Error("Parked order not found");
+        throw new Error('Parked order not found');
     }
+    // Same refusal and text as the host, before anything is restored: the parked order stays.
+    const notSoldNames = orderToResume.lineItems
+        .filter((li) => MOCK_PRODUCTS.some((p) => p.variants.some((v) => v._id === li.variantId && (p.notSoldInPos || v.notSoldInPos))))
+        .map((li) => li.name);
+    if (notSoldNames.length)
+        throw new Error(`${notSoldNames.join(', ')} is not sold in POS`);
     // Restore to MOCK_CART
     // Logic to convert Order back to Cart (simplified)
     resetMockCart();
@@ -26,7 +32,7 @@ export const mockResumeParkedOrder = async (params) => {
     MOCK_CART.customer = orderToResume.customer; // Cast if needed
     // MOCK_CART.products = orderToResume.lineItems... (Mapping needed)
     // For Mock demo, we'll do a best effort mapping
-    MOCK_CART.products = orderToResume.lineItems.map(li => ({
+    MOCK_CART.products = orderToResume.lineItems.map((li) => ({
         id: li.productId,
         name: li.name,
         quantity: li.quantity,
@@ -36,8 +42,8 @@ export const mockResumeParkedOrder = async (params) => {
         sku: li.sku,
         images: [li.image],
         stock: 100,
-        taxTableId: "",
-        attributes: li.attributes
+        taxTableId: '',
+        attributes: li.attributes,
     }));
     MOCK_CART.subtotal = orderToResume.summary.subtotalAfterFees;
     MOCK_CART.total = orderToResume.summary.total;
@@ -46,11 +52,11 @@ export const mockResumeParkedOrder = async (params) => {
     // Remove from parked
     MOCK_PARKED_ORDERS.splice(index, 1);
     // Refresh the restored cart and the order lists.
-    mockPublishEvent("cart", "parked-order-resumed", { orderId });
-    mockPublishEvent("orders", "parked-order-resumed", { orderId });
+    mockPublishEvent('cart', 'parked-order-resumed', { orderId });
+    mockPublishEvent('orders', 'parked-order-resumed', { orderId });
     return {
         success: true,
         order: orderToResume,
-        timestamp: new Date().toISOString()
+        timestamp: new Date().toISOString(),
     };
 };

package/dist/actions/set-outlet/action.d.ts

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

package/dist/actions/set-outlet/action.js

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

package/dist/actions/set-outlet/mock.d.ts

@@ -0,0 +1,13 @@
+import type { SetOutlet } from './types';
+/**
+ * Standalone mock of switching location.
+ *
+ * It mirrors the two REFUSALS the real command makes — a missing id, and an
+ * outlet that cannot take a payment — because those are the mistakes a builder
+ * actually hits. A mock that accepted anything would let a location picker look
+ * finished and then strand a shopper at a dead payment step on the real site.
+ *
+ * The unconnected id comes from the `getOutlets` mock rather than being repeated
+ * here, so the two cannot drift into telling different stories.
+ */
+export declare const mockSetOutlet: SetOutlet;

package/dist/actions/set-outlet/mock.js

@@ -0,0 +1,24 @@
+import { MOCK_UNCONNECTED_OUTLET_ID } from '../get-outlets/mock';
+/**
+ * Standalone mock of switching location.
+ *
+ * It mirrors the two REFUSALS the real command makes — a missing id, and an
+ * outlet that cannot take a payment — because those are the mistakes a builder
+ * actually hits. A mock that accepted anything would let a location picker look
+ * finished and then strand a shopper at a dead payment step on the real site.
+ *
+ * The unconnected id comes from the `getOutlets` mock rather than being repeated
+ * here, so the two cannot drift into telling different stories.
+ */
+export const mockSetOutlet = async (params) => {
+    console.log('[Mock] setOutlet called', params);
+    if (!params)
+        throw new Error('Params required');
+    if (!params.outletId || !params.outletId.trim()) {
+        throw new Error('setOutlet: outletId is required');
+    }
+    if (params.outletId === MOCK_UNCONNECTED_OUTLET_ID) {
+        throw new Error(`setOutlet: outlet ${params.outletId} cannot take an online payment — offer only outlets with connected: true`);
+    }
+    return { outletId: params.outletId, rehydrated: true, timestamp: new Date().toISOString() };
+};

package/dist/actions/set-outlet/types.d.ts

@@ -0,0 +1,31 @@
+export interface SetOutletParams {
+    /** An `id` from `getOutlets`. */
+    outletId: string;
+}
+export interface SetOutletResponse {
+    /** The location now in effect. */
+    outletId: string;
+    /**
+     * `true` when the catalog and tax tables were re-pulled for this location.
+     *
+     * `false` means the switch took effect but the refresh could not reach the
+     * server — the shop is running on what it already had cached. Totals may be
+     * the previous location's until the next refresh pass lands, so a flow can
+     * tell the shopper to try again rather than quietly showing stale tax.
+     */
+    rehydrated: boolean;
+    timestamp: string;
+}
+/**
+ * Switch the shop to another of the company's locations.
+ *
+ * REFUSES AN OUTLET THAT CANNOT TAKE A PAYMENT, and one that does not belong to
+ * this company, rather than letting either fail later at the payment step. Check
+ * `connected` from `getOutlets` and do not offer those, so this refusal is a
+ * backstop rather than something a shopper ever sees.
+ *
+ * The cart survives the switch. Its lines are kept and re-priced; a line that is
+ * not purchasable at the new location is not silently dropped here, it is
+ * reported when the checkout is next priced.
+ */
+export type SetOutlet = (params: SetOutletParams) => Promise<SetOutletResponse>;