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

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/demo/database.js

@@ -982,8 +982,10 @@ const CLOSE_HOUR = 18;
 // Rooms, not people: a resource is whatever is scarce, and a room is the case that
 // reads the same in every vertical a dataset might describe.
 export const MOCK_BOOKING_RESOURCES = [
-    { id: 'res_room_1', name: 'Room 1', kind: BookingResourceKind.ROOM },
-    { id: 'res_room_2', name: 'Room 2', kind: BookingResourceKind.ROOM },
+    // Two different photos, from the assets this demo already ships: a screen that picks a
+    // resource by sight has to be fed two that look apart, not one repeated.
+    { id: 'res_room_1', name: 'Room 1', kind: BookingResourceKind.ROOM, image: beetImg },
+    { id: 'res_room_2', name: 'Room 2', kind: BookingResourceKind.ROOM, image: roastedTomatoImg },
 ];
 /**
  * The clock this mock shop keeps — the same one `getContext` reports. They used to disagree: the

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