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

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/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/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/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>;

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

@@ -0,0 +1,21 @@
+// Set Outlet Types
+//
+// Choose which of the company's locations this shop is ordering from.
+//
+// WHAT IT ACTUALLY CHANGES. An outlet decides three things, and a shop that lets
+// a shopper pick one has to move all three together:
+//
+//   tax           rates follow the outlet's own address, so the total moves
+//   availability  stock is counted per location, and a product can be hidden at one
+//   fulfilment    the order records where the goods come from, so the right
+//                 location's stock is the one that is drawn down
+//
+// So this is not a display preference. It re-pulls the catalog for the new
+// location, re-hydrates the tax tables, and re-prices the cart. The totals a
+// flow reads afterwards are the new location's.
+//
+// SAFE MID-CHECKOUT. Checkout starts when a shopper ARRIVES, so by the time
+// anyone changes their mind an order usually already exists. That order is
+// re-priced and moved to the new outlet in place, keeping its id and its receipt
+// id, rather than being abandoned and replaced.
+export {};

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

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

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

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

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

@@ -0,0 +1,16 @@
+import { StartCheckout } from './types';
+/**
+ * Standalone mock of the storefront checkout.
+ *
+ * It mirrors the REFUSALS of the real command (empty cart,
+ * container not on the page) in the same order, because those are what a
+ * builder actually hits first — a mock that accepted anything would let a
+ * checkout screen look finished and fail on the published site.
+ *
+ * The mounted box is deliberately labelled as a mock. The real command mounts
+ * the provider's hosted card fields (iframes owned by the payment provider);
+ * nothing here takes a card number, and the placeholder must never look like
+ * it does. Its button publishes `payment-completed` so a flow's subscriber —
+ * the only way the outcome ever arrives — can be exercised in preview.
+ */
+export declare const mockStartCheckout: StartCheckout;

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

@@ -0,0 +1,80 @@
+import { MOCK_CART, MOCK_COMPANY, mockPublishEvent } from '../../demo/database';
+/**
+ * Standalone mock of the storefront checkout.
+ *
+ * It mirrors the REFUSALS of the real command (empty cart,
+ * container not on the page) in the same order, because those are what a
+ * builder actually hits first — a mock that accepted anything would let a
+ * checkout screen look finished and fail on the published site.
+ *
+ * The mounted box is deliberately labelled as a mock. The real command mounts
+ * the provider's hosted card fields (iframes owned by the payment provider);
+ * nothing here takes a card number, and the placeholder must never look like
+ * it does. Its button publishes `payment-completed` so a flow's subscriber —
+ * the only way the outcome ever arrives — can be exercised in preview.
+ */
+export const mockStartCheckout = async (params) => {
+    console.log('[Mock] startCheckout called', params);
+    if (!params)
+        throw new Error('Params required');
+    // No email check: contact is optional now, because checkout starts on arrival.
+    // Refusing here would make "start on arrival" fail in PREVIEW while working on
+    // the published site, which is the worst way for this to be wrong.
+    if (!params.container || typeof params.container !== 'string') {
+        throw new Error('startCheckout: container must be a CSS selector string (e.g. "#card-fields") — a DOM element cannot cross the command boundary');
+    }
+    const lineCount = (MOCK_CART.products?.length ?? 0) + (MOCK_CART.customSales?.length ?? 0);
+    if (!lineCount) {
+        throw new Error('startCheckout: cannot check out an empty cart');
+    }
+    // Resolved BEFORE the order is "created", exactly as the real command does:
+    // finding out the selector is wrong after an order exists would leave an
+    // unpaid order behind for a typo that cost nothing to catch first.
+    const container = typeof document === 'undefined' ? null : document.querySelector(params.container);
+    if (!container) {
+        throw new Error(`startCheckout: checkout container "${params.container}" was not found on the page`);
+    }
+    const serverTotal = Math.round(MOCK_CART.amountToBeCharged || MOCK_CART.total);
+    const currency = MOCK_COMPANY.settings?.currency ?? 'USD';
+    const suffix = String(Date.now()).slice(-6);
+    const order = {
+        orderId: `mock-order-${suffix}`,
+        receiptId: `ON-001-${suffix}`,
+        serverTotal,
+        currency,
+        paymentStatus: 'ready',
+        orderPassword: `mock-pw-${suffix}`,
+    };
+    mockPublishEvent('checkout', 'checkout-started', { ...order });
+    container.replaceChildren();
+    const box = document.createElement('div');
+    box.setAttribute('data-mock-checkout', 'true');
+    box.style.cssText =
+        'border:1px dashed #9aa;border-radius:8px;padding:16px;font:14px system-ui,sans-serif;text-align:center;color:#334';
+    const label = document.createElement('div');
+    label.textContent = 'Mock payment fields — the published site shows the real hosted card fields here.';
+    label.style.cssText = 'margin-bottom:12px;opacity:.75';
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.textContent = `Simulate paying ${(serverTotal / 100).toFixed(2)} ${currency}`;
+    button.style.cssText =
+        'padding:10px 16px;border:0;border-radius:6px;background:#111;color:#fff;font-size:14px;cursor:pointer';
+    button.addEventListener('click', () => {
+        button.disabled = true;
+        // `Authorised` is what the real provider reports for a successful card
+        // entry. It is NOT settlement — see the checkout topic docs.
+        mockPublishEvent('checkout', 'payment-completed', {
+            orderId: order.orderId,
+            receiptId: order.receiptId,
+            resultCode: 'Authorised',
+        });
+    });
+    box.appendChild(label);
+    box.appendChild(button);
+    container.appendChild(box);
+    return {
+        success: true,
+        timestamp: new Date().toISOString(),
+        order,
+    };
+};

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

