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

package/dist/CommonTypes.d.ts

@@ -1,5 +1,5 @@
 export * from './common-types';
-import type { Tax, Tip, Address, MetadataItem, PosDataItem, CartFeeTaxEntry, CartFeeItem, CartDiscountItem, OrderNote, NonRevenueItem, DiscountDetail, FeeDetail, DiscountLineItem, FeeLineItem, LineItem, TipPayment, RefundedTipPayment, PaymentMethod, Discount, CustomFee, Summary, CustomSale, RefundedCustomSale, RefundItem, RefundedLineItem, ActiveStation, ActiveSession, ActiveOutlet, ActiveUser, ActiveUserRole, ActiveOrder, ActiveCart, ActivePark, ActiveCompany, ActiveCustomSales, ActiveProduct, ActiveCustomer, FullProduct, ProductVariant, Inventory, ResolvedModifier, ResolvedModifierChoice, ModifierSelectionType, ModifierSelection, ModifierChoiceSelection, CartLineModifier, ProdModifierBreakdown, OrderLineItemModifier, CustomerNote, Attribute, AttributeOption, Category, Transaction, ActiveSplitPayment, BookingAvailability, BookingSlot, BookingSlotResource, BookingResource, Booking, CartReservation, OrderReservation, Composite, CompositePart, CompositeItem, CompositeChoice, CompositeItemUnavailable, CompositePick, CartLineComponent, OrderLineItemComponent } from '@final-commerce/common/pos-types';
+import type { Tax, Tip, Address, MetadataItem, PosDataItem, CartFeeTaxEntry, CartFeeItem, CartDiscountItem, OrderNote, NonRevenueItem, DiscountDetail, FeeDetail, DiscountLineItem, FeeLineItem, LineItem, TipPayment, RefundedTipPayment, PaymentMethod, Discount, CustomFee, Summary, CustomSale, RefundedCustomSale, RefundItem, RefundedLineItem, ActiveStation, ActiveSession, ActiveOutlet, ActiveUser, ActiveUserRole, ActiveOrder, ActiveCart, ActivePark, ActiveCompany, ActiveCustomSales, ActiveProduct, ActiveCustomer, FullProduct, ProductVariant, Inventory, ResolvedModifier, ResolvedModifierChoice, ModifierSelectionType, ModifierSelection, ModifierChoiceSelection, CartLineModifier, ProdModifierBreakdown, OrderLineItemModifier, CustomerNote, Attribute, AttributeOption, Category, Transaction, ActiveSplitPayment, BookingAvailability, BookingSlot, BookingSlotResource, BookingResource, Booking, CartReservation, OrderReservation, CartAddress, CartShipping, Composite, CompositePart, CompositeItem, CompositeChoice, CompositeItemUnavailable, CompositePick, CartLineComponent, OrderLineItemComponent } from '@final-commerce/common/pos-types';
 export { CurrencyCode, ProductType as CFProductType, UserTypes as CFUserTypes } from '@final-commerce/common';
 /** Open record used as a base for active entities. */
 export type CFActiveEntity = Record<string, unknown>;
@@ -105,6 +105,8 @@ export type CFActiveOrder = ActiveOrder;
 export type CFActiveCustomSales = ActiveCustomSales;
 export type CFNonRevenueItem = NonRevenueItem;
 export type CFActiveCart = ActiveCart;
+export type CFCartAddress = CartAddress;
+export type CFCartShipping = CartShipping;
 export type CFActivePark = ActivePark;
 export type CFActiveCompany = ActiveCompany;
 /** Tile kinds a SmartGrid cell can represent. Mirrors common's `BaseTile['type']`. */
@@ -147,6 +149,7 @@ export interface CFActiveRefundDetails {
     buttonsDisabled?: Record<string, boolean>;
     isRefund?: boolean;
     customSalesQuantities?: Record<string, number>;
+    /** Keyed by cart-fee id, plus the reserved key `'shipping'` for the order's shipping. 0/1 each. */
     cartFeesRefunds?: Record<string, number>;
     tipsRefunds?: Record<string, number>;
     refundProcessingStatus?: CFRefundProcessingStatus | null;
@@ -214,9 +217,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-address-options/action.d.ts

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -96,7 +96,7 @@ export function mockRefundBreakdown(rows, items) {
         return { type: row.type, itemKey: row.itemKey, quantity, amounts: scale(row.amounts, quantity / row.quantity) };
     })
         .filter((r) => r.quantity > 0);
