@morefin/cashier-bootstrapper 0.3.5 → 0.3.7

package/README.md

@@ -100,6 +100,33 @@ new CashierBootstrapper('#cashier-root', {
 });
 ```
 
+The bootstrapper calls `onReady` after the cashier iframe has registered its runtime message listener. If the cashier build does not support that ready signal, the bootstrapper falls back to iframe load after 3 seconds to preserve existing integrations.
+
+For asynchronous merchant configuration, return or await the async work from `onReady`. The cashier stays in its host-configuration loading state until the returned promise completes.
+
+```typescript
+import { CashierBootstrapper } from '@morefin/cashier-bootstrapper';
+
+new CashierBootstrapper('#cashier-root', {
+  properties: { environment: CASHIER_ENVIRONMENT }
+}, async api => {
+  const css = await fetch('/merchant-cashier-theme.css').then(response => response.text());
+  api.setCss(css);
+});
+```
+
+Avoid starting async setup without returning it. In this example, the bootstrapper cannot wait for the timer, so the cashier may become visible before the CSS is applied:
+
+```typescript
+new CashierBootstrapper('#cashier-root', {
+  properties: { environment: CASHIER_ENVIRONMENT }
+}, api => {
+  setTimeout(() => {
+    api.setCss(css);
+  }, 1000);
+});
+```
+
 ### Transaction Result Callbacks
 
 ```typescript
@@ -140,11 +167,13 @@ Iframe-based embed that loads the cashier URL and exposes runtime controls once
 - `container: string | HTMLElement | null | undefined` - Where the iframe is appended. If omitted, `config.properties.container` is used (falling back to `document.body`).
 - `config?: CashierIframeConfig` - Request params and iframe properties. `properties.environment` is required.
 - `config.callbacks?: CashierCallbacks` - Host callback handlers for cashier result events.
-- `onReady?: (api: CashierIframeApi) => void` - Called when the iframe loads; exposes helpers:
+- `onReady?: (api: CashierIframeApi) => void | Promise<void>` - Called when the cashier iframe is ready for runtime messages; exposes helpers:
   - `api.setCss(css: string)` – inject CSS inside the cashier iframe
   - `api.updateData(data: object)` – post updated `APP_DATA` to the cashier
   - `api.pause()` / `api.resume()` – forward pause/resume signals
 
