@melio-eng/web-sdk 1.1.0-pr.92.a38482a → 1.1.0-pr.93.ae7fb3c

package/README.md

@@ -28,6 +28,7 @@ const init = melioSDK.init("AUTH_CODE_FROM_YOUR_BACKEND", {
   partnerName: "your-partner-name",   // required
   environment: "production",          // optional — defaults to 'production'
   keepAlive: true,                    // optional — keeps the session warm
+  debug: true,                        // optional — verbose console logging
 });
 
 init.on("authenticationSucceeded", () => {
@@ -65,9 +66,29 @@ melioSDK.init(authenticationCode: string, options: InitOptions): InitFlowInstanc
   - `keepAlive` (boolean): If true, the session will be kept alive in the background via an invisible iframe
   - `environment` (Environment): The environment to use for API endpoints (defaults to `'production'`)
   - `branchOverride` (string): Advanced/testing only
+  - `debug` (boolean): If true, prints debug-level logs to the console on top of the warnings and errors the SDK always prints (defaults to `false`)
 
 `init` returns an `InitFlowInstance` you can listen on for `authenticationSucceeded` / `authenticationFailed`.
 
+### Debug Logging
+
+The SDK always prints warnings and errors to the browser console, prefixed with `[melio-sdk]`. Pass `debug: true` to `init()` to add debug-level output:
+
+```typescript
+melioSDK.init("auth_code", { partnerName: "your-partner-name", debug: true });
+```
+
+Every line carries `msSinceInit`, the elapsed time since `init()` was called — which is what makes a flow that *hangs* (rather than fails) visible in a console capture.
+
+Debug output covers:
+
+- host environment at init (user agent, `readyState`, whether the SDK is running inside a frame)
+- iframe lifecycle for the hidden auth iframe and every visible flow, with `loadMs` / `authMs` / `readyMs` timings
+- every `postMessage` exchanged with the embedded app, including message types the SDK does not handle
+- a keep-alive heartbeat (when `keepAlive: true`), which doubles as proof the page is still executing
+
+Regardless of the flag, a flow that neither loads nor becomes interactive is reported as an error every 15 seconds, up to 8 times. Auth codes and customer details are redacted from all output.
+
 ### Environment Configuration
 
 The SDK supports multiple environments to facilitate development and testing:

package/dist/flows/Flow.d.ts

@@ -13,11 +13,28 @@ export declare class Flow implements FlowInstance {
     private eventListeners;
     protected keepAliveInterval: number | null;
     private messageHandler;
+    private loadWatchdog;
+    private watchdogReports;
+    private iframeLoaded;
+    private readyForInteraction;
+    private injectedAt;
     constructor(containerId: string, config: BaseFlowConfig, partnerName: string, environment: Environment, branchOverride?: string | undefined);
     /**
      * Initialize the flow by creating and injecting the iframe
      */
     initialize(): Promise<void>;
+    /**
+     * Report a flow that has neither loaded nor become interactive within the budget.
+     *
+     * Diagnostic only: this logs and does nothing else. It separates "the iframe
+     * never loaded" from "it loaded but never reported READY_FOR_INTERACTION",
+     * which is the difference between a transport problem and the embedded app
+     * stalling after its document arrived.
+     */
+    private startLoadWatchdog;
+    /** Milliseconds since the iframe was injected, for load/ready timings. */
+    private sinceInject;
+    private clearLoadWatchdog;
     /**
      * Construct the specific flow URL - can be overridden by subclasses
      */
@@ -27,6 +44,7 @@ export declare class Flow implements FlowInstance {
      */
     protected createFlowUrl(): string;
     private setupEventListeners;
+    private handleMessage;
     /**
      * Emit events to registered listeners
      */

package/dist/flows/Flow.js

@@ -1,4 +1,5 @@
 import { getBaseUrl } from './utils.js';
+import { logger, redactUrl, describeError, describeConfig, LOAD_WATCHDOG_MS, WATCHDOG_MAX_REPORTS, } from './logger.js';
 /**
  * Flow class implementation for handling iframe flows and events
  */
@@ -14,6 +15,11 @@ export class Flow {
         this.eventListeners = new Map();
         this.keepAliveInterval = null;
         this.messageHandler = null;
+        this.loadWatchdog = null;
+        this.watchdogReports = 0;
+        this.iframeLoaded = false;
+        this.readyForInteraction = false;
+        this.injectedAt = null;
         this.setupEventListeners();
     }
     /**
@@ -22,15 +28,95 @@ export class Flow {
     async initialize() {
         this.container = document.getElementById(this.containerId);
         if (!this.container) {
+            logger.error('Flow container not found in the DOM', {
+                containerId: this.containerId,
+                partnerName: this.partnerName,
+            });
             throw new Error(`Container with ID "${this.containerId}" not found`);
         }
-        this.iframe = document.createElement('iframe');
-        this.iframe.src = this.createFlowUrl();
-        this.iframe.style.width = '100%';
-        this.iframe.style.height = '1000px';
-        this.iframe.style.border = 'none';
-        this.iframe.style.display = 'block';
-        this.container.appendChild(this.iframe);
+        let safeUrl = '<url not yet built>';
+        try {
+            const url = this.createFlowUrl();
+            safeUrl = redactUrl(url);
+            this.iframe = document.createElement('iframe');
+            this.iframe.src = url;
+            this.iframe.style.width = '100%';
+            this.iframe.style.height = '1000px';
+            this.iframe.style.border = 'none';
+            this.iframe.style.display = 'block';
+            this.iframe.addEventListener('load', () => {
+                this.iframeLoaded = true;
+                logger.debug('Flow iframe fired `load`', {
+                    url: safeUrl,
+                    loadMs: this.sinceInject(),
+                });
+            });
+            // Fires for network-level failures. A document that loads but then stalls
+            // internally will NOT fire this — that case is covered by the watchdog.
+            this.iframe.addEventListener('error', () => {
+                this.clearLoadWatchdog();
+                logger.error('Flow iframe failed to load', { url: safeUrl });
+            });
+            this.startLoadWatchdog(safeUrl);
+            logger.debug('Injecting flow iframe', {
+                url: safeUrl,
+                containerId: this.containerId,
+            });
+            this.injectedAt = Date.now();
+            this.container.appendChild(this.iframe);
+        }
+        catch (error) {
+            this.clearLoadWatchdog();
+            logger.error('Failed to inject flow iframe', {
+                url: safeUrl,
+                ...describeError(error),
+            });
+            throw error;
+        }
+    }
+    /**
+     * Report a flow that has neither loaded nor become interactive within the budget.
+     *
+     * Diagnostic only: this logs and does nothing else. It separates "the iframe
+     * never loaded" from "it loaded but never reported READY_FOR_INTERACTION",
+     * which is the difference between a transport problem and the embedded app
+     * stalling after its document arrived.
+     */
+    startLoadWatchdog(safeUrl) {
+        this.loadWatchdog = window.setInterval(() => {
+            if (this.iframeLoaded && this.readyForInteraction) {
+                this.clearLoadWatchdog();
+                return;
+            }
+            this.watchdogReports += 1;
+            const context = {
+                url: safeUrl,
+                waitedMs: this.watchdogReports * LOAD_WATCHDOG_MS,
+                report: `${this.watchdogReports}/${WATCHDOG_MAX_REPORTS}`,
+                containerId: this.containerId,
+                environment: this.environment,
+            };
+            if (!this.iframeLoaded) {
+                logger.error('Flow iframe has not fired `load` — the flow document appears to be stuck', context);
+            }
+            else {
+                logger.error('Flow iframe loaded but never sent READY_FOR_INTERACTION — the embedded app is stuck after its document loaded', context);
+            }
+            if (this.watchdogReports >= WATCHDOG_MAX_REPORTS) {
+                logger.error('Giving up on stuck-flow reporting — the flow never became interactive. If this is the last SDK line in the console, the page stopped executing here', context);
+                this.clearLoadWatchdog();
+            }
+        }, LOAD_WATCHDOG_MS);
+    }
+    /** Milliseconds since the iframe was injected, for load/ready timings. */
+    sinceInject() {
+        return this.injectedAt === null ? null : Date.now() - this.injectedAt;
+    }
+    clearLoadWatchdog() {
+        if (this.loadWatchdog !== null) {
+            clearInterval(this.loadWatchdog);
+            this.loadWatchdog = null;
+        }
     }
     /**
      * Construct the specific flow URL - can be overridden by subclasses
@@ -42,11 +128,6 @@ export class Flow {
      * Create flow URL using partner name and environment
      */
     createFlowUrl() {
-        console.log('🔧 Creating flow URL...');
-        console.log('📝 Config:', this.config);
-        console.log('🏢 Partner:', this.partnerName);
-        console.log('🌍 Environment:', this.environment);
-        console.log('🔝 Branch Override:', this.branchOverride);
         const baseUrl = getBaseUrl(this.environment);
         let finalUrl = this.constructFlowUrl(baseUrl);
         // Add cdn_branch_override parameter for non-production environments
@@ -54,70 +135,125 @@ export class Flow {
             const separator = finalUrl.includes('?') ? '&' : '?';
             finalUrl += `${separator}cdn_branch_override=${this.branchOverride}`;
         }
-        console.log('🌐 Final URL:', finalUrl);
+        logger.debug('Created flow URL', {
+            url: redactUrl(finalUrl),
+            partnerName: this.partnerName,
+            environment: this.environment,
+            branchOverride: this.branchOverride,
+            config: describeConfig(this.config),
+        });
         return finalUrl;
     }
     setupEventListeners() {
         // Add post message handlers for internal events - setHeight, scroll etc
         // Also need to implement callbacks for flow completed exit etc in the platform-app
         this.messageHandler = (event) => {
-            if (!/melio\.com|melioservices\.com/.test(event.origin)) {
-                return;
+            try {
+                this.handleMessage(event);
             }
-            const { type, ...data } = event.data;
-            console.log('📬 Received message from iframe:', {
-                type,
-                data,
-                origin: event.origin,
-            });
-            switch (type) {
-                case 'FLOW_COMPLETED':
-                    this.emit('completed', data);
-                    break;
-                case 'FLOW_EXIT':
-                    this.emit('exit');
-                    break;
-                case 'NAVIGATED_TO_TARGET':
-                    this.emit('navigated', data);
-                    break;
-                case 'ONBOARDING_FORM_COMPLETED':
-                    this.emit('onboardingCompleted');
-                    break;
-                case 'ONBOARDING_REQUIRED':
-                    this.emit('onboardingRequired');
-                    break;
-                case 'READY_FOR_INTERACTION':
-                    this.emit('loaded');
-                    break;
-                case 'PAYMENT_SCHEDULED':
-                    this.emit('completed', { flowName: 'payment', ...data });
-                    break;
-                case 'MELIO_ERROR':
-                    if (data.code === 'failed_to_sync_bills') {
-                        this.emit('error', { errorCode: 'billsSyncFailed' });
-                    }
-                    break;
-                case 'HEIGHT_CHANGE':
-                    if (this.iframe) {
-                        this.iframe.style.height = `${data.height}px`;
-                    }
-                    break;
+            catch (error) {
+                // A throw here would escape into the host page as an uncaught listener
+                // error with no indication it came from the SDK.
+                logger.error('Failed to handle message from flow iframe', {
+                    origin: event.origin,
+                    ...describeError(error),
+                });
             }
         };
         window.addEventListener('message', this.messageHandler);
     }
-    emit(event, data) {
-        const listeners = this.eventListeners.get(event);
-        if (listeners) {
-            listeners.forEach((callback) => {
-                try {
-                    callback(data);
+    handleMessage(event) {
+        if (!/melio\.com|melioservices\.com/.test(event.origin)) {
+            // Only surface near-misses. Host pages receive plenty of unrelated
+            // postMessage traffic and logging all of it would bury the signal.
+            if (/melio/i.test(event.origin)) {
+                logger.warn('Ignored message from an unrecognised Melio origin — check the origin allowlist', { origin: event.origin });
+            }
+            return;
+        }
+        // Destructuring a null or primitive payload throws, and this handler runs
+        // for every message that clears the origin check.
+        if (event.data === null || typeof event.data !== 'object') {
+            logger.warn('Ignored non-object message from a Melio origin', {
+                origin: event.origin,
+                dataType: event.data === null ? 'null' : typeof event.data,
+            });
+            return;
+        }
+        const { type, ...data } = event.data;
+        logger.debug('Received message from flow iframe', {
+            type,
+            data,
+            origin: event.origin,
+        });
+        switch (type) {
+            case 'FLOW_COMPLETED':
+                this.emit('completed', data);
+                break;
+            case 'FLOW_EXIT':
+                this.emit('exit');
+                break;
+            case 'NAVIGATED_TO_TARGET':
+                this.emit('navigated', data);
+                break;
+            case 'ONBOARDING_FORM_COMPLETED':
+                this.emit('onboardingCompleted');
+                break;
+            case 'ONBOARDING_REQUIRED':
+                this.emit('onboardingRequired');
+                break;
+            case 'READY_FOR_INTERACTION':
+                this.readyForInteraction = true;
+                this.clearLoadWatchdog();
+                logger.debug('Flow reported READY_FOR_INTERACTION', {
+                    readyMs: this.sinceInject(),
+                });
+                this.emit('loaded');
+                break;
+            case 'PAYMENT_SCHEDULED':
+                this.emit('completed', { flowName: 'payment', ...data });
+                break;
+            case 'MELIO_ERROR':
+                logger.error('Embedded app reported MELIO_ERROR', { ...data });
+                if (data.code === 'failed_to_sync_bills') {
+                    this.emit('error', { errorCode: 'billsSyncFailed' });
                 }
-                catch (error) {
-                    console.error(`Error in ${event} event listener:`, error);
+                else {
+                    // Only failed_to_sync_bills maps to a public ErrorData code, so any
+                    // other code is not forwarded to the host at all. Log it loudly
+                    // rather than dropping it silently.
+                    logger.error('MELIO_ERROR code has no mapping and was not forwarded to the host', { code: data.code });
                 }
-            });
+                break;
+            case 'HEIGHT_CHANGE':
+                if (this.iframe) {
+                    this.iframe.style.height = `${data.height}px`;
+                }
+                else {
+                    logger.warn('Received HEIGHT_CHANGE but the flow iframe no longer exists', { height: data.height });
+                }
+                break;
+            default:
+                logger.debug('Unhandled message type from flow iframe', { type });
+                break;
+        }
+    }
+    emit(event, data) {
+        const listeners = this.eventListeners.get(event);
+        if (!listeners || listeners.size === 0) {
+            if (event === 'error' || event === 'authenticationFailed') {
+                logger.warn(`Emitted '${event}' but no listener is registered — the host will not learn about it`, { data });
+            }
+            return;
         }
+        listeners.forEach((callback) => {
+            try {
+                callback(data);
+            }
+            catch (error) {
+                logger.error(`Listener for '${event}' threw`, describeError(error));
+            }
+        });
     }
     on(event, callback) {
         if (!this.eventListeners.has(event)) {
@@ -139,12 +275,25 @@ export class Flow {
      * Close the flow and clean up resources
      */
     close() {
+        logger.debug('Closing flow', {
+            containerId: this.containerId,
+            iframeLoaded: this.iframeLoaded,
+            readyForInteraction: this.readyForInteraction,
+        });
+        this.clearLoadWatchdog();
         if (this.keepAliveInterval) {
             clearInterval(this.keepAliveInterval);
             this.keepAliveInterval = null;
         }
         if (this.iframe && this.container) {
-            this.container.removeChild(this.iframe);
+            try {
+                this.container.removeChild(this.iframe);
+            }
+            catch (error) {
+                // Throwing here would abandon the rest of teardown, leaving the message
+                // listener attached and the keep-alive running.
+                logger.error('Failed to remove the flow iframe during close — continuing teardown', describeError(error));
+            }
             this.iframe = null;
         }
         if (this.messageHandler) {

package/dist/flows/InitFlow.d.ts

@@ -13,11 +13,30 @@ export declare class InitFlow implements InitFlowInstance {
     private partnerName;
     private environment;
     private branchOverride?;
+    private loadWatchdog;
+    private watchdogReports;
+    private iframeLoaded;
+    private authResolved;
+    private keepAliveTargetLost;
+    private injectedAt;
+    private keepAlivePings;
     constructor(config: InitConfig, partnerName: string, environment: Environment, branchOverride?: string);
     /**
      * Initialize the init flow by creating and injecting a hidden iframe
      */
     initialize(): Promise<void>;
+    /**
+     * Report a flow that has neither loaded nor authenticated within the budget.
+     *
+     * Diagnostic only: this logs and does nothing else. It deliberately separates
+     * "the auth document never loaded" from "it loaded but never authenticated",
+     * because those point at different layers and the distinction is invisible
+     * from the host page otherwise.
+     */
+    private startLoadWatchdog;
+    /** Milliseconds since the iframe was injected, for load/auth timings. */
+    private sinceInject;
+    private clearLoadWatchdog;
     /**
      * Construct the specific flow URL for initialization
      */
@@ -30,6 +49,7 @@ export declare class InitFlow implements InitFlowInstance {
      * Setup event listeners to only handle authentication events
      */
     private setupEventListeners;
+    private handleMessage;
     /**
      * Emit events to registered listeners
      */

package/dist/flows/InitFlow.js

@@ -1,4 +1,5 @@
 import { isEmptyString, getBaseUrl } from './utils.js';
+import { logger, redactUrl, describeError, describeConfig, LOAD_WATCHDOG_MS, WATCHDOG_MAX_REPORTS, KEEP_ALIVE_INTERVAL_MS, } from './logger.js';
 /**
  * Standalone InitFlow class for handling initialization with callbacks
  */
@@ -9,7 +10,18 @@ export class InitFlow {
         this.eventListeners = new Map();
         this.keepAliveInterval = null;
         this.messageHandler = null;
+        this.loadWatchdog = null;
+        this.watchdogReports = 0;
+        this.iframeLoaded = false;
+        this.authResolved = false;
+        this.keepAliveTargetLost = false;
+        this.injectedAt = null;
+        this.keepAlivePings = 0;
         if (isEmptyString(config.authCode)) {
+            logger.error('Cannot create init flow: authorization code is missing', {
+                partnerName,
+                environment,
+            });
             throw new Error('Authorization code is required for init flow');
         }
         this.authorizationCode = config.authCode;
@@ -23,15 +35,101 @@ export class InitFlow {
      * Initialize the init flow by creating and injecting a hidden iframe
      */
     async initialize() {
-        this.container = document.body;
-        this.iframe = document.createElement('iframe');
-        this.iframe.src = this.createFlowUrl();
-        this.iframe.style.width = '1px';
-        this.iframe.style.height = '1px';
-        this.iframe.style.position = 'absolute';
-        this.iframe.style.left = '-9999px';
-        this.iframe.style.top = '-9999px';
-        this.container.appendChild(this.iframe);
+        let safeUrl = '<url not yet built>';
+        try {
+            const url = this.createFlowUrl();
+            safeUrl = redactUrl(url);
+            // The SDK is preloaded, so it can run before the host document has a
+            // body. Without this the failure surfaces as an opaque TypeError from
+            // appendChild.
+            if (!document.body) {
+                logger.error('Cannot inject auth iframe: document.body does not exist yet — the SDK was initialized before the host document was ready', { url: safeUrl, readyState: document.readyState });
+                throw new Error('document.body is not available for iframe injection');
+            }
+            this.container = document.body;
+            this.iframe = document.createElement('iframe');
+            this.iframe.src = url;
+            this.iframe.style.width = '1px';
+            this.iframe.style.height = '1px';
+            this.iframe.style.position = 'absolute';
+            this.iframe.style.left = '-9999px';
+            this.iframe.style.top = '-9999px';
+            this.iframe.addEventListener('load', () => {
+                this.iframeLoaded = true;
+                logger.debug('Auth iframe fired `load`', {
+                    url: safeUrl,
+                    loadMs: this.sinceInject(),
+                });
+            });
+            // Fires for network-level failures. A document that loads but then stalls
+            // internally will NOT fire this — that case is covered by the watchdog.
+            this.iframe.addEventListener('error', () => {
+                this.clearLoadWatchdog();
+                logger.error('Auth iframe failed to load', { url: safeUrl });
+            });
+            this.startLoadWatchdog(safeUrl);
+            logger.debug('Injecting hidden auth iframe', {
+                url: safeUrl,
+                partnerName: this.partnerName,
+                environment: this.environment,
+                config: describeConfig(this.config),
+            });
+            this.injectedAt = Date.now();
+            this.container.appendChild(this.iframe);
+        }
+        catch (error) {
+            this.clearLoadWatchdog();
+            logger.error('Failed to inject auth iframe', {
+                url: safeUrl,
+                ...describeError(error),
+            });
+            throw error;
+        }
+    }
+    /**
+     * Report a flow that has neither loaded nor authenticated within the budget.
+     *
+     * Diagnostic only: this logs and does nothing else. It deliberately separates
+     * "the auth document never loaded" from "it loaded but never authenticated",
+     * because those point at different layers and the distinction is invisible
+     * from the host page otherwise.
+     */
+    startLoadWatchdog(safeUrl) {
+        this.loadWatchdog = window.setInterval(() => {
+            if (this.iframeLoaded && this.authResolved) {
+                this.clearLoadWatchdog();
+                return;
+            }
+            this.watchdogReports += 1;
+            const waitedMs = this.watchdogReports * LOAD_WATCHDOG_MS;
+            const context = {
+                url: safeUrl,
+                waitedMs,
+                report: `${this.watchdogReports}/${WATCHDOG_MAX_REPORTS}`,
+                partnerName: this.partnerName,
+                environment: this.environment,
+            };
+            if (!this.iframeLoaded) {
+                logger.error('Auth iframe has not fired `load` — the auth document appears to be stuck', context);
+            }
+            else {
+                logger.error('Auth iframe loaded but never reported AUTHENTICATION_SUCCESS or AUTHENTICATION_ERROR — auth is stuck inside the iframe', context);
+            }
+            if (this.watchdogReports >= WATCHDOG_MAX_REPORTS) {
+                logger.error('Giving up on stuck-flow reporting — the auth flow never resolved. If this is the last SDK line in the console, the page stopped executing here', context);
+                this.clearLoadWatchdog();
+            }
+        }, LOAD_WATCHDOG_MS);
+    }
+    /** Milliseconds since the iframe was injected, for load/auth timings. */
+    sinceInject() {
+        return this.injectedAt === null ? null : Date.now() - this.injectedAt;
+    }
+    clearLoadWatchdog() {
+        if (this.loadWatchdog !== null) {
+            clearInterval(this.loadWatchdog);
+            this.loadWatchdog = null;
+        }
     }
     /**
      * Construct the specific flow URL for initialization
@@ -61,42 +159,80 @@ export class InitFlow {
      */
     setupEventListeners() {
         this.messageHandler = (event) => {
-            if (!/melio\.com|melioservices\.com/.test(event.origin)) {
-                return;
+            try {
+                this.handleMessage(event);
             }
-            const { type, ...data } = event.data;
-            console.log('📬 Received message from iframe:', {
-                type,
-                data,
-                origin: event.origin,
-            });
-            switch (type) {
-                case 'AUTHENTICATION_SUCCESS':
-                    this.emit('authenticationSucceeded');
-                    break;
-                case 'AUTHENTICATION_ERROR':
-                    this.emit('authenticationFailed');
-                    break;
+            catch (error) {
+                // A throw here would escape into the host page as an uncaught listener
+                // error with no indication it came from the SDK.
+                logger.error('Failed to handle message from auth iframe', {
+                    origin: event.origin,
+                    ...describeError(error),
+                });
             }
         };
         window.addEventListener('message', this.messageHandler);
     }
+    handleMessage(event) {
+        if (!/melio\.com|melioservices\.com/.test(event.origin)) {
+            // Only surface near-misses. Host pages receive plenty of unrelated
+            // postMessage traffic and logging all of it would bury the signal.
+            if (/melio/i.test(event.origin)) {
+                logger.warn('Ignored message from an unrecognised Melio origin — check the origin allowlist', { origin: event.origin });
+            }
+            return;
+        }
+        // Destructuring a null or primitive payload throws, and this handler runs
+        // for every message that clears the origin check.
+        if (event.data === null || typeof event.data !== 'object') {
+            logger.warn('Ignored non-object message from a Melio origin', {
+                origin: event.origin,
+                dataType: event.data === null ? 'null' : typeof event.data,
+            });
+            return;
+        }
+        const { type, ...data } = event.data;
+        logger.debug('Received message from auth iframe', {
+            type,
+            data,
+            origin: event.origin,
+        });
+        switch (type) {
+            case 'AUTHENTICATION_SUCCESS':
+                this.authResolved = true;
+                this.clearLoadWatchdog();
+                logger.debug('Authentication succeeded');
+                this.emit('authenticationSucceeded');
+                break;
+            case 'AUTHENTICATION_ERROR':
+                this.authResolved = true;
+                this.clearLoadWatchdog();
+                logger.error('Authentication failed', { ...data });
+                this.emit('authenticationFailed', data);
+                break;
+            default:
+                logger.debug('Unhandled message type from auth iframe', { type });
+                break;
+        }
+    }
     /**
      * Emit events to registered listeners
      */
     /* eslint-disable @typescript-eslint/no-explicit-any */
     emit(event, data) {
         const listeners = this.eventListeners.get(event);
-        if (listeners) {
-            listeners.forEach((callback) => {
-                try {
-                    callback(data);
-                }
-                catch (error) {
-                    console.error(`Error in ${event} event listener:`, error);
-                }
-            });
+        if (!listeners || listeners.size === 0) {
+            logger.warn(`Emitted '${event}' but no listener is registered — the host will not learn about it`, { data });
+            return;
         }
+        listeners.forEach((callback) => {
+            try {
+                callback(data);
+            }
+            catch (error) {
+                logger.error(`Listener for '${event}' threw`, describeError(error));
+            }
+        });
     }
     /**
      * Register an event listener
@@ -121,12 +257,24 @@ export class InitFlow {
      * Close the flow and clean up resources
      */
     close() {
+        logger.debug('Closing init flow', {
+            iframeLoaded: this.iframeLoaded,
+            authResolved: this.authResolved,
+        });
+        this.clearLoadWatchdog();
         if (this.keepAliveInterval) {
             clearInterval(this.keepAliveInterval);
             this.keepAliveInterval = null;
         }
         if (this.iframe && this.container) {
-            this.container.removeChild(this.iframe);
+            try {
+                this.container.removeChild(this.iframe);
+            }
+            catch (error) {
+                // Throwing here would abandon the rest of teardown, leaving the message
+                // listener attached and the keep-alive running.
+                logger.error('Failed to remove the auth iframe during close — continuing teardown', describeError(error));
+            }
             this.iframe = null;
         }
         if (this.messageHandler) {
@@ -136,10 +284,39 @@ export class InitFlow {
         this.eventListeners.clear();
     }
     setupKeepAlive() {
+        if (this.keepAliveInterval !== null) {
+            logger.warn('setupKeepAlive called while a keep-alive is already running — clearing the previous interval to avoid a leak');
+            clearInterval(this.keepAliveInterval);
+            this.keepAliveInterval = null;
+        }
         this.keepAliveInterval = window.setInterval(() => {
-            if (this.iframe && this.iframe.contentWindow) {
+            if (!this.iframe || !this.iframe.contentWindow) {
+                // Logged once: the interval keeps running, so an unguarded log here
+                // would repeat every 30s for the life of the page.
+                if (!this.keepAliveTargetLost) {
+                    this.keepAliveTargetLost = true;
+                    logger.error('Keep-alive ping has no target — the auth iframe or its content window is gone, every subsequent ping is a no-op', {
+                        hasIframe: Boolean(this.iframe),
+                        iframeLoaded: this.iframeLoaded,
+                        authResolved: this.authResolved,
+                    });
+                }
+                return;
+            }
+            if (this.keepAliveTargetLost) {
+                this.keepAliveTargetLost = false;
+                logger.warn('Keep-alive target recovered');
+            }
+            try {
                 this.iframe.contentWindow.postMessage({ type: 'USER_ACTIVE_PING' }, '*');
+                this.keepAlivePings += 1;
+                // Doubles as a liveness heartbeat: if these stop while the flow is
+                // still open, the page stopped executing rather than merely stalling.
+                logger.debug('Keep-alive ping sent', { ping: this.keepAlivePings });
+            }
+            catch (error) {
+                logger.error('Keep-alive ping threw', describeError(error));
             }
-        }, 30000); // Send ping every 30 seconds
+        }, KEEP_ALIVE_INTERVAL_MS);
     }
 }

package/dist/flows/logger.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Lightweight console logger for the SDK.
+ *
+ * Every line is prefixed with `[melio-sdk]` so partners can filter SDK output out
+ * of a busy host page, and carries `msSinceInit` — elapsed time since `init()` was
+ * called. The elapsed time is what makes a *hang* legible in a console capture: a
+ * hard failure shows up as an error either way, but a flow that simply never
+ * finishes is only visible as a gap on the clock.
+ */
+/**
+ * Severity levels, lowest first. `debug` is opt-in via `init({ debug: true })`;
+ * `warn` and `error` always print, because a partner debugging a broken flow
+ * should not have to enable anything to see that something failed.
+ */
+export type LogLevel = 'debug' | 'warn' | 'error';
+/** Enable or disable debug-level output. Called from `init({ debug })`. */
+export declare const setDebugEnabled: (enabled: boolean) => void;
+/** Whether debug-level output is currently enabled. */
+export declare const isDebugEnabled: () => boolean;
+/**
+ * How long a flow may stay unloaded before the SDK reports it as stuck, and how
+ * often it keeps repeating that report afterwards.
+ *
+ * Diagnostic only — reaching it logs, it does not tear the flow down.
+ *
+ * The repeat matters for diagnosing a page that dies rather than recovers: a
+ * stuck flow keeps announcing itself every 15s, so the timestamp of the *last*
+ * report marks the moment the tab stopped executing. A one-shot log cannot
+ * distinguish "still hanging" from "the renderer was killed".
+ */
+export declare const LOAD_WATCHDOG_MS = 15000;
+/** Stop repeating the stuck-flow report after this many rounds (~2 minutes). */
+export declare const WATCHDOG_MAX_REPORTS = 8;
+/** Interval between keep-alive pings to an initialized flow. */
+export declare const KEEP_ALIVE_INTERVAL_MS = 30000;
+/** Start the SDK clock. Called once from `init()`. */
+export declare const markInitStart: () => void;
+/**
+ * Strip credential-bearing query params so a flow URL can be logged safely.
+ * On a URL we cannot parse we fall back to the path, never the raw string.
+ */
+export declare const redactUrl: (url: string) => string;
+/** Flatten an unknown throwable into something that survives a console capture. */
+export declare const describeError: (error: unknown) => Record<string, unknown>;
+/**
+ * Shallow-copy a flow config with PII redacted, so a config can be logged
+ * without printing customer details into the partner's console.
+ */
+export declare const describeConfig: (config: object | undefined) => Record<string, unknown>;
+/**
+ * Describe the host environment once at init. The Safari 26.5 regression on
+ * Xero's Bills page was only ever reproducible on specific browser builds, and
+ * whether we are running inside a frame decides which failure modes are even
+ * possible — so both belong in any console capture we are asked to read.
+ */
+export declare const describeHost: () => Record<string, unknown>;
+export declare const logger: {
+    debug(message: string, context?: Record<string, unknown>): void;
+    warn(message: string, context?: Record<string, unknown>): void;
+    error(message: string, context?: Record<string, unknown>): void;
+};

package/dist/flows/logger.js

@@ -0,0 +1,153 @@
+/**
+ * Lightweight console logger for the SDK.
+ *
+ * Every line is prefixed with `[melio-sdk]` so partners can filter SDK output out
+ * of a busy host page, and carries `msSinceInit` — elapsed time since `init()` was
+ * called. The elapsed time is what makes a *hang* legible in a console capture: a
+ * hard failure shows up as an error either way, but a flow that simply never
+ * finishes is only visible as a gap on the clock.
+ */
+const PREFIX = '[melio-sdk]';
+/** Query params that may carry a credential and must never reach the console. */
+const REDACTED_PARAMS = ['token', 'authCode', 'code'];
+/**
+ * Flow-config keys holding a credential or customer PII. Their presence is worth
+ * logging, their contents are not — this SDK runs inside a partner's page.
+ *
+ * `authCode` matters most: it is on both `InitConfig` and `BaseFlowConfig`, so
+ * logging a config verbatim prints a live auth token to the console.
+ */
+const REDACTED_CONFIG_KEYS = [
+    'authCode',
+    'token',
+    'code',
+    'userDetails',
+    'organizationDetails',
+];
+const LEVEL_WEIGHT = {
+    debug: 10,
+    warn: 20,
+    error: 30,
+};
+let minimumWeight = LEVEL_WEIGHT.warn;
+/** Enable or disable debug-level output. Called from `init({ debug })`. */
+export const setDebugEnabled = (enabled) => {
+    minimumWeight = enabled ? LEVEL_WEIGHT.debug : LEVEL_WEIGHT.warn;
+};
+/** Whether debug-level output is currently enabled. */
+export const isDebugEnabled = () => minimumWeight <= LEVEL_WEIGHT.debug;
+const shouldLog = (level) => LEVEL_WEIGHT[level] >= minimumWeight;
+/**
+ * How long a flow may stay unloaded before the SDK reports it as stuck, and how
+ * often it keeps repeating that report afterwards.
+ *
+ * Diagnostic only — reaching it logs, it does not tear the flow down.
+ *
+ * The repeat matters for diagnosing a page that dies rather than recovers: a
+ * stuck flow keeps announcing itself every 15s, so the timestamp of the *last*
+ * report marks the moment the tab stopped executing. A one-shot log cannot
+ * distinguish "still hanging" from "the renderer was killed".
+ */
+export const LOAD_WATCHDOG_MS = 15000;
+/** Stop repeating the stuck-flow report after this many rounds (~2 minutes). */
+export const WATCHDOG_MAX_REPORTS = 8;
+/** Interval between keep-alive pings to an initialized flow. */
+export const KEEP_ALIVE_INTERVAL_MS = 30000;
+let initTimestamp = null;
+/** Start the SDK clock. Called once from `init()`. */
+export const markInitStart = () => {
+    initTimestamp = Date.now();
+};
+const buildContext = (context) => ({
+    ...(initTimestamp === null
+        ? {}
+        : { msSinceInit: Date.now() - initTimestamp }),
+    ...context,
+});
+/**
+ * Strip credential-bearing query params so a flow URL can be logged safely.
+ * On a URL we cannot parse we fall back to the path, never the raw string.
+ */
+export const redactUrl = (url) => {
+    try {
+        const parsed = new URL(url);
+        REDACTED_PARAMS.forEach((param) => {
+            if (parsed.searchParams.has(param)) {
+                parsed.searchParams.set(param, 'redacted');
+            }
+        });
+        return parsed.toString();
+    }
+    catch {
+        return `${url.split('?')[0]}?[unparsed-query-redacted]`;
+    }
+};
+/** Flatten an unknown throwable into something that survives a console capture. */
+export const describeError = (error) => {
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message, stack: error.stack };
+    }
+    return { thrown: String(error) };
+};
+/**
+ * Shallow-copy a flow config with PII redacted, so a config can be logged
+ * without printing customer details into the partner's console.
+ */
+export const describeConfig = (config) => {
+    if (!config) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(config).map(([key, value]) => [
+        key,
+        REDACTED_CONFIG_KEYS.includes(key) && value !== undefined
+            ? '[redacted]'
+            : value,
+    ]));
+};
+/**
+ * Describe the host environment once at init. The Safari 26.5 regression on
+ * Xero's Bills page was only ever reproducible on specific browser builds, and
+ * whether we are running inside a frame decides which failure modes are even
+ * possible — so both belong in any console capture we are asked to read.
+ */
+export const describeHost = () => {
+    const host = {};
+    if (typeof navigator !== 'undefined') {
+        host.userAgent = navigator.userAgent;
+    }
+    if (typeof document !== 'undefined') {
+        host.readyState = document.readyState;
+        host.visibilityState = document.visibilityState;
+    }
+    if (typeof window !== 'undefined') {
+        try {
+            host.isFramed = window.top !== window.self;
+        }
+        catch {
+            // Cross-origin parents throw on access, which itself proves we are framed.
+            host.isFramed = true;
+        }
+        host.origin = window.location?.origin;
+    }
+    return host;
+};
+export const logger = {
+    debug(message, context) {
+        if (!shouldLog('debug')) {
+            return;
+        }
+        console.log(`${PREFIX} ${message}`, buildContext(context));
+    },
+    warn(message, context) {
+        if (!shouldLog('warn')) {
+            return;
+        }
+        console.warn(`${PREFIX} ${message}`, buildContext(context));
+    },
+    error(message, context) {
+        if (!shouldLog('error')) {
+            return;
+        }
+        console.error(`${PREFIX} ${message}`, buildContext(context));
+    },
+};

package/dist/flows/utils.js

@@ -1,3 +1,4 @@
+import { logger } from './logger.js';
 /**
  * Utility function to get the base URL for a given environment
  */
@@ -16,6 +17,7 @@ export function getBaseUrl(environment) {
         case 'localhost':
             return 'http://localhost:3005';
         default:
+            logger.warn('Unknown environment — falling back to the default base URL, which may not serve this partner', { environment, fallback: 'https://partnerships.melioservices.com' });
             return 'https://partnerships.melioservices.com';
     }
 }

package/dist/index.d.ts

@@ -14,6 +14,12 @@ export declare class MelioSDK implements MelioSDK {
      * Initialize the SDK - triggers auth event without creating iframe
      */
     init(authenticationCode: string, options: InitOptions): InitFlowInstance;
+    /**
+     * Shared launch path for every open* flow: log the attempt, report a
+     * constructor failure, and make sure a rejected initialize() surfaces rather
+     * than becoming an unhandled promise.
+     */
+    private startFlow;
     /**
      * Launch the onboarding flow
      */

package/dist/index.js

@@ -1,4 +1,5 @@
 import { InitFlow, OnboardingFlow, PayFlow, JustPayFlow, SettingsFlow, PaymentsDashboardFlow, isEmptyString, } from './flows/index.js';
+import { logger, markInitStart, describeError, describeConfig, describeHost, setDebugEnabled, } from './flows/logger.js';
 /**
  * Main SDK implementation - now partner agnostic
  */
@@ -16,79 +17,101 @@ export class MelioSDK {
      */
     init(authenticationCode, options) {
         if (this.initFlow) {
-            console.log('SDK already initialized. Returning existing init flow instance.');
+            logger.warn('SDK already initialized. Returning existing init flow instance.');
             return this.initFlow;
         }
+        // Set before the first log so the init banner honours the flag.
+        setDebugEnabled(Boolean(options.debug));
+        markInitStart();
         this.partnerName = options.partnerName;
         this.environment = options.environment || 'production';
         this.branchOverride = options.branchOverride;
         this.authCode = authenticationCode;
-        console.log('starting init flow', {
+        logger.debug('Starting init flow', {
             partnerName: this.partnerName,
             environment: this.environment,
+            keepAlive: Boolean(options.keepAlive),
+            branchOverride: this.branchOverride,
+            ...describeHost(),
+        });
+        let initFlow;
+        try {
+            initFlow = new InitFlow({ authCode: authenticationCode, containerId: '' }, this.partnerName, this.environment, this.branchOverride);
+        }
+        catch (error) {
+            logger.error('Failed to create the init flow', describeError(error));
+            throw error;
+        }
+        // `initialize()` is intentionally not awaited — `init()` is synchronous by
+        // contract — but its rejection must not become an unhandled promise, which
+        // is invisible to partners debugging from the console.
+        initFlow.initialize().catch((error) => {
+            logger.error('Init flow failed to initialize', describeError(error));
         });
-        const initFlow = new InitFlow({ authCode: authenticationCode, containerId: '' }, this.partnerName, this.environment, this.branchOverride);
-        initFlow.initialize();
-        console.log('InitFlow initialized successfully');
         if (options.keepAlive)
             initFlow.setupKeepAlive();
         this.initFlow = initFlow;
         return this.initFlow;
     }
     /**
-     * Launch the onboarding flow
+     * Shared launch path for every open* flow: log the attempt, report a
+     * constructor failure, and make sure a rejected initialize() surfaces rather
+     * than becoming an unhandled promise.
      */
-    openOnboarding(config) {
+    startFlow(flowName, config, create) {
         if (isEmptyString(this.authCode)) {
-            throw new Error('SDK not initialized. Please call init() before opening onboarding flow.');
+            const message = `SDK not initialized. Please call init() before opening ${flowName}.`;
+            logger.error(message);
+            throw new Error(message);
+        }
+        logger.debug(`Opening ${flowName}`, {
+            partnerName: this.partnerName,
+            environment: this.environment,
+            config: describeConfig(config),
+        });
+        let flow;
+        try {
+            flow = create();
         }
-        const flow = new OnboardingFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
+        catch (error) {
+            logger.error(`Failed to create ${flowName}`, describeError(error));
+            throw error;
+        }
+        // Not awaited by contract, but a rejection must not vanish.
+        flow.initialize().catch((error) => {
+            logger.error(`${flowName} failed to initialize`, describeError(error));
+        });
         return flow;
     }
+    /**
+     * Launch the onboarding flow
+     */
+    openOnboarding(config) {
+        return this.startFlow('onboarding flow', config, () => new OnboardingFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride));
+    }
     /**
      * Launch the pay flow
      */
     openPayFlow(config) {
-        if (isEmptyString(this.authCode)) {
-            throw new Error('SDK not initialized. Please call init() before opening pay flow.');
-        }
-        const flow = new PayFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
-        return flow;
+        return this.startFlow('pay flow', config, () => new PayFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride));
     }
     /**
      * Launch the just pay flow (vendor-based payment)
      */
     openJustPayFlow(config) {
-        if (isEmptyString(this.authCode)) {
-            throw new Error('SDK not initialized. Please call init() before opening just pay flow.');
-        }
-        const flow = new JustPayFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
-        return flow;
+        return this.startFlow('just pay flow', config, () => new JustPayFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride));
     }
     /**
      * Launch the settings flow
      */
     openSettings(config) {
-        if (isEmptyString(this.authCode)) {
-            throw new Error('SDK not initialized. Please call init() before opening settings flow.');
-        }
-        const flow = new SettingsFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
-        return flow;
+        return this.startFlow('settings flow', config, () => new SettingsFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride));
     }
     /**
      * Launch the payments dashboard flow
      */
     openPaymentsDashboard(config) {
-        if (isEmptyString(this.authCode)) {
-            throw new Error('SDK not initialized. Please call init() before opening payments dashboard flow.');
-        }
-        const flow = new PaymentsDashboardFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
-        return flow;
+        return this.startFlow('payments dashboard flow', config, () => new PaymentsDashboardFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride));
     }
 }
 /**

package/dist/types.d.ts

@@ -14,6 +14,16 @@ export interface InitOptions {
     environment?: Environment;
     /** The branch to use for the melio platform. Defaults to 'main' */
     branchOverride?: string;
+    /**
+     * If true, the SDK prints debug-level logs to the console on top of the
+     * warnings and errors it always prints. Defaults to false.
+     *
+     * Turn this on to trace a flow that loads but never becomes usable: debug
+     * output covers iframe lifecycle, load and auth timings, every postMessage
+     * exchanged with the embedded app, and a keep-alive heartbeat proving the
+     * page is still executing.
+     */
+    debug?: boolean;
 }
 /**
  * Base configuration for all flows

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melio-eng/web-sdk",
-  "version": "1.1.0-pr.92.a38482a",
+  "version": "1.1.0-pr.93.ae7fb3c",
   "description": "Melio Web SDK - Embed core Melio workflows directly into partner UI with minimal effort",
   "main": "dist/index.js",
   "module": "dist/index.js",