@final-commerce/command-frame 0.10.0 → 0.10.1-online.1

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/shipping.d.ts

@@ -0,0 +1,8 @@
+import { type ShippingZoneRule } from '@final-commerce/common';
+import type { ShippingOptionView } from '../actions/get-shipping-options/types';
+export declare const MOCK_SHIPPING_ZONES: ShippingZoneRule[];
+/** The demo cart's options, shaped like the runtime's answer. The mock runs as the website. */
+export declare function mockShippingOptions(): {
+    resolution: import("@final-commerce/common").ShippingResolution;
+    options: ShippingOptionView[];
+};

package/dist/demo/shipping.js

@@ -0,0 +1,69 @@
+import { resolveShipping } from '@final-commerce/common';
+import { MOCK_CART, MOCK_OUTLET_MAIN } from './database';
+/*
+ * The demo store's Settings › Shipping, so a flow previewed against the mocks meets the real rules
+ * (common's `resolveShipping`) rather than a canned list: Canada $10 (free over $100) or Express,
+ * Quebec at $15, pickup at the demo store, and nowhere else.
+ */
+export const MOCK_SHIPPING_ZONES = [
+    {
+        id: 'zone_canada',
+        kind: 'country',
+        places: [{ country: 'CA' }],
+        ships: true,
+        options: [
+            {
+                id: 'opt_standard',
+                type: 'ship',
+                name: 'Standard shipping',
+                price: 1000,
+                freeOver: 10000,
+                minDays: 3,
+                maxDays: 6,
+                channels: ['web', 'pos'],
+            },
+            { id: 'opt_express', type: 'ship', name: 'Express', price: 2000, minDays: 1, maxDays: 2, channels: ['web'] },
+            { id: 'opt_pickup', type: 'pickup', price: 0, channels: ['web'], outletId: MOCK_OUTLET_MAIN.id },
+        ],
+    },
+    {
+        id: 'zone_quebec',
+        kind: 'province',
+        places: [{ country: 'CA', province: 'QC' }],
+        ships: true,
+        options: [
+            {
+                id: 'opt_quebec',
+                type: 'ship',
+                name: 'Standard shipping',
+                price: 1500,
+                minDays: 4,
+                maxDays: 7,
+                channels: ['web', 'pos'],
+            },
+        ],
+    },
+];
+const STORE_NAME = MOCK_OUTLET_MAIN.name ?? 'the store';
+const money = (amount) => (amount === 0 ? 'Free' : `$${(amount / 100).toFixed(2)}`);
+/** The demo cart's options, shaped like the runtime's answer. The mock runs as the website. */
+export function mockShippingOptions() {
+    const resolution = resolveShipping({
+        zones: MOCK_SHIPPING_ZONES,
+        address: MOCK_CART.shippingAddress,
+        itemsTotal: MOCK_CART.subtotal,
+        channel: 'web',
+    });
+    const options = resolution.options.map((option) => ({
+        optionId: option.optionId,
+        type: option.type,
+        name: option.type === 'pickup' ? `Pickup at ${STORE_NAME}` : (option.name ?? ''),
+        amount: option.amount,
+        priceText: money(option.amount),
+        freeShippingHint: option.amountToFree ? `Add ${money(option.amountToFree)} more for free shipping` : null,
+        arrivalText: option.minDays != null ? `Arrives in ${option.minDays}–${option.maxDays} business days` : null,
+        pickup: option.type === 'pickup' ? { outletId: MOCK_OUTLET_MAIN.id, name: STORE_NAME, hours: [] } : null,
+        selected: MOCK_CART.shipping?.optionId === option.optionId,
+    }));
+    return { resolution, options };
+}

package/dist/index.d.ts

@@ -56,6 +56,15 @@ 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 getAddressOptions: import(".").GetAddressOptions;
+    readonly setOrderAddress: import(".").SetOrderAddress;
+    readonly getShippingOptions: import(".").GetShippingOptions;
+    readonly selectShippingOption: import(".").SelectShippingOption;
+    readonly setOutlet: import(".").SetOutlet;
+    readonly resumeCheckout: import(".").ResumeCheckout;
+    readonly getCheckoutStatus: import(".").GetCheckoutStatus;
     readonly addCustomerNote: import(".").AddCustomerNote;
     readonly removeCustomerNote: import(".").RemoveCustomerNote;
     readonly removeCustomerFromCart: import(".").RemoveCustomerFromCart;