@@ -0,0 +1,90 @@
+/**
+ * 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 StartCheckoutContact {
+    email: string;
+    name?: string;
+    phone?: string;
+}
+export interface StartCheckoutParams {
+    /**
+     * OPTIONAL, because checkout starts when the shopper ARRIVES rather than when
+     * they submit a form. 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 they have typed anything.
+     *
+     * Supply it afterwards with `attachCheckoutContact`, which re-sends the same
+     * idempotency key and so reaches the SAME order.
+     */
+    contact?: StartCheckoutContact;
+    /**
+     * CSS SELECTOR for the element the payment fields mount into, e.g.
+     * `'#card-fields'`. The element must already be in the DOM when this is
+     * called.
+     *
+     * A SELECTOR, NOT AN ELEMENT — and this is not a style preference. Command
+     * params cross a `postMessage` boundary, which serializes them with the
+     * structured clone algorithm; a DOM node is not cloneable, so passing
+     * `ref.current` throws `DataCloneError: HTMLDivElement object could not be
+     * cloned` before the command is ever sent. The string is resolved on the
+     * runtime's side against the same document the page rendered.
+     */
+    container: string;
+    /**
+     * Where the provider returns the shopper after a redirect payment method
+     * (bank apps, wallets). Defaults to the current URL.
+     *
+     * Must be HTTPS and on the SAME ORIGIN the storefront token was minted for;
+     * the server rejects anything else, since this URL is handed to a payment
+     * provider and an open redirect on a checkout is a phishing primitive.
+     */
+    returnUrl?: string;
+    /**
+     * Overrides the cart-derived idempotency key. Leave unset: the default is
+     * derived from the cart, which is what makes a shopper's double-tap on "Pay"
+     * return the SAME order instead of creating a second, abandoned one.
+     */
+    idempotencyKey?: string;
+    /** Defaults to the outlet the storefront booted against. */
+    outletId?: string;
+    /** Forwarded verbatim to the provider's Drop-in (`showPayButton`, `locale`, field styling, …). */
+    dropinConfiguration?: Record<string, unknown>;
+}
+/**
+ * The created order. Deliberately says nothing about money having moved — see
+ * `paymentStatus` and the `checkout` topic.
+ */
+export interface StartCheckoutOrder {
+    orderId: string;
+    receiptId: string;
+    /** The SERVER-computed total in integer minor units — the only total that matters. */
+    serverTotal: number;
+    currency: string;
+    /**
+     * `ready` — the payment fields are mounted and the shopper can pay.
+     * `unavailable` — THE ORDER EXISTS but no payment could be started, so the
+     * shopper has NOT been charged. Never report this as a failed order.
+     */
+    paymentStatus: 'ready' | 'unavailable';
+    /**
+     * One-time password for reading this order back, returned only on the first
+     * create. It is the ONLY route to this order's status — the guest token
+     * grants order creation and deliberately not order reads — so a caller that
+     * drops it cannot check whether the payment settled.
+     */
+    orderPassword?: string;
+}
+export interface StartCheckoutResponse {
+    success: boolean;
+    timestamp: string;
+    order: StartCheckoutOrder;
+}
+/**
+ * Creates the server-priced order and mounts the provider's hosted card fields.
+ *
+ * RESOLVES WHEN THE SHOPPER *CAN* PAY, NOT WHEN THEY HAVE. The shopper has not
+ * typed a card yet when this returns. The outcome arrives on the `checkout`
+ * topic instead.
+ */
+export type StartCheckout = (params: StartCheckoutParams) => Promise<StartCheckoutResponse>;

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

