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

package/dist/CommonTypes.d.ts

@@ -181,9 +181,23 @@ export interface CFOutletInfo {
         state?: string;
         postCode?: string;
     };
+    address2?: string;
     city?: string;
     state?: string;
     country?: string;
+    postCode?: string;
+    phone?: string;
+    /** Short display alias, when the merchant set one (e.g. `DTWN`). */
+    alias?: string;
+    /**
+     * Whether this location can take an ONLINE payment. Storefront only — it is
+     * absent on a register, where it has no meaning.
+     *
+     * `false` means the outlet has no completed payment connection, so starting a
+     * checkout against it WILL fail. A pickup picker must not offer it as a
+     * selectable location, or must show it as unavailable.
+     */
+    connected?: boolean;
 }
 export interface CFContextManage {
     user: unknown;

package/dist/actions/attach-checkout-contact/action.d.ts

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

package/dist/actions/attach-checkout-contact/action.js

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

package/dist/actions/attach-checkout-contact/mock.d.ts

@@ -0,0 +1,15 @@
+import type { AttachCheckoutContact } from './types';
+/**
+ * Standalone mock of attaching contact to an online order.
+ *
+ * It mirrors the one REFUSAL the real command makes — a missing email — because
+ * that is the mistake a builder actually hits, and a mock that accepted anything
+ * would let a checkout screen look finished and lose receipts on the published
+ * site.
+ *
+ * It does NOT mirror "no order to attach to". The real command answers
+ * `attached: false` there rather than throwing, precisely so a flow can call it
+ * optimistically and still let the shopper pay; the mock always has a checkout
+ * to attach to, so it reports `true`.
+ */
+export declare const mockAttachCheckoutContact: AttachCheckoutContact;

package/dist/actions/attach-checkout-contact/mock.js

@@ -0,0 +1,22 @@
+/**
+ * Standalone mock of attaching contact to an online order.
+ *
+ * It mirrors the one REFUSAL the real command makes — a missing email — because
+ * that is the mistake a builder actually hits, and a mock that accepted anything
+ * would let a checkout screen look finished and lose receipts on the published
+ * site.
+ *
+ * It does NOT mirror "no order to attach to". The real command answers
+ * `attached: false` there rather than throwing, precisely so a flow can call it
+ * optimistically and still let the shopper pay; the mock always has a checkout
+ * to attach to, so it reports `true`.
+ */
+export const mockAttachCheckoutContact = async (params) => {
+    console.log('[Mock] attachCheckoutContact called', params);
+    if (!params)
+        throw new Error('Params required');
+    if (!params.email || !params.email.trim()) {
+        throw new Error('attachCheckoutContact: email is required — it is where the receipt goes');
+    }
+    return { attached: true, timestamp: new Date().toISOString() };
+};

package/dist/actions/attach-checkout-contact/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Guest contact for the order. There is no shopper account, so this is the only
+ * way to reach them — `email` is where the receipt goes and is required.
+ */
+export interface AttachCheckoutContactParams {
+    email: string;
+    name?: string;
+    phone?: string;
+    /** Defaults to the outlet the storefront booted against. */
+    outletId?: string;
+}
+export interface AttachCheckoutContactResponse {
+    /**
+     * `false` means there was nothing to attach to — no checkout had been started
+     * for this cart. It is NOT a failure to record the contact on an order that
+     * exists, and it never means the shopper was charged.
+     */
+    attached: boolean;
+    timestamp: string;
+}
+/**
+ * Put the shopper's contact on the order `startCheckout` already created.
+ *
+ * Call it BEFORE paying, whenever the email is known — on blur, on submit, or
+ * as the shopper leaves the contact step. It reuses the order's idempotency
+ * key, so it updates that order rather than creating a second one.
+ *
+ * SAFE TO CALL TWICE. The server only ever ADDS contact to an order that has
+ * none, so a later call cannot redirect a receipt that was already addressed.
+ *
+ * NEVER THROWS FOR A MISSING ORDER. Failing to record an email must not stop a
+ * payment the shopper is trying to make, so the caller gets `attached: false`
+ * and can carry on to pay.
+ */
+export type AttachCheckoutContact = (params: AttachCheckoutContactParams) => Promise<AttachCheckoutContactResponse>;

package/dist/actions/attach-checkout-contact/types.js

@@ -0,0 +1,16 @@
+// Attach Checkout Contact Types
+//
+// The second half of the online checkout. `startCheckout` creates the order and
+// mounts the payment fields the moment a shopper ARRIVES; this puts their email
+// on that same order once they have typed it.
+//
+// WHY THESE ARE TWO COMMANDS. The card fields cannot render without a payment
+// session, a session needs a server-priced amount, and an amount needs an order.
+// So the order has to exist before the shopper has typed anything. Demanding an
+// email first is what forced the old "fill the form, then see the card fields"
+// checkout — and it also meant every cart edit minted a NEW order, because the
+// idempotency key moved with the cart.
+//
+// Served ONLY by the storefront runtime (a published website), like
+// `startCheckout` itself. On a register it does not exist.
+export {};

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

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

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

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

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

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

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

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

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

@@ -15,5 +15,9 @@ import { GetRefundPlan } from './types';
  * and no company cash-rounding setting, so it always describes a FULL refund
  * with `rounding: 0` and no cash `payout`. Against real kaching the allocation
  * tracks the live selection and carries the drawer snap.
+ *
+ * `rows` / `allocation.breakdown` follow the engine's reading of the order
+ * (`line.total` includes the line's tax) but prorate by plain quantity share;
+ * the engine's remainder carry across earlier partial refunds is not modelled.
  */
 export declare const mockGetRefundPlan: GetRefundPlan;

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

@@ -1,4 +1,5 @@
 import { MOCK_ORDERS } from '../../demo/database';
+import { mockRefundBreakdown, mockRefundRows } from './mockRows';
 /**
  * Demo derivation of the runtime `getRefundPlan`. Builds the per-source rows
  * from the mock order's `paymentMethods`, mirroring the runtime's capacity
@@ -15,6 +16,10 @@ import { MOCK_ORDERS } from '../../demo/database';
  * and no company cash-rounding setting, so it always describes a FULL refund
  * with `rounding: 0` and no cash `payout`. Against real kaching the allocation
  * tracks the live selection and carries the drawer snap.
+ *
+ * `rows` / `allocation.breakdown` follow the engine's reading of the order
+ * (`line.total` includes the line's tax) but prorate by plain quantity share;
+ * the engine's remainder carry across earlier partial refunds is not modelled.
  */
 export const mockGetRefundPlan = async (params) => {
     console.log('[Mock] getRefundPlan called', params);
@@ -62,16 +67,19 @@ export const mockGetRefundPlan = async (params) => {
         requiresGiftCardDestination: s.paymentType === 'redeem',
     }));
     const budget = legs.reduce((sum, l) => sum + l.amount, 0);
+    const rows = mockRefundRows(order);
     return {
         success: true,
         orderId: order._id,
         sources,
+        rows,
         allocation: {
             budget,
             // No cash rounding in the demo, so the goods value and the budget agree.
             itemTotal: budget,
             rounding: 0,
             legs,
+            breakdown: mockRefundBreakdown(rows, params?.items),
         },
         // Demo: no prior refunds, so remaining = captured minus the non-revenue load.
         remainingRefundable: Math.max(0, totalCaptured - nonRefundableLiability),

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

@@ -0,0 +1,6 @@
+import type { CFActiveOrder } from '../../CommonTypes';
+import type { GetRefundPlanParams, RefundPlanBreakdown, RefundPlanRow } from './types';
+/** Every row of a demo order. The demo has no refund ledger, so everything is refundable. */
+export declare function mockRefundRows(order: CFActiveOrder): RefundPlanRow[];
+/** The selection's breakdown; no `items` means everything, like the demo's full-refund legs. */
+export declare function mockRefundBreakdown(rows: RefundPlanRow[], items?: GetRefundPlanParams['items']): RefundPlanBreakdown;

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

@@ -0,0 +1,114 @@
+// Demo derivation of `getRefundPlan`'s `rows` and `allocation.breakdown`, for
+// local/standalone mode only. See the note on `mockGetRefundPlan`.
+const minor = (v) => Math.round(Number(v ?? 0)) || 0;
+/** A line's whole-quantity money, reading `total` as tax-inclusive (the engine's reading). */
+function lineAmounts(line) {
+    const tax = minor(line.totalTax);
+    const itemDiscount = (line.discount?.itemDiscounts ?? []).reduce((s, d) => s + minor(d.amount), 0);
+    const cartDiscount = minor(line.discount?.cartDiscount?.amount);
+    const net = Math.max(0, minor(line.total) - tax);
+    const taxes = (line.taxes ?? []).map((t) => ({
+        name: String(t.name ?? 'Tax'),
+        percentage: t.percentage,
+        amount: minor(t.amount),
+    }));
+    return { subtotal: net + itemDiscount + cartDiscount, itemDiscount, cartDiscount, tax, taxes, total: net + tax };
+}
+function scale(a, share) {
+    if (share >= 1)
+        return a;
+    const r = (n) => Math.round(n * share);
+    const out = {
+        subtotal: r(a.subtotal),
+        itemDiscount: r(a.itemDiscount),
+        cartDiscount: r(a.cartDiscount),
+        tax: r(a.tax),
+        taxes: a.taxes.map((t) => ({ ...t, amount: r(t.amount) })),
+    };
+    return { ...out, total: out.subtotal - out.itemDiscount - out.cartDiscount + out.tax };
+}
+/** Every row of a demo order. The demo has no refund ledger, so everything is refundable. */
+export function mockRefundRows(order) {
+    const rows = [];
+    for (const li of order.lineItems ?? []) {
+        const itemKey = String(li.internalId || li.variantId || '');
+        if (!itemKey || !(li.quantity > 0))
+            continue;
+        rows.push({
+            type: 'product',
+            itemKey,
+            label: String(li.name ?? 'Item'),
+            ...(li.sku ? { sku: li.sku } : {}),
+            ...(li.attributes ? { attributes: li.attributes } : {}),
+            quantity: li.quantity,
+            refundableQuantity: li.quantity,
+            amounts: lineAmounts(li),
+        });
+    }
+    for (const cs of order.customSales ?? []) {
+        if (!cs.customSaleId || !(cs.quantity > 0))
+            continue;
+        rows.push({
+            type: 'customSale',
+            itemKey: cs.customSaleId,
+            label: String(cs.name ?? 'Custom sale'),
+            quantity: cs.quantity,
+            refundableQuantity: cs.quantity,
+            amounts: lineAmounts(cs),
+        });
+    }
+    for (const fee of order.cartFees ?? []) {
+        const amount = minor(fee.amount);
+        const tax = minor(fee.tax);
+        rows.push({
+            type: 'fee',
+            itemKey: String(fee.id),
+            label: String(fee.label || 'Cart fee'),
+            quantity: 1,
+            refundableQuantity: 1,
+            amounts: { subtotal: amount, itemDiscount: 0, cartDiscount: 0, tax, taxes: [], total: amount + tax },
+        });
+    }
+    for (const pm of order.paymentMethods ?? []) {
+        const tip = minor(pm.tip?.amount);
+        if (tip <= 0)
+            continue;
+        rows.push({
+            type: 'tip',
+            itemKey: pm.transactionId,
+            label: 'Tip',
+            paymentType: pm.paymentType,
+            quantity: 1,
+            refundableQuantity: 1,
+            amounts: { subtotal: tip, itemDiscount: 0, cartDiscount: 0, tax: 0, taxes: [], total: tip },
+        });
+    }
+    return rows;
+}
+/** The selection's breakdown; no `items` means everything, like the demo's full-refund legs. */
+export function mockRefundBreakdown(rows, items) {
+    const picked = new Map((items ?? []).map((i) => [i.itemKey, i.quantity]));
+    const selected = rows
+        .map((row) => {
+        const quantity = items?.length
+            ? Math.min(picked.get(row.itemKey) ?? 0, row.refundableQuantity)
+            : row.refundableQuantity;
+        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 };
+    for (const r of selected) {
+        const a = r.amounts;
+        if (r.type === 'fee')
+            totals.fees += a.subtotal;
+        else if (r.type === 'tip')
+            totals.tip += a.subtotal;
+        else {
+            totals.items += a.subtotal;
+            totals.discounts += a.itemDiscount + a.cartDiscount;
+        }
+        totals.tax += a.tax;
+        totals.total += a.total;
+    }
+    return { rows: selected, totals };
+}

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

@@ -79,6 +79,81 @@ export interface RefundPlanLeg {
         rounding: number;
     };
 }
+export type RefundPlanRowType = 'product' | 'customSale' | 'fee' | 'tip';
+/** One tax rate's share of a row's refund (minor units). */
+export interface RefundPlanTaxLine {
+    name: string;
+    /** Decimal rate as stored on the order (e.g. `0.15`), when the order recorded one. */
+    percentage?: number;
+    amount: number;
+}
+/**
+ * The money a row refunds, split the way a receipt shows it. Every field is
+ * minor units and already rounded; `subtotal − itemDiscount − cartDiscount +
+ * tax === total` always holds. DISPLAY IT — never re-add or prorate it.
+ */
+export interface RefundPlanAmounts {
+    /** Before discounts, tax excluded. For a tip row, the tip itself. */
+    subtotal: number;
+    /** Per-item discounts on the refunded quantity (positive). */
+    itemDiscount: number;
+    /** Cart discount share on the refunded quantity (positive). */
+    cartDiscount: number;
+    /** Tax on the refunded quantity. Zero for a tip. */
+    tax: number;
+    /** `tax` per rate — the price breakdown's tax lines. */
+    taxes: RefundPlanTaxLine[];
+    /** What the row refunds. */
+    total: number;
+}
+/**
+ * One refundable row of the order — a line item, custom sale, cart fee or tip —
+ * served ready to render. Rows with nothing left to refund are not listed.
+ */
+export interface RefundPlanRow {
+    type: RefundPlanRowType;
+    /** The key `items[].itemKey` takes, for this call and for `processPartialRefund`. */
+    itemKey: string;
+    /** Line or fee name; `Tip` for a tip. */
+    label: string;
+    /** Product lines only, when the order recorded them. */
+    sku?: string;
+    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: number;
+    /** Quantity still refundable — the stepper's max. */
+    refundableQuantity: number;
+    /** The money for refunding ALL of `refundableQuantity`. */
+    amounts: RefundPlanAmounts;
+}
+/** One selected row and what refunding the selected quantity of it moves. */
+export interface RefundPlanSelectedRow {
+    type: RefundPlanRowType;
+    itemKey: string;
+    quantity: number;
+    amounts: RefundPlanAmounts;
+}
+/**
+ * The selection's goods value broken down for display. Minor units;
+ * `items − discounts + fees + tax + tip === total === allocation.itemTotal`.
+ */
+export interface RefundPlanTotals {
+    /** Σ selected line subtotals (before discounts, tax excluded). */
+    items: number;
+    /** Σ item + cart discounts on the selected lines (positive). */
+    discounts: number;
+    /** Σ selected cart fees, tax excluded. */
+    fees: number;
+    tax: number;
+    tip: number;
+    total: number;
+}
+export interface RefundPlanBreakdown {
+    rows: RefundPlanSelectedRow[];
+    totals: RefundPlanTotals;
+}
 /**
  * The engine's own allocation of the CURRENT refund selection across the
  * order's captures — what a flow renders and submits instead of computing a
@@ -106,11 +181,25 @@ export interface RefundPlanAllocation {
     rounding: number;
     /** One leg per source that receives money. Submit as `legs`, unchanged. */
     legs: RefundPlanLeg[];
+    /**
+     * What the selection refunds, per row and in total — the numbers a refund
+     * dialog's rows and footer render. Optional so an older runtime still
+     * type-checks; kaching 1.12.1+ always sends it.
+     */
+    breakdown?: RefundPlanBreakdown;
 }
 export interface GetRefundPlanResponse {
     success: boolean;
     orderId: string;
     sources: RefundPlanSource[];
+    /**
+     * Every row still refundable on the order, with the money for refunding all
+     * of it — what a refund dialog lists before anything is selected. Replaces
+     * reading line totals off the order and deciding whether they include tax.
+     * Optional so an older runtime still type-checks; kaching 1.12.1+ always
+     * sends it.
+     */
+    rows?: RefundPlanRow[];
     /**
      * Ready-to-submit allocation of the current selection. Present only when a
      * refund selection exists on the active order. See {@link RefundPlanAllocation}.

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

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

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

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

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

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

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

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

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

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