@melio-eng/web-sdk 1.1.0 → 1.2.0-pr.94.cf53d50

package/README.md

@@ -178,8 +178,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
  */
@@ -33,6 +33,7 @@ export declare class Flow implements FlowInstance {
     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 +45,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

@@ -77,6 +77,13 @@ export class Flow {
                 case 'FLOW_EXIT':
                     this.emit('exit');
                     break;
+                case 'PARTNER_ACTION_REQUIRED':
+                    // Only the quick payment button is reported today; every other
+                    // requiredAction is ignored until the SDK declares a type for it.
+                    if (data.data?.requiredAction === 'NAVIGATE_TO_NEW_PAYMENT') {
+                        this.emit('buttonClicked', { type: 'quickPayment' });
+                    }
+                    break;
                 case 'NAVIGATED_TO_TARGET':
                     this.emit('navigated', data);
                     break;

package/dist/types.d.ts

@@ -129,6 +129,26 @@ 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
+ * Melio cannot navigate your page, so a button with no listener registered visibly does
+ * nothing when clicked.
+ *
+ * Only buttons whose destination lives in your product are reported here. 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 +170,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 +186,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.94.cf53d50",
   "description": "Melio Web SDK - Embed core Melio workflows directly into partner UI with minimal effort",
   "main": "dist/index.js",
   "module": "dist/index.js",