@m2c/checkout 0.1.1 → 0.1.3

package/README.md

@@ -99,6 +99,14 @@ polls the status source to a terminal result.
 `storageKey`, default `m2c.checkout`) before navigating. It is read and cleared
 on the return page, so a refresh does not re-poll a stale checkout.
 
+If the customer instead presses **Back** from the vendor checkout, the
+originating page is restored (from the back-forward cache) and the `start` /
+`startFromSession` promise resolves `{ status: 'window_closed', requestId }`.
+This is an ambiguous browser outcome, not a payment status; keep using the
+webhook/status source as the truth. The resume record remains in storage, so if
+the customer goes Forward and completes the hosted checkout, the return page can
+still call `resume()` and resolve the terminal payment result.
+
 ### Popup / new-tab launch
 
 For apps that must keep the original page alive, such as web games, opt into a

package/dist/client.d.ts

@@ -18,6 +18,7 @@ declare class CheckoutClientImpl implements CheckoutClient {
     private persistAndLaunch;
     private prepareAsyncLaunchWindow;
     private waitForReturnResult;
+    private armRedirectWindowClosed;
     private publishReturnResult;
     private launchCheckout;
     private openBlankCheckoutWindow;

package/dist/client.js

@@ -13,11 +13,6 @@ const WINDOW_CLOSED_OBSERVABILITY_GRACE_MS = 300;
 const WINDOW_CLOSED_AFTER_FOCUS_GRACE_MS = 500;
 const RETURN_RESULT_CHECK_INTERVAL_MS = 100;
 const WINDOW_CLOSED_BEFORE_LAUNCH_MESSAGE = 'checkout window was closed before launch';
-// Same-tab redirect tears down the page, so `start*` never resolves in that
-// execution context; the result is obtained from `resume()` on the return page.
-// Returning one shared never-settling promise keeps the documented
-// Promise<CheckoutResult> return type without leaking.
-const PENDING_UNTIL_REDIRECT = new Promise(() => { });
 /** Create a headless checkout client. Safe to import in SSR; lifecycle methods need a DOM. */
 export function createClient(config) {
     return new CheckoutClientImpl(normalizeConfig(config));
@@ -216,12 +211,7 @@ class CheckoutClientImpl {
     }
     waitForReturnResult(requestId) {
         if (this.config.launchMode === 'redirect') {
-            return {
-                promise: PENDING_UNTIL_REDIRECT,
-                cancel: () => { },
-                resolveWindowClosed: () => { },
-                watchWindowClosed: () => { },
-            };
+            return this.armRedirectWindowClosed(requestId);
         }
         return listenForReturnResult(this.config.storageKey, requestId, this.config.storage, this.config.returnTimeoutMs, (result) => {
             this.requestId = result.requestId;
@@ -237,6 +227,54 @@ class CheckoutClientImpl {
             this.setState(result.status);
         });
     }
+    // Redirect mode tears the page down after navigate, so the happy-path result
+    // comes from resume() on success_url/cancel_url. But if the customer presses
+    // Back from the vendor checkout, the originating page is restored (back-forward
+    // cache) frozen in `awaiting_return` with nothing listening. Arm a page-restore
+    // listener so that case resolves instead of hanging forever.
+    armRedirectWindowClosed(requestId) {
+        let settled = false;
+        let triggered = false;
+        let removeListeners = () => { };
+        let resolveResult;
+        const promise = new Promise((resolve) => {
+            resolveResult = resolve;
+        });
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            removeListeners();
+            resolveResult(result);
+        };
+        const settleWindowClosed = () => {
+            this.requestId = requestId;
+            this.setState('window_closed');
+            settle({ status: 'window_closed', requestId });
+        };
+        // `state === 'awaiting_return'` is the real gate: in same-tab redirect mode
+        // the originating page is usually shown again via Back navigation. That is
+        // an ambiguous browser outcome, not a payment status, so keep the resume
+        // record for a later success_url/cancel_url return.
+        const onRestore = () => {
+            if (triggered || settled || this.state !== 'awaiting_return')
+                return;
+            triggered = true;
+            settleWindowClosed();
+        };
+        removeListeners = listenForPageRestore(onRestore);
+        return {
+            promise,
+            cancel: () => {
+                if (settled)
+                    return;
+                settled = true;
+                removeListeners();
+            },
+            resolveWindowClosed: () => { },
+            watchWindowClosed: () => { },
+        };
+    }
     publishReturnResult(result) {
         publishReturnResult(this.config.storageKey, result, this.config.storage);
     }
@@ -670,6 +708,40 @@ function listenForWindowClosed(win, onClosed, onUnobservable) {
     check();
     return stop;
 }
+// Fire `onRestore` when the originating page is shown again - a `pageshow`
+// (including back-forward cache restores) or the document becoming visible. The
+// caller gates on lifecycle state, so an unconditional callback is safe here.
+function listenForPageRestore(onRestore) {
+    try {
+        if (typeof globalThis.addEventListener !== 'function') {
+            return () => { };
+        }
+        const handler = () => onRestore();
+        globalThis.addEventListener('pageshow', handler);
+        const doc = globalThis.document;
+        let visibilityListener;
+        if (doc && typeof doc.addEventListener === 'function') {
+            visibilityListener = () => {
+                if (doc.visibilityState === 'visible') {
+                    onRestore();
+                }
+            };
+            doc.addEventListener('visibilitychange', visibilityListener);
+        }
+        return () => {
+            try {
+                globalThis.removeEventListener('pageshow', handler);
+                if (visibilityListener && doc && typeof doc.removeEventListener === 'function') {
+                    doc.removeEventListener('visibilitychange', visibilityListener);
+                }
+            }
+            catch { }
+        };
+    }
+    catch {
+        return () => { };
+    }
+}
 function listenForOpenerFocus(onFocus) {
     try {
         if (typeof globalThis.addEventListener !== 'function') {

package/dist/types.d.ts

@@ -7,7 +7,10 @@ import type { M2CCheckoutError } from './errors.js';
 export type ClientStatus = 'processing' | 'completed' | 'failed' | 'canceled';
 /** Lifecycle states the SDK passes through. Drives the merchant's progress UI. */
 export type CheckoutState = 'idle' | 'creating' | 'ready' | 'launching' | 'awaiting_return' | 'returned' | 'polling' | 'completed' | 'failed' | 'canceled' | 'pending_timeout' | 'window_closed' | 'error';
-/** Terminal outcome of a checkout. `pending_timeout` resolves; it does not reject. */
+/**
+ * Terminal outcome of a checkout. `pending_timeout` and `window_closed` resolve;
+ * they do not reject.
+ */
 export type CheckoutResult = {
     status: 'completed';
     requestId: string;

package/dist/validate.d.ts

@@ -1,4 +1,5 @@
 export declare const MAX_TRANSACTION_VALUE = 5000000000;
+export declare const MIN_TRANSACTION_VALUE = 0.000001;
 export declare const UUID_RE: RegExp;
 /**
  * UTF-8 byte length. The server measures string limits in bytes (Go `len`), so

package/dist/validate.js

@@ -3,6 +3,11 @@ import { M2CCheckoutError } from './errors.js';
 // contract violation fails client-side with a clear message instead of a
 // round-trip and a generic 400.
 export const MAX_TRANSACTION_VALUE = 5000000000;
+// Smallest positive value the server keeps: it rounds major units to micro-units
+// (1e-6) internally, so a positive value below one micro-unit becomes 0 at the
+// storage boundary and is rejected. Mirror that floor instead of taking the
+// round-trip for a generic 400.
+export const MIN_TRANSACTION_VALUE = 0.000001;
 const MAX_RETURN_URL_BYTES = 2048;
 const MAX_CHECKOUT_URL_BYTES = 4096;
 const MAX_DESCRIPTION_BYTES = 256;
@@ -48,6 +53,9 @@ export function assertTransactionValue(value) {
     if (value <= 0) {
         throw invalid('transactionValue must be greater than 0');
     }
+    if (value < MIN_TRANSACTION_VALUE) {
+        throw invalid(`transactionValue must be at least ${MIN_TRANSACTION_VALUE}`);
+    }
     if (value > MAX_TRANSACTION_VALUE) {
         throw invalid(`transactionValue must be at most ${MAX_TRANSACTION_VALUE} major units`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m2c/checkout",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Headless browser checkout SDK for M2C: run an auction, redirect to the winning vendor's hosted checkout, and reflect conversion status.",
   "type": "module",
   "engines": {