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

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

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

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

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

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

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

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

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

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

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

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

@@ -0,0 +1,13 @@
+// Resume Checkout Types
+//
+// The RETURN LEG of an online checkout. Some payment methods — and 3-D Secure
+// on a card — take the shopper away to their bank or wallet and send them back
+// to `returnUrl` on a FRESH PAGE LOAD. The payment is not finished at that
+// point: the provider hands the browser a one-time result in the URL, and it
+// has to be handed back to the provider to complete the charge.
+//
+// `startCheckout` cannot do this. It ran in the page that is now gone.
+//
+// Served ONLY by the storefront runtime (a published website), like
+// `startCheckout`. On a register it does not exist.
+export {};

package/dist/index.d.ts

@@ -44,6 +44,7 @@ export declare const command: {
     readonly createPaymentLink: import(".").CreatePaymentLink;
     readonly chargeMoto: import(".").ChargeMoto;
     readonly startCheckout: import(".").StartCheckout;
+    readonly resumeCheckout: import(".").ResumeCheckout;
     readonly addCustomerNote: import(".").AddCustomerNote;
     readonly removeCustomerNote: import(".").RemoveCustomerNote;
     readonly removeCustomerFromCart: import(".").RemoveCustomerFromCart;
@@ -180,6 +181,7 @@ export type { IntegrationPayment, IntegrationPaymentParams, IntegrationPaymentRe
 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 { ResumeCheckout, ResumeCheckoutParams, ResumeCheckoutResponse, ResumeCheckoutResult, } from './actions/resume-checkout/types';
 export type { AddCustomerNote, AddCustomerNoteParams, AddCustomerNoteResponse, } from './actions/add-customer-note/types';
 export type { RemoveCustomerNote, RemoveCustomerNoteParams, RemoveCustomerNoteResponse, } from './actions/remove-customer-note/types';
 export type { RemoveCustomerFromCart, RemoveCustomerFromCartResponse } from './actions/remove-customer-from-cart/types';

package/dist/index.js

@@ -44,6 +44,7 @@ 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 { resumeCheckout } from './actions/resume-checkout/action';
 // Customer Actions
 import { addCustomerNote } from './actions/add-customer-note/action';
 import { removeCustomerNote } from './actions/remove-customer-note/action';
@@ -182,6 +183,7 @@ export const command = {
     createPaymentLink,
     chargeMoto,
     startCheckout,
+    resumeCheckout,
     // Customer Actions
     addCustomerNote,
     removeCustomerNote,

package/dist/projects/render/mocks.js

@@ -32,6 +32,7 @@ import { mockGetCashRoundingAmount } from '../../actions/get-cash-rounding-amoun
 import { mockCreatePaymentLink } from '../../actions/create-payment-link/mock';
 import { mockChargeMoto } from '../../actions/charge-moto/mock';
 import { mockStartCheckout } from '../../actions/start-checkout/mock';
+import { mockResumeCheckout } from '../../actions/resume-checkout/mock';
 import { mockGetTimeClockStatus } from '../../actions/get-time-clock-status/mock';
 import { mockClearCart } from '../../actions/clear-cart/mock';
 import { mockDeleteParkedOrder } from '../../actions/delete-parked-order/mock';
@@ -130,6 +131,7 @@ export const RENDER_MOCKS = {
     createPaymentLink: mockCreatePaymentLink,
     chargeMoto: mockChargeMoto,
     startCheckout: mockStartCheckout,
+    resumeCheckout: mockResumeCheckout,
     clearCart: mockClearCart,
     deleteParkedOrder: mockDeleteParkedOrder,
     voidOrder: mockVoidOrder,

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

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

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

@@ -12,6 +12,18 @@ export interface PaymentCompletedPayload {
     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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@final-commerce/command-frame",
-  "version": "0.8.0-online.1",
+  "version": "0.8.0-online.2",
   "description": "Commands Frame library",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",