@melio-eng/web-sdk 1.1.0 → 1.2.0-pr.93.0a67210

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: false,                       // optional — verbose console diagnostics
 });
 
 init.on("authenticationSucceeded", () => {
@@ -63,11 +64,20 @@ melioSDK.init(authenticationCode: string, options: InitOptions): InitFlowInstanc
 - `options` (InitOptions, required): Configuration options
   - `partnerName` (string, required): The partner name for the SDK instance
   - `keepAlive` (boolean): If true, the session will be kept alive in the background via an invisible iframe
+  - `debug` (boolean): If true, the SDK prints debug-level diagnostics to the console. Warnings and errors always print
   - `environment` (Environment): The environment to use for API endpoints (defaults to `'production'`)
   - `branchOverride` (string): Advanced/testing only
 
 `init` returns an `InitFlowInstance` you can listen on for `authenticationSucceeded` / `authenticationFailed`.
 
+#### Debug logging
+
+Every SDK console line is prefixed with `[melio-sdk]`, so you can filter it out of a busy
+host page. Warnings and errors — a flow whose iframe never loaded, a failed authentication,
+a `MELIO_ERROR` from the embedded app — always print. Pass `debug: true` to also get the
+step-by-step trace: the host environment, the redacted flow URLs, iframe load timings and
+every message received from the iframe. Credentials and customer details are redacted.
+
 ### Environment Configuration
 
 The SDK supports multiple environments to facilitate development and testing:
@@ -178,8 +188,37 @@ flow.on("navigated", (p)    => console.log("Navigated to:", p.target));
 - `error`: A flow error occurred (e.g. `billsSyncFailed`)
 - `exit`: The user exited the iframe
 - `navigated`: Navigation occurred inside the iframe
+- `buttonClicked`: The user clicked a button whose destination is in your product (see below)
 - `authenticationSucceeded` / `authenticationFailed`: emitted on the `init` instance
 
+#### Button clicks (`buttonClicked`)
+
+Some Melio screens contain buttons whose destination lives in **your** product, not in Melio —
+today the "+ Quick payment" button on the payments dashboard, which should take the user to
+your own supplier selection page. Melio cannot navigate the host page, so it reports the click
+and waits for you:
+
+```typescript
+const dashboard = melioSDK.openPaymentsDashboard({
+  containerId: "melio-dashboard-container",
+});
+
+dashboard.on("buttonClicked", ({ type }) => {
+  if (type === "quickPayment") {
+    window.location.assign("/suppliers/select");
+  }
+});
+```
+
+| `type` | Emitted when | What you should do |
+|---|---|---|
+| `quickPayment` | The user clicks the quick payment button on the payments dashboard | Take them to your supplier selection page, then open a pay flow |
+
+Without a listener the button does nothing at all. Only buttons whose destination is in your
+product are reported here — buttons that end a flow keep their existing events, so "Back to
+bills" still arrives as `completed`. Further button types ship in minor releases, so switch on
+`type` and treat an unrecognised value as a no-op.
+
 ## 💡 Examples
 
 ### Pay Flow

package/dist/flows/Flow.d.ts

@@ -1,4 +1,4 @@
-import { FlowInstance, FlowEventType, FlowEventCallback, FlowCompletionData, NavigationData, BaseFlowConfig, Environment, ErrorData } from '../types.js';
+import { FlowInstance, FlowEventType, FlowEventCallback, FlowCompletionData, NavigationData, ButtonClickedData, BaseFlowConfig, Environment, ErrorData } from '../types.js';
 /**
  * Flow class implementation for handling iframe flows and events
  */
@@ -13,11 +13,15 @@ export declare class Flow implements FlowInstance {
     private eventListeners;
     protected keepAliveInterval: number | null;
     private messageHandler;
+    /** When the iframe was injected, used to time load and first paint. */
+    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>;
+    /** Milliseconds since the iframe was injected, when known. */
+    private sinceInject;
     /**
      * Construct the specific flow URL - can be overridden by subclasses
      */
@@ -27,12 +31,14 @@ export declare class Flow implements FlowInstance {
      */
     protected createFlowUrl(): string;
     private setupEventListeners;
+    private handleMessage;
     /**
      * Emit events to registered listeners
      */
     protected emit(event: 'completed', data: FlowCompletionData): void;
     protected emit(event: 'loaded'): void;
     protected emit(event: 'exit'): void;
+    protected emit(event: 'buttonClicked', data: ButtonClickedData): void;
     protected emit(event: 'navigated', data: NavigationData): void;
     protected emit(event: 'authenticationSucceeded'): void;
     protected emit(event: 'authenticationFailed'): void;
@@ -44,6 +50,7 @@ export declare class Flow implements FlowInstance {
      */
     on(event: 'completed', callback: (data: FlowCompletionData) => void): void;
     on(event: 'exit', callback: () => void): void;
+    on(event: 'buttonClicked', callback: (data: ButtonClickedData) => void): void;
     on(event: 'navigated', callback: (payload: NavigationData) => void): void;
     on(event: 'authenticationSucceeded', callback: () => void): void;
     on(event: 'authenticationFailed', callback: () => void): void;

package/dist/flows/Flow.js

@@ -1,4 +1,5 @@
 import { getBaseUrl } from './utils.js';
+import { logger, describeError, describeConfig, redactUrl } from './logger.js';
 /**
  * Flow class implementation for handling iframe flows and events
  */
@@ -14,6 +15,8 @@ export class Flow {
         this.eventListeners = new Map();
         this.keepAliveInterval = null;
         this.messageHandler = null;
+        /** When the iframe was injected, used to time load and first paint. */
+        this.injectedAt = null;
         this.setupEventListeners();
     }
     /**
@@ -22,16 +25,44 @@ export class Flow {
     async initialize() {
         this.container = document.getElementById(this.containerId);
         if (!this.container) {
+            logger.error(`Container with ID "${this.containerId}" not found — the flow cannot be injected`, { readyState: document.readyState });
             throw new Error(`Container with ID "${this.containerId}" not found`);
         }
+        const url = this.createFlowUrl();
+        const safeUrl = redactUrl(url);
         this.iframe = document.createElement('iframe');
-        this.iframe.src = this.createFlowUrl();
+        this.iframe.src = url;
         this.iframe.style.width = '100%';
         this.iframe.style.height = '1000px';
         this.iframe.style.border = 'none';
         this.iframe.style.display = 'block';
+        // A cross-origin document that never loads is otherwise silent: no
+        // exception, no message, nothing in the host console.
+        this.iframe.addEventListener('error', () => {
+            logger.error('Flow iframe failed to load', {
+                url: safeUrl,
+                ...this.sinceInject(),
+            });
+        });
+        this.iframe.addEventListener('load', () => {
+            logger.debug('Flow iframe loaded', {
+                url: safeUrl,
+                ...this.sinceInject(),
+            });
+        });
+        logger.debug('Injecting flow iframe', {
+            url: safeUrl,
+            containerId: this.containerId,
+        });
+        this.injectedAt = Date.now();
         this.container.appendChild(this.iframe);
     }
+    /** Milliseconds since the iframe was injected, when known. */
+    sinceInject() {
+        return this.injectedAt === null
+            ? {}
+            : { msSinceInject: Date.now() - this.injectedAt };
+    }
     /**
      * Construct the specific flow URL - can be overridden by subclasses
      */
@@ -42,11 +73,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,58 +80,103 @@ 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;
+            // A throw here is otherwise swallowed by the browser's event dispatch,
+            // so the flow would stall with nothing in the console. Rethrown to keep
+            // the existing behaviour: the error still escapes to the host page.
+            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) {
+                logger.error('Failed to handle a message from the flow iframe', describeError(error));
+                throw error;
             }
         };
         window.addEventListener('message', this.messageHandler);
     }
+    handleMessage(event) {
+        if (!/melio\.com|melioservices\.com/.test(event.origin)) {
+            return;
+        }
+        if (typeof event.data !== 'object' || event.data === null) {
+            logger.warn('Ignoring a non-object message from a melio origin', {
+                origin: event.origin,
+                dataType: typeof event.data,
+            });
+            return;
+        }
+        const { type, ...data } = event.data;
+        logger.debug('Received message from flow iframe', {
+            type,
+            data,
+            origin: event.origin,
+            ...this.sinceInject(),
+        });
+        switch (type) {
+            case 'FLOW_COMPLETED':
+                this.emit('completed', data);
+                break;
+            case 'FLOW_EXIT':
+                this.emit('exit');
+                break;
+            case 'PARTNER_ACTION_REQUIRED':
+                if (data.data?.requiredAction === 'NAVIGATE_TO_NEW_PAYMENT') {
+                    this.emit('buttonClicked', { type: 'quickPayment' });
+                }
+                else {
+                    logger.debug('PARTNER_ACTION_REQUIRED has no matching action and was not forwarded', { requiredAction: data.data?.requiredAction });
+                }
+                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':
+                logger.debug('Flow is ready for interaction', this.sinceInject());
+                this.emit('loaded');
+                break;
+            case 'PAYMENT_SCHEDULED':
+                this.emit('completed', { flowName: 'payment', ...data });
+                break;
+            case 'MELIO_ERROR':
+                // Only one code maps to a host-facing event, so an unmapped code would
+                // otherwise be dropped silently.
+                logger.error('Embedded app reported MELIO_ERROR', {
+                    ...data,
+                    forwardedToHost: data.code === 'failed_to_sync_bills',
+                });
+                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;
+            default:
+                logger.debug('Flow iframe message type is not handled by the SDK', {
+                    type,
+                });
+        }
+    }
     emit(event, data) {
         const listeners = this.eventListeners.get(event);
         if (listeners) {
@@ -114,7 +185,7 @@ export class Flow {
                     callback(data);
                 }
                 catch (error) {
-                    console.error(`Error in ${event} event listener:`, error);
+                    logger.error(`A host listener for "${event}" threw`, describeError(error));
                 }
             });
         }
@@ -139,6 +210,7 @@ export class Flow {
      * Close the flow and clean up resources
      */
     close() {
+        logger.debug('Closing the flow', { containerId: this.containerId });
         if (this.keepAliveInterval) {
             clearInterval(this.keepAliveInterval);
             this.keepAliveInterval = null;

package/dist/flows/InitFlow.d.ts

@@ -13,7 +13,11 @@ export declare class InitFlow implements InitFlowInstance {
     private partnerName;
     private environment;
     private branchOverride?;
+    /** When the hidden iframe was injected, used to time the auth round trip. */
+    private injectedAt;
     constructor(config: InitConfig, partnerName: string, environment: Environment, branchOverride?: string);
+    /** Milliseconds since the hidden iframe was injected, when known. */
+    private sinceInject;
     /**
      * Initialize the init flow by creating and injecting a hidden iframe
      */
@@ -30,6 +34,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, describeError, redactUrl } from './logger.js';
 /**
  * Standalone InitFlow class for handling initialization with callbacks
  */
@@ -9,7 +10,10 @@ export class InitFlow {
         this.eventListeners = new Map();
         this.keepAliveInterval = null;
         this.messageHandler = null;
+        /** When the hidden iframe was injected, used to time the auth round trip. */
+        this.injectedAt = null;
         if (isEmptyString(config.authCode)) {
+            logger.error('Authorization code is required for init flow');
             throw new Error('Authorization code is required for init flow');
         }
         this.authorizationCode = config.authCode;
@@ -19,19 +23,63 @@ export class InitFlow {
         this.branchOverride = branchOverride;
         this.setupEventListeners();
     }
+    /** Milliseconds since the hidden iframe was injected, when known. */
+    sinceInject() {
+        return this.injectedAt === null
+            ? {}
+            : { msSinceInject: Date.now() - this.injectedAt };
+    }
     /**
      * 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 {
+            this.container = document.body;
+            // init() called from <head> before the parser reached <body> leaves nothing
+            // to inject into, and the flow then fails with no other symptom.
+            if (!this.container) {
+                logger.error('Cannot inject the auth iframe: document.body does not exist yet. Call init() after the document has a body.', { readyState: document.readyState });
+                throw new Error('document.body is not available');
+            }
+            const url = this.createFlowUrl();
+            safeUrl = redactUrl(url);
+            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';
+            // A cross-origin auth document that never loads is otherwise silent: no
+            // exception, no message, nothing in the host console.
+            this.iframe.addEventListener('error', () => {
+                logger.error('Auth iframe failed to load', {
+                    url: safeUrl,
+                    ...this.sinceInject(),
+                });
+            });
+            this.iframe.addEventListener('load', () => {
+                logger.debug('Auth iframe loaded', {
+                    url: safeUrl,
+                    ...this.sinceInject(),
+                });
+            });
+            logger.debug('Injecting auth iframe', {
+                url: safeUrl,
+                environment: this.environment,
+                partnerName: this.partnerName,
+            });
+            this.injectedAt = Date.now();
+            this.container.appendChild(this.iframe);
+        }
+        catch (error) {
+            logger.error('Failed to initialize the auth flow', {
+                url: safeUrl,
+                ...describeError(error),
+            });
+            throw error;
+        }
     }
     /**
      * Construct the specific flow URL for initialization
@@ -61,26 +109,55 @@ export class InitFlow {
      */
     setupEventListeners() {
         this.messageHandler = (event) => {
-            if (!/melio\.com|melioservices\.com/.test(event.origin)) {
-                return;
+            // A throw here is otherwise swallowed by the browser's event dispatch,
+            // so the flow would stall with nothing in the console. Rethrown to keep
+            // the existing behaviour: the error still escapes to the host page.
+            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) {
+                logger.error('Failed to handle a message from the auth iframe', describeError(error));
+                throw error;
             }
         };
         window.addEventListener('message', this.messageHandler);
     }
+    handleMessage(event) {
+        if (!/melio\.com|melioservices\.com/.test(event.origin)) {
+            return;
+        }
+        if (typeof event.data !== 'object' || event.data === null) {
+            logger.warn('Ignoring a non-object message from a melio origin', {
+                origin: event.origin,
+                dataType: typeof event.data,
+            });
+            return;
+        }
+        const { type, ...data } = event.data;
+        logger.debug('Received message from auth iframe', {
+            type,
+            data,
+            origin: event.origin,
+            ...this.sinceInject(),
+        });
+        switch (type) {
+            case 'AUTHENTICATION_SUCCESS':
+                logger.debug('Authentication succeeded', this.sinceInject());
+                this.emit('authenticationSucceeded');
+                break;
+            case 'AUTHENTICATION_ERROR':
+                logger.error('Authentication failed', {
+                    ...data,
+                    ...this.sinceInject(),
+                });
+                this.emit('authenticationFailed');
+                break;
+            default:
+                logger.debug('Auth iframe message type is not handled by the SDK', {
+                    type,
+                });
+        }
+    }
     /**
      * Emit events to registered listeners
      */
@@ -93,7 +170,7 @@ export class InitFlow {
                     callback(data);
                 }
                 catch (error) {
-                    console.error(`Error in ${event} event listener:`, error);
+                    logger.error(`A host listener for "${event}" threw`, describeError(error));
                 }
             });
         }
@@ -121,6 +198,7 @@ export class InitFlow {
      * Close the flow and clean up resources
      */
     close() {
+        logger.debug('Closing the auth flow');
         if (this.keepAliveInterval) {
             clearInterval(this.keepAliveInterval);
             this.keepAliveInterval = null;
@@ -137,8 +215,20 @@ export class InitFlow {
     }
     setupKeepAlive() {
         this.keepAliveInterval = window.setInterval(() => {
+            // The ping doubles as a liveness heartbeat: if these lines stop appearing
+            // while the page is still open, the host page stopped executing.
             if (this.iframe && this.iframe.contentWindow) {
-                this.iframe.contentWindow.postMessage({ type: 'USER_ACTIVE_PING' }, '*');
+                try {
+                    this.iframe.contentWindow.postMessage({ type: 'USER_ACTIVE_PING' }, '*');
+                    logger.debug('Keep-alive ping sent');
+                }
+                catch (error) {
+                    logger.error('Failed to send a keep-alive ping', describeError(error));
+                    throw error;
+                }
+            }
+            else {
+                logger.warn('Skipping the keep-alive ping: the auth iframe is gone or has no contentWindow');
             }
         }, 30000); // Send ping every 30 seconds
     }

package/dist/flows/logger.d.ts

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ */
+/**
+ * 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;
+/**
+ * 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.
+ *
+ * Never throws. Reading a thrown value can itself fail — `String()` on a
+ * null-prototype object or a throwing `toString`, `instanceof` on a revoked
+ * Proxy, a getter that throws — and this runs inside catch blocks that rethrow,
+ * so a throw here would replace the original error instead of reporting it.
+ */
+export declare const describeError: (error: unknown) => Record<string, unknown>;
+/**
+ * Shallow-copy a config with credentials and PII redacted, so it can be logged
+ * without printing customer details into the partner's console.
+ *
+ * Never throws, for the same reason as {@link describeError}.
+ */
+export declare const describeConfig: (config: object | undefined) => Record<string, unknown>;
+/**
+ * Describe the host environment once at init. The Safari regression on Xero's
+ * Bills page only reproduced on specific browser builds, and whether we run
+ * inside a frame decides which failure modes are 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,152 @@
+/**
+ * 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.
+ */
+const PREFIX = '[melio-sdk]';
+/** Query params that may carry a credential and must never reach the console. */
+const REDACTED_PARAMS = ['token', 'authCode', 'code'];
+/**
+ * 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;
+};
+const shouldLog = (level) => LEVEL_WEIGHT[level] >= minimumWeight;
+/**
+ * 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.
+ *
+ * Never throws. Reading a thrown value can itself fail — `String()` on a
+ * null-prototype object or a throwing `toString`, `instanceof` on a revoked
+ * Proxy, a getter that throws — and this runs inside catch blocks that rethrow,
+ * so a throw here would replace the original error instead of reporting it.
+ */
+export const describeError = (error) => {
+    try {
+        if (error instanceof Error) {
+            return { name: error.name, message: error.message, stack: error.stack };
+        }
+        return { thrown: String(error) };
+    }
+    catch {
+        return { thrown: '[unprintable]', thrownType: typeof error };
+    }
+};
+/**
+ * Shallow-copy a config with credentials and PII redacted, so it can be logged
+ * without printing customer details into the partner's console.
+ *
+ * Never throws, for the same reason as {@link describeError}.
+ */
+export const describeConfig = (config) => {
+    if (!config) {
+        return {};
+    }
+    try {
+        return Object.fromEntries(Object.entries(config).map(([key, value]) => [
+            key,
+            REDACTED_CONFIG_KEYS.includes(key) && value !== undefined
+                ? '[redacted]'
+                : value,
+        ]));
+    }
+    catch (error) {
+        // Object.entries invokes getters, and a host-supplied config may have one
+        // that throws.
+        return { config: '[undescribable]', reason: describeError(error) };
+    }
+};
+/**
+ * Describe the host environment once at init. The Safari regression on Xero's
+ * Bills page only reproduced on specific browser builds, and whether we run
+ * inside a frame decides which failure modes are 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;
+};
+/**
+ * Write one line, swallowing any failure.
+ *
+ * `console` belongs to the host page and may have been wrapped by something that
+ * throws. This is the outermost layer — there is nowhere left to report to — and
+ * it runs inside catch blocks that rethrow, so it must not be the reason a flow
+ * loses its original error.
+ */
+const write = (level, method, message, context) => {
+    if (!shouldLog(level)) {
+        return;
+    }
+    try {
+        console[method](`${PREFIX} ${message}`, context ?? {});
+    }
+    catch {
+        // Deliberately silent: a logger must never break its caller.
+    }
+};
+export const logger = {
+    debug(message, context) {
+        write('debug', 'log', message, context);
+    },
+    warn(message, context) {
+        write('warn', 'warn', message, context);
+    },
+    error(message, context) {
+        write('error', 'error', message, context);
+    },
+};

package/dist/index.js

@@ -1,3 +1,4 @@
+import { logger, setDebugEnabled, describeError, describeConfig, describeHost, } from './flows/logger.js';
 import { InitFlow, OnboardingFlow, PayFlow, JustPayFlow, SettingsFlow, PaymentsDashboardFlow, isEmptyString, } from './flows/index.js';
 /**
  * Main SDK implementation - now partner agnostic
@@ -15,21 +16,31 @@ export class MelioSDK {
      * Initialize the SDK - triggers auth event without creating iframe
      */
     init(authenticationCode, options) {
+        // Set before anything else so every line below honours the flag.
+        setDebugEnabled(Boolean(options.debug));
         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;
         }
         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,
+            branchOverride: this.branchOverride,
+            keepAlive: Boolean(options.keepAlive),
+            ...describeHost(),
         });
         const initFlow = new InitFlow({ authCode: authenticationCode, containerId: '' }, this.partnerName, this.environment, this.branchOverride);
-        initFlow.initialize();
-        console.log('InitFlow initialized successfully');
+        // Nothing awaits this promise, so without the catch an injection failure
+        // would leave no trace at all. Rethrown so it still surfaces as an
+        // unhandled rejection, exactly as before.
+        initFlow.initialize().catch((error) => {
+            logger.error('Init flow failed to initialize', describeError(error));
+            throw error;
+        });
         if (options.keepAlive)
             initFlow.setupKeepAlive();
         this.initFlow = initFlow;
@@ -40,10 +51,20 @@ export class MelioSDK {
      */
     openOnboarding(config) {
         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 onboarding flow.';
+            logger.error(message);
+            throw new Error(message);
         }
+        logger.debug('Opening onboarding flow', {
+            partnerName: this.partnerName,
+            environment: this.environment,
+            config: describeConfig(config),
+        });
         const flow = new OnboardingFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
+        flow.initialize().catch((error) => {
+            logger.error('Onboarding flow failed to initialize', describeError(error));
+            throw error;
+        });
         return flow;
     }
     /**
@@ -51,10 +72,20 @@ export class MelioSDK {
      */
     openPayFlow(config) {
         if (isEmptyString(this.authCode)) {
-            throw new Error('SDK not initialized. Please call init() before opening pay flow.');
+            const message = 'SDK not initialized. Please call init() before opening pay flow.';
+            logger.error(message);
+            throw new Error(message);
         }
+        logger.debug('Opening pay flow', {
+            partnerName: this.partnerName,
+            environment: this.environment,
+            config: describeConfig(config),
+        });
         const flow = new PayFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
+        flow.initialize().catch((error) => {
+            logger.error('Pay flow failed to initialize', describeError(error));
+            throw error;
+        });
         return flow;
     }
     /**
@@ -62,10 +93,20 @@ export class MelioSDK {
      */
     openJustPayFlow(config) {
         if (isEmptyString(this.authCode)) {
-            throw new Error('SDK not initialized. Please call init() before opening just pay flow.');
+            const message = 'SDK not initialized. Please call init() before opening just pay flow.';
+            logger.error(message);
+            throw new Error(message);
         }
+        logger.debug('Opening just pay flow', {
+            partnerName: this.partnerName,
+            environment: this.environment,
+            config: describeConfig(config),
+        });
         const flow = new JustPayFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
+        flow.initialize().catch((error) => {
+            logger.error('Just pay flow failed to initialize', describeError(error));
+            throw error;
+        });
         return flow;
     }
     /**
@@ -73,10 +114,20 @@ export class MelioSDK {
      */
     openSettings(config) {
         if (isEmptyString(this.authCode)) {
-            throw new Error('SDK not initialized. Please call init() before opening settings flow.');
+            const message = 'SDK not initialized. Please call init() before opening settings flow.';
+            logger.error(message);
+            throw new Error(message);
         }
+        logger.debug('Opening settings flow', {
+            partnerName: this.partnerName,
+            environment: this.environment,
+            config: describeConfig(config),
+        });
         const flow = new SettingsFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
+        flow.initialize().catch((error) => {
+            logger.error('Settings flow failed to initialize', describeError(error));
+            throw error;
+        });
         return flow;
     }
     /**
@@ -84,10 +135,20 @@ export class MelioSDK {
      */
     openPaymentsDashboard(config) {
         if (isEmptyString(this.authCode)) {
-            throw new Error('SDK not initialized. Please call init() before opening payments dashboard flow.');
+            const message = 'SDK not initialized. Please call init() before opening payments dashboard flow.';
+            logger.error(message);
+            throw new Error(message);
         }
+        logger.debug('Opening payments dashboard flow', {
+            partnerName: this.partnerName,
+            environment: this.environment,
+            config: describeConfig(config),
+        });
         const flow = new PaymentsDashboardFlow(config.containerId, config, this.partnerName, this.environment, this.authCode, this.branchOverride);
-        flow.initialize();
+        flow.initialize().catch((error) => {
+            logger.error('Payments dashboard flow failed to initialize', describeError(error));
+            throw error;
+        });
         return flow;
     }
 }

package/dist/types.d.ts

@@ -10,6 +10,11 @@ export interface InitOptions {
     partnerName: string;
     /** If true, the session will be kept alive in the background via an invisible iframe */
     keepAlive?: boolean;
+    /**
+     * If true, the SDK prints debug-level diagnostics to the console in addition to
+     * warnings and errors. Leave it off in production: warnings and errors always print.
+     */
+    debug?: boolean;
     /** The environment to use for API endpoints. Defaults to 'production' */
     environment?: Environment;
     /** The branch to use for the melio platform. Defaults to 'main' */
@@ -129,6 +134,23 @@ export interface NavigationData {
     target: string;
     targetAction: 'schedulePayment' | 'scheduleBatchPayments' | 'viewSubscriptionPlans' | 'viewSettingsCollaborators' | 'viewPayment' | 'viewPaidPayment' | 'viewBill' | 'addNewBill' | 'viewVendors' | 'addVendor' | 'viewSettings' | 'viewArInvoices' | 'redirect';
 }
+/**
+ * Which button the user clicked inside the embedded Melio app, delivered by the
+ * `buttonClicked` event.
+ *
+ * `'quickPayment'` is the new payment button on the payments dashboard: take the user to
+ * your own supplier selection page, from which you open a payment flow.
+ *
+ * @remarks
+ * Buttons that end a flow keep their existing events — "Back to bills" still arrives as
+ * `completed`.
+ *
+ * Further button types are added in minor releases, so switch on `type` and treat an
+ * unrecognised value as a no-op rather than an error.
+ */
+export interface ButtonClickedData {
+    type: 'quickPayment';
+}
 /**
  * Flow completion data
  */
@@ -150,11 +172,11 @@ export interface ErrorData {
 /**
  * Event types that can be listened to
  */
-export type FlowEventType = 'completed' | 'exit' | 'navigated' | 'authenticationSucceeded' | 'authenticationFailed' | 'error' | 'loaded' | 'onboardingCompleted' | 'onboardingRequired';
+export type FlowEventType = 'completed' | 'exit' | 'buttonClicked' | 'navigated' | 'authenticationSucceeded' | 'authenticationFailed' | 'error' | 'loaded' | 'onboardingCompleted' | 'onboardingRequired';
 /**
  * Event callback function types
  */
-export type FlowEventCallback = ((data: FlowCompletionData | NavigationData | ErrorData) => void) | (() => void);
+export type FlowEventCallback = ((data: FlowCompletionData | NavigationData | ErrorData | ButtonClickedData) => void) | (() => void);
 /**
  * Flow instance interface for event handling
  */
@@ -166,6 +188,7 @@ export interface FlowInstance {
      */
     on(event: 'completed', callback: (data: FlowCompletionData) => void): void;
     on(event: 'exit', callback: () => void): void;
+    on(event: 'buttonClicked', callback: (data: ButtonClickedData) => void): void;
     on(event: 'navigated', callback: (payload: NavigationData) => void): void;
     on(event: 'authenticationSucceeded', callback: () => void): void;
     on(event: 'authenticationFailed', callback: () => void): void;

package/package.json

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