@@ -0,0 +1,10 @@
+// Start Checkout Types
+//
+// The ONLINE counterpart of the POS tenders: a shopper on a published website
+// pays for the current cart with their own card. Mirrors kaching's storefront
+// `startCheckout` input and result. All money is integer MINOR currency units.
+//
+// This command is served ONLY by the storefront runtime (a published website).
+// On a register it does not exist, exactly as the till tenders (`cashPayment`,
+// `terminalPayment`, `tapToPayPayment`, `chargeMoto`) do not exist online.
+export {};

package/dist/index.d.ts

@@ -52,6 +52,10 @@ export declare const command: {
     readonly integrationPayment: import(".").IntegrationPayment;
     readonly createPaymentLink: import(".").CreatePaymentLink;
     readonly chargeMoto: import(".").ChargeMoto;
+    readonly startCheckout: import(".").StartCheckout;
+    readonly attachCheckoutContact: import(".").AttachCheckoutContact;
+    readonly setOutlet: import(".").SetOutlet;
+    readonly resumeCheckout: import(".").ResumeCheckout;
     readonly addCustomerNote: import(".").AddCustomerNote;
     readonly removeCustomerNote: import(".").RemoveCustomerNote;
     readonly removeCustomerFromCart: import(".").RemoveCustomerFromCart;
@@ -147,7 +151,7 @@ export type { AddProduct, AddProductParams, AddProductResponse } from './actions
 export type { EditProduct, EditProductParams, EditProductResponse } from './actions/edit-product/types';
 export type { EditProductVariants, EditProductVariantsParams, EditProductVariantsResponse, } from './actions/edit-product-variants/types';
 export type { DeleteProduct, DeleteProductParams, DeleteProductResponse } from './actions/delete-product/types';
-export type { GetOutlets, GetOutletsResponse } from './actions/get-outlets/types';
+export type { GetOutlets, GetOutletsParams, GetOutletsResponse } from './actions/get-outlets/types';
 export type { GetStations, GetStationsParams, GetStationsResponse } from './actions/get-stations/types';
 export type { GetSmartGridLayout, GetSmartGridLayoutParams, GetSmartGridLayoutResponse, } from './actions/get-smart-grid-layout/types';
 export type { SaveSmartGridLayout, SaveSmartGridLayoutParams, SaveSmartGridLayoutResponse, } from './actions/save-smart-grid-layout/types';
@@ -196,6 +200,10 @@ export type { RedeemPayment, RedeemPaymentParams, RedeemPaymentResponse } from '
 export type { IntegrationPayment, IntegrationPaymentParams, IntegrationPaymentResponse, IntegrationEmvData, } from './actions/integration-payment/types';
 export type { CreatePaymentLink, CreatePaymentLinkParams, CreatePaymentLinkResponse, } from './actions/create-payment-link/types';
 export type { ChargeMoto, ChargeMotoParams, ChargeMotoResponse, ChargeMotoCardFields, } from './actions/charge-moto/types';
+export type { StartCheckout, StartCheckoutParams, StartCheckoutResponse, StartCheckoutContact, StartCheckoutOrder, } from './actions/start-checkout/types';
+export type { AttachCheckoutContact, AttachCheckoutContactParams, AttachCheckoutContactResponse, } from './actions/attach-checkout-contact/types';
+export type { SetOutlet, SetOutletParams, SetOutletResponse } from './actions/set-outlet/types';
+export type { ResumeCheckout, ResumeCheckoutParams, ResumeCheckoutResponse, ResumeCheckoutResult, } from './actions/resume-checkout/types';
 export type { AddCustomerNote, AddCustomerNoteParams, AddCustomerNoteResponse, } from './actions/add-customer-note/types';
 export type { RemoveCustomerNote, RemoveCustomerNoteParams, RemoveCustomerNoteResponse, } from './actions/remove-customer-note/types';
 export type { RemoveCustomerFromCart, RemoveCustomerFromCartResponse } from './actions/remove-customer-from-cart/types';
@@ -252,6 +260,7 @@ export { refundsTopic } from './pubsub/topics/refunds';
 export { productsTopic } from './pubsub/topics/products';
 export { cartTopic } from './pubsub/topics/cart';
 export { paymentsTopic } from './pubsub/topics/payments';
+export { checkoutTopic } from './pubsub/topics/checkout';
 export { splitPaymentsTopic } from './pubsub/topics/split-payments';
 export { customTablesTopic } from './pubsub/topics/custom-tables';
 export { printTopic } from './pubsub/topics/print';
@@ -279,6 +288,7 @@ export type { CategoryCreatedPayload, CategoryCreatedEvent, CategoryUpdatedPaylo
 export type { AttributeCreatedPayload, AttributeCreatedEvent, AttributeUpdatedPayload, AttributeUpdatedEvent, AttributesEventType, AttributesEventPayload, } from './pubsub/topics/attributes/types';
 export type { CartCreatedPayload, CartCustomerAssignedPayload, ProductAddedPayload, ProductDeletedPayload, CartDiscountAddedPayload, CartDiscountRemovedPayload, CartFeeAddedPayload, CartFeeRemovedPayload, ProductDiscountAddedPayload, ProductDiscountRemovedPayload, ProductFeeAddedPayload, ProductFeeRemovedPayload, ProductNoteAddedPayload, ProductNoteRemovedPayload, CartCreatedEvent, CartCustomerAssignedEvent, ProductAddedEvent, ProductDeletedEvent, CartDiscountAddedEvent, CartDiscountRemovedEvent, CartFeeAddedEvent, CartFeeRemovedEvent, ProductDiscountAddedEvent, ProductDiscountRemovedEvent, ProductFeeAddedEvent, ProductFeeRemovedEvent, ProductNoteAddedEvent, ProductNoteRemovedEvent, CartEventType, CartEventPayload, } from './pubsub/topics/cart/types';
 export type { PaymentDonePayload, PaymentErrPayload, PaymentDoneEvent, PaymentErrEvent, PaymentsEventType, PaymentsEventPayload, } from './pubsub/topics/payments/types';
+export type { CheckoutStartedPayload, PaymentCompletedPayload, PaymentFailedPayload, CheckoutStartedEvent, PaymentCompletedEvent, PaymentFailedEvent, CheckoutEventType, CheckoutEventPayload, } from './pubsub/topics/checkout/types';
 export type { SplitPaymentUpdatedPayload, SplitPaymentUpdatedEvent, SplitPaymentsEventType, SplitPaymentsEventPayload, } from './pubsub/topics/split-payments/types';
 export type { RowCreatedPayload, RowUpdatedPayload, RowDeletedPayload, RowCreatedEvent, RowUpdatedEvent, RowDeletedEvent, CustomTablesEventType, CustomTablesEventPayload, } from './pubsub/topics/custom-tables/types';
 export type { PrintStartedPayload, PrintCompletedPayload, PrintErrorPayload, PrintStartedEvent, PrintCompletedEvent, PrintErrorEvent, PrintEventType, PrintEventPayload, } from './pubsub/topics/print/types';

package/dist/index.js

@@ -52,6 +52,10 @@ import { redeemPayment } from './actions/redeem-payment/action';
 import { integrationPayment } from './actions/integration-payment/action';
 import { createPaymentLink } from './actions/create-payment-link/action';
 import { chargeMoto } from './actions/charge-moto/action';
+import { startCheckout } from './actions/start-checkout/action';
+import { attachCheckoutContact } from './actions/attach-checkout-contact/action';
+import { setOutlet } from './actions/set-outlet/action';
+import { resumeCheckout } from './actions/resume-checkout/action';
 // Customer Actions
 import { addCustomerNote } from './actions/add-customer-note/action';
 import { removeCustomerNote } from './actions/remove-customer-note/action';
@@ -198,6 +202,10 @@ export const command = {
     integrationPayment,
     createPaymentLink,
     chargeMoto,
+    startCheckout,
+    attachCheckoutContact,
+    setOutlet,
+    resumeCheckout,
     // Customer Actions
     addCustomerNote,
     removeCustomerNote,
@@ -308,6 +316,7 @@ export { refundsTopic } from './pubsub/topics/refunds';
 export { productsTopic } from './pubsub/topics/products';
 export { cartTopic } from './pubsub/topics/cart';
 export { paymentsTopic } from './pubsub/topics/payments';
+export { checkoutTopic } from './pubsub/topics/checkout';
 export { splitPaymentsTopic } from './pubsub/topics/split-payments';
 export { customTablesTopic } from './pubsub/topics/custom-tables';
 export { printTopic } from './pubsub/topics/print';

package/dist/projects/render/mocks.js

@@ -33,6 +33,11 @@ import { mockCashPayment } from '../../actions/cash-payment/mock';
 import { mockGetCashRoundingAmount } from '../../actions/get-cash-rounding-amount/mock';
 import { mockCreatePaymentLink } from '../../actions/create-payment-link/mock';
 import { mockChargeMoto } from '../../actions/charge-moto/mock';
+import { mockStartCheckout } from '../../actions/start-checkout/mock';
+import { mockAttachCheckoutContact } from '../../actions/attach-checkout-contact/mock';
+import { mockGetOutlets } from '../../actions/get-outlets/mock';
+import { mockSetOutlet } from '../../actions/set-outlet/mock';
+import { mockResumeCheckout } from '../../actions/resume-checkout/mock';
 import { mockGetTimeClockStatus } from '../../actions/get-time-clock-status/mock';
 import { mockClearCart } from '../../actions/clear-cart/mock';
 import { mockDeleteParkedOrder } from '../../actions/delete-parked-order/mock';
@@ -139,6 +144,11 @@ export const RENDER_MOCKS = {
     getCashRoundingAmount: mockGetCashRoundingAmount,
     createPaymentLink: mockCreatePaymentLink,
     chargeMoto: mockChargeMoto,
+    startCheckout: mockStartCheckout,
+    attachCheckoutContact: mockAttachCheckoutContact,
+    getOutlets: mockGetOutlets,
+    setOutlet: mockSetOutlet,
+    resumeCheckout: mockResumeCheckout,
     clearCart: mockClearCart,
     deleteParkedOrder: mockDeleteParkedOrder,
     voidOrder: mockVoidOrder,

package/dist/projects/render/types.d.ts

@@ -1,4 +1,4 @@
-import type { ExampleFunction, GetProducts, AddCustomSale, EditCustomSale, GetCustomers, AssignCustomer, AddCustomer, EditCustomer, GetCategories, GetOrders, GetRefunds, GetTaxTables, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, GetProductModifierSelections, SetProductModifierSelections, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, AddOrderNote, AddCartFee, ClearCart, ParkOrder, ResumeParkedOrder, DeleteParkedOrder, VoidOrder, InitiateRefund, CashPayment, GetCashRoundingAmount, TapToPayPayment, TerminalPayment, ExtensionPayment, RedeemPayment, AddNonRevenueItem, AddCustomerNote, RemoveCustomerNote, RemoveCustomerFromCart, GoToStationHome, OpenCashDrawer, ShowNotification, ShowConfirmation, AuthenticateUser, PartialPayment, SwitchUser, SetRefundStockAction, SelectAllRefundItems, ResetRefundDetails, CalculateRefundTotal, GetRemainingRefundableQuantities, ProcessPartialRefund, RedeemRefund, GetRefundPlan, CheckPermission, GetCurrentCart, Print, SetActiveOrder, GetCustomTables, GetCustomTableData, UpsertCustomTableData, DeleteCustomTableData, GetCustomExtensions, GetCurrentCompanyCustomExtensions, GetCustomExtensionCustomTables, GetCustomTableFields, GetSecretsKeys, GetSecretVal, SetSecretVal, GetUsers, GetRoles, RemoveCartDiscount, GetActiveOrder, GetActiveCustomer, SetActiveCustomer, GetActiveOutlet, GetActiveStation, GetActiveSession, GetActiveUser, SetActiveUser, SetActiveRefund, RemoveProductDiscount, RemoveProductFee, RemoveProductNote, RemoveCartFee, RemoveOrderNote, RemoveCustomSale, RemoveNonRevenueItem, CanTransition, GetAvailableTransitions, ApplyTransition, IntegrationPayment, GetSmartGridLayout, SaveSmartGridLayout, SendEmail, SendSms, GetBookingResources, GetBookingAvailability, GetBookings, HoldBooking, AddBookingToCart, RemoveBookingFromCart, CancelBooking, CreatePaymentLink, ChargeMoto, GetTimeClockStatus } from '../../index';
+import type { ExampleFunction, GetProducts, AddCustomSale, EditCustomSale, GetCustomers, AssignCustomer, AddCustomer, EditCustomer, GetCategories, GetOrders, GetRefunds, GetTaxTables, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, GetProductModifierSelections, SetProductModifierSelections, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, AddOrderNote, AddCartFee, ClearCart, ParkOrder, ResumeParkedOrder, DeleteParkedOrder, VoidOrder, InitiateRefund, CashPayment, GetCashRoundingAmount, TapToPayPayment, TerminalPayment, ExtensionPayment, RedeemPayment, AddNonRevenueItem, AddCustomerNote, RemoveCustomerNote, RemoveCustomerFromCart, GoToStationHome, OpenCashDrawer, ShowNotification, ShowConfirmation, AuthenticateUser, PartialPayment, SwitchUser, SetRefundStockAction, SelectAllRefundItems, ResetRefundDetails, CalculateRefundTotal, GetRemainingRefundableQuantities, ProcessPartialRefund, RedeemRefund, GetRefundPlan, CheckPermission, GetCurrentCart, Print, SetActiveOrder, GetCustomTables, GetCustomTableData, UpsertCustomTableData, DeleteCustomTableData, GetCustomExtensions, GetCurrentCompanyCustomExtensions, GetCustomExtensionCustomTables, GetCustomTableFields, GetSecretsKeys, GetSecretVal, SetSecretVal, GetUsers, GetRoles, RemoveCartDiscount, GetActiveOrder, GetActiveCustomer, SetActiveCustomer, GetActiveOutlet, GetActiveStation, GetActiveSession, GetActiveUser, SetActiveUser, SetActiveRefund, RemoveProductDiscount, RemoveProductFee, RemoveProductNote, RemoveCartFee, RemoveOrderNote, RemoveCustomSale, RemoveNonRevenueItem, CanTransition, GetAvailableTransitions, ApplyTransition, IntegrationPayment, GetSmartGridLayout, SaveSmartGridLayout, SendEmail, SendSms, GetBookingResources, GetBookingAvailability, GetBookings, HoldBooking, AddBookingToCart, RemoveBookingFromCart, CancelBooking, CreatePaymentLink, ChargeMoto, StartCheckout, AttachCheckoutContact, GetOutlets, SetOutlet, ResumeCheckout, GetTimeClockStatus } from '../../index';
 export interface RenderProviderActions {
     exampleFunction: ExampleFunction;
     getProducts: GetProducts;
@@ -52,6 +52,21 @@ export interface RenderProviderActions {
     integrationPayment: IntegrationPayment;
     createPaymentLink: CreatePaymentLink;
     chargeMoto: ChargeMoto;
+    /**
+     * ONLINE checkout — served only by the storefront runtime (a published
+     * website). The till tenders above are refused there, and this is refused on
+     * a register, because the two declare different things to the card networks.
+     */
+    startCheckout: StartCheckout;
+    attachCheckoutContact: AttachCheckoutContact;
+    getOutlets: GetOutlets;
+    setOutlet: SetOutlet;
+    /**
+     * The RETURN LEG of an online checkout, after a redirect payment method or
+     * 3-D Secure sent the shopper away and back. Storefront-only, like
+     * `startCheckout`, and safe to call on every page load.
+     */
+    resumeCheckout: ResumeCheckout;
     addNonRevenueItem: AddNonRevenueItem;
     addCustomerNote: AddCustomerNote;
     removeCustomerNote: RemoveCustomerNote;

package/dist/pubsub/topics/checkout/checkout-started/types.d.ts

@@ -0,0 +1,26 @@
+import type { TopicEvent } from "../../../types";
+/**
+ * Payload for checkout-started event
+ *
+ * The order EXISTS and is unpaid. `serverTotal` is the server's own price for
+ * the cart, in integer minor units — the browser never sends a price, so this
+ * is the first and only authoritative total.
+ */
+export interface CheckoutStartedPayload {
+    orderId: string;
+    receiptId: string;
+    serverTotal: number;
+    currency: string;
+    /**
+     * `ready` — the payment fields are mounted and the shopper can pay.
+     * `unavailable` — the order exists but no payment could be started, so the
+     * shopper has NOT been charged.
+     */
+    paymentStatus: "ready" | "unavailable";
+    /** One-time password for reading this order back. Returned only on the first create. */
+    orderPassword?: string;
+}
+/**
+ * Typed event for checkout-started
+ */
+export type CheckoutStartedEvent = TopicEvent<CheckoutStartedPayload>;

package/dist/pubsub/topics/checkout/checkout-started/types.js

@@ -0,0 +1 @@
+export {};

package/dist/pubsub/topics/checkout/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checkout Topic Definition
+ * Defines the checkout topic and its available event types
+ */
+import type { TopicDefinition } from "../../types";
+export declare const checkoutTopic: TopicDefinition;
+export * from "./types";

package/dist/pubsub/topics/checkout/index.js

@@ -0,0 +1,28 @@
+/**
+ * Checkout Topic Definition
+ * Defines the checkout topic and its available event types
+ */
+export const checkoutTopic = {
+    id: "checkout",
+    name: "Checkout",
+    description: "Topic for online (website) checkout events",
+    eventTypes: [
+        {
+            id: "checkout-started",
+            name: "Checkout Started",
+            description: "Published when the order has been created and the payment fields are mounted"
+        },
+        {
+            id: "payment-completed",
+            name: "Payment Completed",
+            description: "Published when the shopper's payment succeeds on their side (authorisation, not settlement)"
+        },
+        {
+            id: "payment-failed",
+            name: "Payment Failed",
+            description: "Published when a payment attempt is refused or errors; the shopper can retry"
+        }
+    ]
+};
+// Re-export types
+export * from "./types";

package/dist/pubsub/topics/checkout/payment-completed/types.d.ts

@@ -0,0 +1,31 @@
+import type { TopicEvent } from "../../../types";
+/**
+ * Payload for payment-completed event
+ *
+ * THIS IS NOT SETTLEMENT. It reports that the SHOPPER'S side finished —
+ * `resultCode` is the provider's own outcome, typically `Authorised`. The money
+ * is confirmed by the provider's capture webhook reaching the backend, out of
+ * band and after this page is done, so this event cannot and does not claim it.
+ */
+export interface PaymentCompletedPayload {
+    orderId: string;
+    receiptId: string;
+    /** The provider's result code, e.g. `Authorised`. */
+    resultCode: string;
+    /**
+     * OPAQUE PROOF OF THIS PAYMENT, handed to the browser by the provider and to
+     * nobody else. Pass it to the order-status read and the server verifies it
+     * with the provider before believing a word of it.
+     *
+     * It is the only evidence of an outcome that exists outside the provider's
+     * webhook, so it is what recovers an order whose confirmation never arrived.
+     * Treat it as a credential: do not log it, do not put it in a URL you share.
+     *
+     * Absent when the provider reported no payment (see `resultCode`).
+     */
+    sessionResult?: string;
+}
+/**
+ * Typed event for payment-completed
+ */
+export type PaymentCompletedEvent = TopicEvent<PaymentCompletedPayload>;

package/dist/pubsub/topics/checkout/payment-completed/types.js

@@ -0,0 +1 @@
+export {};

package/dist/pubsub/topics/checkout/payment-failed/types.d.ts

@@ -0,0 +1,20 @@
+import type { TopicEvent } from "../../../types";
+/**
+ * Payload for payment-failed event
+ *
+ * ONE DECLINED ATTEMPT, NOT A DEAD CHECKOUT. The order and the mounted payment
+ * fields both survive, so the shopper can try another card without the page
+ * starting a new checkout.
+ */
+export interface PaymentFailedPayload {
+    orderId: string;
+    receiptId: string;
+    /** The provider's result code, e.g. `Refused`, or an error name. */
+    resultCode: string;
+    /** Present when the failure carried a message worth showing. */
+    message?: string;
+}
+/**
+ * Typed event for payment-failed
+ */
+export type PaymentFailedEvent = TopicEvent<PaymentFailedPayload>;

package/dist/pubsub/topics/checkout/payment-failed/types.js

@@ -0,0 +1 @@
+export {};

package/dist/pubsub/topics/checkout/types.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Checkout Topic Types
+ * Aggregated types for all online-checkout events
+ */
+export * from "./checkout-started/types";
+export * from "./payment-completed/types";
+export * from "./payment-failed/types";
+import type { CheckoutStartedPayload } from "./checkout-started/types";
+import type { PaymentCompletedPayload } from "./payment-completed/types";
+import type { PaymentFailedPayload } from "./payment-failed/types";
+export type CheckoutEventPayload = CheckoutStartedPayload | PaymentCompletedPayload | PaymentFailedPayload;
+export type CheckoutEventType = "checkout-started" | "payment-completed" | "payment-failed";

package/dist/pubsub/topics/checkout/types.js

@@ -0,0 +1,8 @@
+/**
+ * Checkout Topic Types
+ * Aggregated types for all online-checkout events
+ */
+// Re-export all event types
+export * from "./checkout-started/types";
+export * from "./payment-completed/types";
+export * from "./payment-failed/types";

package/dist/pubsub/topics/index.d.ts

@@ -2,20 +2,21 @@
  * Pub/Sub Topics
  * Export all available topics and their types
  */
-export * from './customers';
-export * from './orders';
-export * from './bookings';
-export * from './refunds';
-export * from './products';
-export * from './cart';
-export * from './payments';
-export * from './custom-tables';
-export * from './print';
-export * from './outlet';
-export * from './station';
-export * from './session';
-export * from './users';
-export * from './variants';
-export * from './transactions';
-export * from './categories';
-export * from './attributes';
+export * from "./customers";
+export * from "./orders";
+export * from "./bookings";
+export * from "./refunds";
+export * from "./products";
+export * from "./cart";
+export * from "./payments";
+export * from "./checkout";
+export * from "./custom-tables";
+export * from "./print";
+export * from "./outlet";
+export * from "./station";
+export * from "./session";
+export * from "./users";
+export * from "./variants";
+export * from "./transactions";
+export * from "./categories";
+export * from "./attributes";

package/dist/pubsub/topics/index.js

@@ -2,20 +2,21 @@
  * Pub/Sub Topics
  * Export all available topics and their types
  */
-export * from './customers';
-export * from './orders';
-export * from './bookings';
-export * from './refunds';
-export * from './products';
-export * from './cart';
-export * from './payments';
-export * from './custom-tables';
-export * from './print';
-export * from './outlet';
-export * from './station';
-export * from './session';
-export * from './users';
-export * from './variants';
-export * from './transactions';
-export * from './categories';
-export * from './attributes';
+export * from "./customers";
+export * from "./orders";
+export * from "./bookings";
+export * from "./refunds";
+export * from "./products";
+export * from "./cart";
+export * from "./payments";
+export * from "./checkout";
+export * from "./custom-tables";
+export * from "./print";
+export * from "./outlet";
+export * from "./station";
+export * from "./session";
+export * from "./users";
+export * from "./variants";
+export * from "./transactions";
+export * from "./categories";
+export * from "./attributes";

package/dist/pubsub/topics/types.d.ts

@@ -4,6 +4,7 @@ import { RefundsEventType, RefundsEventPayload } from "./refunds/types";
 import { ProductsEventType, ProductsEventPayload } from "./products/types";
 import { CartEventType, CartEventPayload } from "./cart/types";
 import { PaymentsEventType, PaymentsEventPayload } from "./payments/types";
+import { CheckoutEventType, CheckoutEventPayload } from "./checkout/types";
 import { SplitPaymentsEventType, SplitPaymentsEventPayload } from "./split-payments/types";
 import { CustomTablesEventPayload, CustomTablesEventType } from "./custom-tables/types";
 import { PrintEventType, PrintEventPayload } from "./print/types";
@@ -23,6 +24,13 @@ export interface TopicEventPayloadMap {
     products: Record<ProductsEventType, ProductsEventPayload>;
     cart: Record<CartEventType, CartEventPayload>;
     payments: Record<PaymentsEventType, PaymentsEventPayload>;
+    /**
+     * ONLINE checkout only (a published website), where the POS `payments`
+     * topic never fires: `payments` reports a till tender settling in front of
+     * a cashier, while a web shopper's outcome arrives asynchronously and can
+     * only ever be an authorisation until the provider's webhook lands.
+     */
+    checkout: Record<CheckoutEventType, CheckoutEventPayload>;
     "split-payments": Record<SplitPaymentsEventType, SplitPaymentsEventPayload>;
     customTables: Record<CustomTablesEventType, CustomTablesEventPayload>;
     print: Record<PrintEventType, PrintEventPayload>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.8.0",
+  "version": "0.8.1-online.1",
   "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"
+    "@final-commerce/common": "2.4.1-online.1"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.0.0",