-    const totals = { items: 0, discounts: 0, fees: 0, tax: 0, tip: 0, total: 0 };
+    const totals = { items: 0, discounts: 0, fees: 0, shipping: 0, tax: 0, tip: 0, total: 0 };
     for (const r of selected) {
         const a = r.amounts;
         if (r.type === 'fee')

package/dist/actions/get-refund-plan/types.d.ts

@@ -20,12 +20,13 @@ export interface GetRefundPlanParams {
     items?: {
         /**
          * `internalId` / `variantId` for a product, `customSaleId`, cart-fee id, tip
-         * `transactionId`, or a booking's own `internalId` on `order.reservations[]`.
+         * `transactionId`, a booking's own `internalId` on `order.reservations[]`, or
+         * `'shipping'` for the order's shipping (all or nothing, like a fee).
          */
         itemKey: string;
         quantity: number;
         /** Optional hint; inferred from the order when omitted. */
-        type?: 'product' | 'customSale' | 'fee' | 'tip' | 'reservation';
+        type?: 'product' | 'customSale' | 'fee' | 'tip' | 'reservation' | 'shipping';
     }[];
 }
 export interface RefundPlanSource {
@@ -79,7 +80,7 @@ export interface RefundPlanLeg {
         rounding: number;
     };
 }
-export type RefundPlanRowType = 'product' | 'customSale' | 'fee' | 'tip';
+export type RefundPlanRowType = 'product' | 'customSale' | 'fee' | 'tip' | 'shipping';
 /** One tax rate's share of a row's refund (minor units). */
 export interface RefundPlanTaxLine {
     name: string;
@@ -107,7 +108,7 @@ export interface RefundPlanAmounts {
     total: number;
 }
 /**
- * One refundable row of the order — a line item, custom sale, cart fee or tip —
+ * One refundable row of the order — a line item, custom sale, cart fee, shipping or tip —
  * served ready to render. Rows with nothing left to refund are not listed.
  */
 export interface RefundPlanRow {
@@ -121,7 +122,7 @@ export interface RefundPlanRow {
     attributes?: string;
     /** Tip rows only: the tender that took the tip (`card`, `cash`, …). */
     paymentType?: string;
-    /** Quantity originally sold. Fees and tips are `1` — all or nothing. */
+    /** Quantity originally sold. Fees, shipping and tips are `1` — all or nothing. */
     quantity: number;
     /** Quantity still refundable — the stepper's max. */
     refundableQuantity: number;
@@ -137,7 +138,7 @@ export interface RefundPlanSelectedRow {
 }
 /**
  * The selection's goods value broken down for display. Minor units;
- * `items − discounts + fees + tax + tip === total === allocation.itemTotal`.
+ * `items − discounts + fees + shipping + tax + tip === total === allocation.itemTotal`.
  */
 export interface RefundPlanTotals {
     /** Σ selected line subtotals (before discounts, tax excluded). */
@@ -146,6 +147,8 @@ export interface RefundPlanTotals {
     discounts: number;
     /** Σ selected cart fees, tax excluded. */
     fees: number;
+    /** The order's shipping when selected, tax excluded; 0 otherwise. */
+    shipping: number;
     tax: number;
     tip: number;
     total: number;

package/dist/actions/get-remaining-refundable-quantities/mock.js

@@ -5,6 +5,7 @@ export const mockGetRemainingRefundableQuantities = async (_params) => {
         lineItems: {},
         customSales: {},
         cartFees: {},
+        shipping: 0,
         tips: {},
         reservations: {},
         timestamp: new Date().toISOString(),

package/dist/actions/get-remaining-refundable-quantities/types.d.ts

@@ -11,6 +11,11 @@ export interface GetRemainingRefundableQuantitiesResponse {
      * 0/1 semantics: `1` = still refundable, `0` = already refunded.
      */
     cartFees: Record<string, number>;
+    /**
+     * The order's shipping: `1` = still refundable, `0` = already refunded or the order has none.
+     * Refunded with `itemKey: 'shipping'`, all or nothing.
+     */
+    shipping: number;
     /**
      * Remaining refundable tips, keyed by the paying method's
      * `transactionId` — the same key `processPartialRefund` takes for

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

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

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

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

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

@@ -0,0 +1,3 @@
+import type { GetShippingOptions } from './types';
+/** Standalone mock: the demo store's zones run through the real resolver, as the website would. */
+export declare const mockGetShippingOptions: GetShippingOptions;

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

@@ -0,0 +1,15 @@
+import { MOCK_SHIPPING_ZONES, mockShippingOptions } from '../../demo/shipping';
+/** Standalone mock: the demo store's zones run through the real resolver, as the website would. */
+export const mockGetShippingOptions = async () => {
+    console.log('[Mock] getShippingOptions called');
+    const { resolution, options } = mockShippingOptions();
+    const message = resolution.message ??
+        (options.length === 0 && resolution.reason === 'NO_COVERAGE' ? 'Sorry, we only ship within Canada.' : null);
+    return {
+        required: MOCK_SHIPPING_ZONES.length > 0,
+        options,
+        reason: resolution.reason,
+        message,
+        timestamp: new Date().toISOString(),
+    };
+};