@morefin/cashier-bootstrapper 0.3.6 → 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

@@ -21,6 +21,7 @@ export declare class CashierBootstrapper {
     private managedRedirectTab?;
     private managedRedirectTabTransactionId?;
     private managedRedirectTabCheckIntervalId?;
+    private iframeLoadFallbackTimeoutId?;
     private origin;
     private ready;
     private readonly fullConfig;
@@ -29,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;

package/dist/index.js

@@ -3,6 +3,8 @@ 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';
@@ -213,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) {
@@ -241,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) {
@@ -267,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();

package/package.json

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