@@ -151,7 +160,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';
@@ -204,6 +213,15 @@ 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 { GetAddressOptions, GetAddressOptionsParams, GetAddressOptionsResponse, AddressCountryOption, AddressProvinceOption, } from './actions/get-address-options/types';
+export type { SetOrderAddress, SetOrderAddressParams, SetOrderAddressResponse, OrderAddressType, } from './actions/set-order-address/types';
+export type { GetShippingOptions, GetShippingOptionsResponse, ShippingOptionView, ShippingPickupView, } from './actions/get-shipping-options/types';
+export type { SelectShippingOption, SelectShippingOptionParams, SelectShippingOptionResponse, } from './actions/select-shipping-option/types';
+export type { SetOutlet, SetOutletParams, SetOutletResponse } from './actions/set-outlet/types';
+export type { ResumeCheckout, ResumeCheckoutParams, ResumeCheckoutResponse, ResumeCheckoutResult, } from './actions/resume-checkout/types';
+export type { GetCheckoutStatus, GetCheckoutStatusParams, GetCheckoutStatusResponse, CheckoutOrderStatus, } from './actions/get-checkout-status/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';
@@ -260,6 +278,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';
@@ -287,6 +306,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

@@ -56,6 +56,15 @@ 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 { getAddressOptions } from './actions/get-address-options/action';
+import { setOrderAddress } from './actions/set-order-address/action';
+import { getShippingOptions } from './actions/get-shipping-options/action';
+import { selectShippingOption } from './actions/select-shipping-option/action';
+import { setOutlet } from './actions/set-outlet/action';
+import { resumeCheckout } from './actions/resume-checkout/action';
+import { getCheckoutStatus } from './actions/get-checkout-status/action';
 // Customer Actions
 import { addCustomerNote } from './actions/add-customer-note/action';
 import { removeCustomerNote } from './actions/remove-customer-note/action';
@@ -206,6 +215,15 @@ export const command = {
     integrationPayment,
     createPaymentLink,
     chargeMoto,
+    startCheckout,
+    attachCheckoutContact,
+    getAddressOptions,
+    setOrderAddress,
+    getShippingOptions,
+    selectShippingOption,
+    setOutlet,
+    resumeCheckout,
+    getCheckoutStatus,
     // Customer Actions
     addCustomerNote,
     removeCustomerNote,
@@ -316,6 +334,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

@@ -37,6 +37,16 @@ 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 { mockGetAddressOptions } from '../../actions/get-address-options/mock';
+import { mockSetOrderAddress } from '../../actions/set-order-address/mock';
+import { mockGetShippingOptions } from '../../actions/get-shipping-options/mock';
+import { mockSelectShippingOption } from '../../actions/select-shipping-option/mock';
+import { mockGetOutlets } from '../../actions/get-outlets/mock';
+import { mockSetOutlet } from '../../actions/set-outlet/mock';
+import { mockResumeCheckout } from '../../actions/resume-checkout/mock';
+import { mockGetCheckoutStatus } from '../../actions/get-checkout-status/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';
@@ -147,6 +157,16 @@ export const RENDER_MOCKS = {
     getCashRoundingAmount: mockGetCashRoundingAmount,
     createPaymentLink: mockCreatePaymentLink,
     chargeMoto: mockChargeMoto,
+    startCheckout: mockStartCheckout,
+    attachCheckoutContact: mockAttachCheckoutContact,
+    getAddressOptions: mockGetAddressOptions,
+    setOrderAddress: mockSetOrderAddress,
+    getShippingOptions: mockGetShippingOptions,
+    selectShippingOption: mockSelectShippingOption,
+    getOutlets: mockGetOutlets,
+    setOutlet: mockSetOutlet,
+    resumeCheckout: mockResumeCheckout,
+    getCheckoutStatus: mockGetCheckoutStatus,
     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, GetCustomStockActions, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, GetProductModifierSelections, GetCompositePrice, GetCompositeAvailability, SetProductModifierSelections, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, SetVariantUnavailable, 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, GetCustomStockActions, AddProductDiscount, AddProductToCart, RemoveProductFromCart, UpdateCartItemQuantity, AddCartDiscount, GetContext, GetFinalContext, AddProductNote, AddProductFee, GetProductModifierSelections, GetCompositePrice, GetCompositeAvailability, SetProductModifierSelections, SetActiveProductFee, SetActiveProductDiscount, GetActiveProduct, SetActiveProduct, AdjustInventory, SetVariantUnavailable, 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, GetAddressOptions, SetOrderAddress, GetShippingOptions, SelectShippingOption, GetOutlets, SetOutlet, ResumeCheckout, GetCheckoutStatus, GetTimeClockStatus } from '../../index';
 export interface RenderProviderActions {
     exampleFunction: ExampleFunction;
     getProducts: GetProducts;
@@ -56,6 +56,28 @@ 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;
+    /** Shipping, on the till (ship-to) and the website alike. The runtime prices; the flow renders. */
+    getAddressOptions: GetAddressOptions;
+    setOrderAddress: SetOrderAddress;
+    getShippingOptions: GetShippingOptions;
+    selectShippingOption: SelectShippingOption;
+    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;
+    /** Where an online order stands now, by its order password. Storefront-only. */
+    getCheckoutStatus: GetCheckoutStatus;
     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.10.0",
+  "version": "0.10.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.6.0"
+    "@final-commerce/common": "2.7.1-online.1"
   },
   "devDependencies": {
     "@commitlint/cli": "^19.0.0",