+If `onReady` returns a promise, the bootstrapper waits for it before notifying the cashier that host configuration is completed. Return or await asynchronous CSS/data setup so the cashier does not render before merchant configuration is applied.
+
 ## Types
 
 ```typescript

package/dist/index.d.ts

@@ -18,6 +18,10 @@ export declare class CashierBootstrapper {
     private redirectOverlayPanel?;
     private redirectOverlayIframe?;
     private overlayPositionSyncHandler?;
+    private managedRedirectTab?;
+    private managedRedirectTabTransactionId?;
+    private managedRedirectTabCheckIntervalId?;
+    private iframeLoadFallbackTimeoutId?;
     private origin;
     private ready;
     private readonly fullConfig;
@@ -26,10 +30,12 @@ export declare class CashierBootstrapper {
     private readonly onReady?;
     private readonly callbacks?;
     private readonly messageListener;
-    constructor(container: string | HTMLElement | null | undefined, config?: CashierIframeConfig, onReady?: (api: CashierIframeApi) => void);
+    constructor(container: string | HTMLElement | null | undefined, config?: CashierIframeConfig, onReady?: (api: CashierIframeApi) => void | Promise<void>);
     private bootstrapIframe;
     private createIframeShell;
     private handleLoad;
+    private completeReady;
+    private runHostReadyCallback;
     private postMessage;
     private handleIframeMessage;
     private handleCashierResultEvent;
@@ -41,6 +47,10 @@ export declare class CashierBootstrapper {
     private normalizeRedirectTarget;
     private normalizeRedirectMethod;
     private normalizeRedirectParameters;
+    private openManagedRedirectTab;
+    private openManagedRedirectTabWithPost;
+    private trackManagedRedirectTab;
+    private clearManagedRedirectTabWatcher;
     private openPopupWithPost;
     private writePostFormToWindow;
     private submitPostForm;

package/dist/index.js

@@ -2,6 +2,9 @@ const DEFAULT_IFRAME_ALLOW = 'geolocation *;camera *;payment *;clipboard-read *;
 const CASHIER_PATH = '/cashier';
 const FINGERPRINT_CDN = 'https://cdn.jsdelivr.net/npm/@fingerprintjs/fingerprintjs@4/dist/fp.min.js';
 const CASHIER_REDIRECT_EVENT = 'CASHIER_REDIRECT';
+const CASHIER_REDIRECT_TAB_CLOSED_EVENT = 'CASHIER_REDIRECT_TAB_CLOSED';
+const CASHIER_READY_EVENT = 'CASHIER_READY';
+const CASHIER_HOST_CONFIG_DONE_EVENT = 'CASHIER_HOST_CONFIG_DONE';
 const TOP_URL_REPLACE_EVENT = 'TOP_URL_REPLACE';
 const CASHIER_IFRAME_OVERLAY_CLOSE_EVENT = 'CASHIER_IFRAME_OVERLAY_CLOSE';
 const CASHIER_RESULT_EVENT = 'CASHIER_RESULT';
@@ -212,8 +215,8 @@ export class CashierBootstrapper {
         const src = buildIframeUrl(this.host, this.fullConfig.requestParams, this.allowedHostnames, fp);
         this.origin = getOriginFromUrl(src, this.allowedHostnames);
         if (this.iframe) {
-            this.iframe.src = src;
             this.iframe.onload = () => this.handleLoad();
+            this.iframe.src = src;
         }
     }
     createIframeShell(container) {
@@ -240,11 +243,33 @@ export class CashierBootstrapper {
         return iframe;
     }
     handleLoad() {
+        if (this.ready)
+            return;
+        if (this.iframeLoadFallbackTimeoutId !== undefined)
+            return;
+        this.iframeLoadFallbackTimeoutId = setTimeout(() => this.completeReady(), 3000);
+    }
+    completeReady() {
         if (this.ready)
             return;
         this.ready = true;
-        if (this.onReady) {
-            this.onReady(this.api());
+        if (this.iframeLoadFallbackTimeoutId !== undefined) {
+            clearTimeout(this.iframeLoadFallbackTimeoutId);
+            this.iframeLoadFallbackTimeoutId = undefined;
+        }
+        void this.runHostReadyCallback();
+    }
+    async runHostReadyCallback() {
+        try {
+            if (this.onReady) {
+                await this.onReady(this.api());
+            }
+        }
+        catch (err) {
+            console.error('Host ready callback threw an error.', err);
+        }
+        finally {
+            this.postMessage(CASHIER_HOST_CONFIG_DONE_EVENT, {});
         }
     }
     postMessage(eventType, payload) {
@@ -266,6 +291,12 @@ export class CashierBootstrapper {
             return;
         }
         const { eventType, payload } = event.data;
+        if (eventType === CASHIER_READY_EVENT) {
+            if (sourceIsMainCashierIframe) {
+                this.completeReady();
+            }
+            return;
+        }
         if (eventType === CASHIER_IFRAME_OVERLAY_CLOSE_EVENT) {
             if (sourceIsOverlayIframe) {
                 this.closeProviderRedirectOverlay();
@@ -335,6 +366,7 @@ export class CashierBootstrapper {
         const redirectTarget = this.normalizeRedirectTarget(redirectPayload.target);
         const redirectMethod = this.normalizeRedirectMethod(redirectPayload.method);
         const redirectParameters = this.normalizeRedirectParameters(redirectPayload.parameters);
+        const transactionId = this.asString(redirectPayload.transactionId);
         if (typeof redirectUrl !== 'string' || redirectUrl.trim() === '') {
             return;
         }
@@ -354,12 +386,12 @@ export class CashierBootstrapper {
             case 'tab':
                 console.log('[CashierBootstrapper] Handling redirect target "tab".', { redirectUrl, redirectMethod, redirectParameters });
                 if (redirectMethod === 'POST') {
-                    if (!this.openPopupWithPost(redirectUrl, redirectParameters)) {
+                    if (!this.openManagedRedirectTabWithPost(redirectUrl, redirectParameters, transactionId)) {
                         this.submitPostForm(redirectUrl, redirectParameters, '_blank');
                     }
                 }
                 else {
-                    window.open(redirectUrl, '_blank', 'noopener,noreferrer');
+                    this.openManagedRedirectTab(redirectUrl, transactionId);
                 }
                 break;
             case 'window':
@@ -492,6 +524,55 @@ export class CashierBootstrapper {
             return acc;
         }, {});
     }
+    openManagedRedirectTab(url, transactionId) {
+        if (typeof window === 'undefined') {
+            return false;
+        }
+        const popup = window.open(url, '_blank');
+        if (!popup) {
+            return false;
+        }
+        this.trackManagedRedirectTab(popup, transactionId);
+        return true;
+    }
+    openManagedRedirectTabWithPost(url, parameters, transactionId) {
+        if (typeof window === 'undefined') {
+            return false;
+        }
+        const popup = window.open('', '_blank');
+        if (!popup) {
+            return false;
+        }
+        if (!this.writePostFormToWindow(popup, url, parameters)) {
+            return false;
+        }
+        this.trackManagedRedirectTab(popup, transactionId);
+        return true;
+    }
+    trackManagedRedirectTab(tab, transactionId) {
+        this.clearManagedRedirectTabWatcher();
+        this.managedRedirectTab = tab;
+        this.managedRedirectTabTransactionId = transactionId;
+        this.managedRedirectTabCheckIntervalId = setInterval(() => {
+            if (!this.managedRedirectTab?.closed) {
+                return;
+            }
+            const closedTransactionId = this.managedRedirectTabTransactionId;
+            this.managedRedirectTab = null;
+            this.managedRedirectTabTransactionId = undefined;
+            this.clearManagedRedirectTabWatcher();
+            this.postMessage(CASHIER_REDIRECT_TAB_CLOSED_EVENT, {
+                transactionId: closedTransactionId
+            });
+        }, 500);
+    }
+    clearManagedRedirectTabWatcher() {
+        if (this.managedRedirectTabCheckIntervalId === undefined) {
+            return;
+        }
+        clearInterval(this.managedRedirectTabCheckIntervalId);
+        this.managedRedirectTabCheckIntervalId = undefined;
+    }
     openPopupWithPost(url, parameters) {
         if (typeof window === 'undefined') {
             return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@morefin/cashier-bootstrapper",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Bootstrap service for initializing cashier payment page data from API",
   "main": "dist/index.js",
   "module": "dist/index.js",