@melio-eng/web-sdk 1.0.35-pr.64.8d96d38 → 1.0.35-pr.65.956c3ca

package/README.md

@@ -1,8 +1,8 @@
 # Melio Web SDK
 
-The Melio Web SDK allows partners to embed core Melio workflows directly into the partner UI with minimal effort. It provides a high-level API for launching flows such as onboarding and pay flow, while managing authentication, lifecycle, and secure communication under the hood.
+The Melio Web SDK (`@melio-eng/web-sdk`) allows partners to embed core Melio workflows directly into the partner UI with minimal effort. It provides a high-level API for launching flows such as onboarding, payments, settings, and payments dashboard, while managing authentication, lifecycle, and secure communication under the hood.
 
-## 🚀 Quick Start
+## Quick Start
 
 ### Installation
 
@@ -19,12 +19,21 @@ import { MelioSDK } from "@melio-eng/web-sdk";
 const melioSDK = new MelioSDK();
 
 // Initialize the SDK with your authorization code
-await melioSDK.init("partner_auth_code", { 
+const initFlow = melioSDK.init("partner_auth_code", { 
   partnerName: "your-partner-name",
   keepAlive: true,
   environment: 'production' // Optional: defaults to 'production'
 });
 
+// Listen for authentication events
+initFlow.on("authenticationSucceeded", () => {
+  console.log("SDK initialized successfully");
+});
+
+initFlow.on("authenticationFailed", () => {
+  console.error("SDK initialization failed");
+});
+
 // Launch onboarding flow
 const onboardingFlow = melioSDK.openOnboarding({
   containerId: "melio-onboarding-container"
@@ -36,25 +45,33 @@ onboardingFlow.on("completed", (data) => {
 });
 ```
 
-## 📖 API Reference
+## API Reference
 
 ### Initialization
 
 ```typescript
-await melioSDK.init(authorizationCode: string, options?: InitOptions): Promise<void>
+melioSDK.init(authorizationCode: string, options: InitOptions): InitFlowInstance
 ```
 
 **Parameters:**
 - `authorizationCode` (string, required): OAuth code received from the partner
 - `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
-  - `environment` (Environment): The environment to use for API endpoints. Available options:
+  - `keepAlive` (boolean, optional): If true, the session will be kept alive in the background via an invisible iframe
+  - `environment` (Environment, optional): The environment to use for API endpoints. Defaults to `'production'`. Available options:
     - `'production'` (default): Production environment
     - `'staging01'`: Staging environment
     - `'public-qa'`: Public QA environment
     - `'certification'`: Certification environment
+    - `'eilat'`: Eilat environment
     - `'localhost'`: Local development environment
+  - `branchOverride` (string, optional): Override the CDN branch for non-production environments (useful for testing)
+
+**Returns:** `InitFlowInstance` - An object with event handling methods:
+- `on('authenticationSucceeded', callback)`: Called when authentication succeeds
+- `on('authenticationFailed', callback)`: Called when authentication fails
+- `off(event, callback)`: Remove an event listener
+- `close()`: Close the flow and clean up resources
 
 ### Environment Configuration
 
@@ -106,34 +123,76 @@ Each environment uses different base URLs:
 melioSDK.openOnboarding(config: OnboardingConfig): FlowInstance
 ```
 
-#### Single Pay Flow
+Launches the user onboarding flow for new Melio users.
+
+**Configuration:**
+- `containerId` (string, required): The ID of the DOM element to inject the flow iframe into
+- `authCode` (string, optional): Override authorization code for this flow
+- `userDetails` (object, optional): Pre-fill user information
+  - `email` (string): User's email address
+  - `firstName` (string): User's first name
+  - `lastName` (string): User's last name
+  - `dateOfBirth` (string): User's date of birth
+- `organizationDetails` (object, optional): Pre-fill organization information
+  - `companyName` (string): Company name
+  - `businessType` (string): One of `'partnership'`, `'limitedLiabilityCompany'`, `'corporation'`, `'nonProfit'`
+  - `companyLegalName` (string): Legal company name
+  - `taxId` (string): Tax ID
+  - `legalDateOfBirth` (string): Legal date of birth
+  - `website` (string): Company website
+  - `description` (string): Company description
+  - `contactPhone` (string): Contact phone number
+- `enforceOnboarding` (boolean, optional): If true, forces the onboarding flow even if user is already onboarded
+
+#### Pay Flow
 ```typescript
-melioSDK.openSinglePayFlow(config: SinglePayFlowConfig): FlowInstance
+melioSDK.openPayFlow(config: PayFlowConfig): FlowInstance
 ```
 
-#### Batch Pay Flow
-```typescript
-melioSDK.openBatchPay(config: BatchPayConfig): FlowInstance
-```
+Launches the payment flow for one or more bills. This method handles both single and batch payments.
+
+**Configuration:**
+- `containerId` (string, required): The ID of the DOM element to inject the flow iframe into
+- `authCode` (string, optional): Override authorization code for this flow
+- `billIds` (string[], required): Array of bill IDs to pay. Pass a single ID for single payment, or multiple IDs for batch payment
 
 #### Settings Flow
 ```typescript
 melioSDK.openSettings(config: SettingsConfig): FlowInstance
 ```
 
+Launches the user settings management flow.
+
+**Configuration:**
+- `containerId` (string, required): The ID of the DOM element to inject the flow iframe into
+- `authCode` (string, optional): Override authorization code for this flow
+
+#### Payments Dashboard Flow
+```typescript
+melioSDK.openPaymentsDashboard(config: PaymentsDashboardConfig): FlowInstance
+```
+
+Launches the payments dashboard flow to view payment history and status.
+
+**Configuration:**
+- `containerId` (string, required): The ID of the DOM element to inject the flow iframe into
+- `authCode` (string, optional): Override authorization code for this flow
+- `paymentId` (string, optional): Navigate directly to a specific payment
+
 ### Event Handling
 
 Each flow method returns a `FlowInstance` that allows you to register event listeners:
 
 ```typescript
-const flow = melioSDK.openSinglePayFlow({
-  billId: "melio_bill_123",
+const flow = melioSDK.openPayFlow({
+  billIds: ["melio_bill_123"],
   containerId: "melio-payflow-container"
 });
 
 // Listen for completion
 flow.on("completed", (data) => {
   console.log("Flow completed:", data);
+  // data.flowName: 'onboarding' | 'payment'
 });
 
 // Listen for exit
@@ -144,34 +203,104 @@ flow.on("exit", () => {
 // Listen for navigation
 flow.on("navigated", (payload) => {
   console.log("Navigated to:", payload.target);
+  // payload.targetAction: 'schedulePayment' | 'scheduleBatchPayments' | 'viewSubscriptionPlans' | etc.
+});
+
+// Listen for errors
+flow.on("error", (data) => {
+  console.error("Flow error:", data.errorCode);
+  // data.errorCode: 'billsSyncFailed'
+});
+
+// Listen for flow loaded
+flow.on("loaded", () => {
+  console.log("Flow iframe loaded and ready");
+});
+
+// Listen for onboarding completion (specific to onboarding flow)
+flow.on("onboardingCompleted", () => {
+  console.log("Onboarding completed");
 });
 ```
 
 **Available Events:**
-- `completed`: Called when the user successfully finishes a flow
+- `completed`: Called when the user successfully finishes a flow. Returns `FlowCompletionData` with `flowName` ('onboarding' | 'payment')
 - `exit`: Called when the user exits the iframe
-- `navigated`: Called when navigation occurs inside an iframe
-
-## 💡 Examples
+- `navigated`: Called when navigation occurs inside an iframe. Returns `NavigationData` with `target` and `targetAction`
+- `authenticationSucceeded`: Called when authentication succeeds
+- `authenticationFailed`: Called when authentication fails
+- `error`: Called when an error occurs. Returns `ErrorData` with `errorCode` (e.g., 'billsSyncFailed')
+- `loaded`: Called when the flow iframe is loaded and ready for interaction
+- `onboardingCompleted`: Called specifically when onboarding is completed
+
+**Navigation Target Actions:**
+- `schedulePayment`: User navigated to schedule a payment
+- `scheduleBatchPayments`: User navigated to schedule batch payments
+- `viewSubscriptionPlans`: User navigated to view subscription plans
+- `viewSettingsCollaborators`: User navigated to settings collaborators
+- `viewPayment`: User navigated to view a payment
+- `viewPaidPayment`: User navigated to view a paid payment
+- `viewBill`: User navigated to view a bill
+- `addNewBill`: User navigated to add a new bill
+- `viewVendors`: User navigated to view vendors
+- `addVendor`: User navigated to add a vendor
+- `viewSettings`: User navigated to view settings
+- `viewArInvoices`: User navigated to view AR invoices
+- `redirect`: User was redirected
+
+**Error Codes:**
+- `billsSyncFailed`: Bill sync failed. This can occur when:
+  - Trying to sync a non-USD bill
+  - Trying to sync an already paid bill or draft bill
+  - Trying to sync bills with an unsupported amount (amount 0 or greater than $1M)
+
+## Examples
 
 ### Basic Onboarding
 
 ```typescript
-import { melioSDK } from "@melio-eng/web-sdk";
+import { MelioSDK } from "@melio-eng/web-sdk";
+
+const melioSDK = new MelioSDK();
 
 // Initialize with production environment
-await melioSDK.init("your_auth_code", { 
+const initFlow = melioSDK.init("your_auth_code", { 
   partnerName: "your-partner-name",
   environment: 'production' 
 });
 
-// Launch onboarding
+initFlow.on("authenticationSucceeded", () => {
+  // Launch onboarding after successful authentication
+  const onboarding = melioSDK.openOnboarding({
+    containerId: "onboarding-container"
+  });
+
+  onboarding.on("completed", (data) => {
+    console.log("User completed onboarding:", data);
+  });
+});
+```
+
+### Onboarding with Pre-filled User Details
+
+```typescript
 const onboarding = melioSDK.openOnboarding({
-  containerId: "onboarding-container"
+  containerId: "onboarding-container",
+  userDetails: {
+    email: "user@example.com",
+    firstName: "John",
+    lastName: "Doe"
+  },
+  organizationDetails: {
+    companyName: "Acme Corp",
+    businessType: "corporation",
+    website: "https://acme.com"
+  },
+  enforceOnboarding: true
 });
 
-onboarding.on("completed", (data) => {
-  console.log("User completed onboarding:", data);
+onboarding.on("onboardingCompleted", () => {
+  console.log("Onboarding completed");
 });
 ```
 
@@ -179,23 +308,25 @@ onboarding.on("completed", (data) => {
 
 ```typescript
 // Initialize with staging environment for development
-await melioSDK.init("your_auth_code", { 
+const initFlow = melioSDK.init("your_auth_code", { 
   partnerName: "your-partner-name",
   environment: 'staging01',
   keepAlive: true 
 });
 
-const payFlow = melioSDK.openSinglePayFlow({
-  billId: "melio_bill_123",
-  containerId: "payment-container"
+initFlow.on("authenticationSucceeded", () => {
+  const payFlow = melioSDK.openPayFlow({
+    billIds: ["melio_bill_123"],
+    containerId: "payment-container"
+  });
 });
 ```
 
 ### Single Payment Flow
 
 ```typescript
-const payFlow = melioSDK.openSinglePayFlow({
-  billId: "melio_bill_123",
+const payFlow = melioSDK.openPayFlow({
+  billIds: ["melio_bill_123"],
   containerId: "payment-container"
 });
 
@@ -206,16 +337,17 @@ payFlow.on("completed", (data) => {
 payFlow.on("exit", () => {
   console.log("User exited payment flow");
 });
+
+payFlow.on("error", (data) => {
+  console.error("Payment error:", data.errorCode);
+});
 ```
 
 ### Batch Payment Flow
 
 ```typescript
-const batchPayFlow = melioSDK.openBatchPay({
-  bills: [
-    { billId: "melio_bill_123" },
-    { billId: "melio_bill_456" }
-  ],
+const batchPayFlow = melioSDK.openPayFlow({
+  billIds: ["melio_bill_123", "melio_bill_456", "melio_bill_789"],
   containerId: "batch-pay-container"
 });
 
@@ -224,7 +356,44 @@ batchPayFlow.on("completed", (data) => {
 });
 ```
 
-## 🧪 Testing Examples
+### Settings Flow
+
+```typescript
+const settingsFlow = melioSDK.openSettings({
+  containerId: "settings-container"
+});
+
+settingsFlow.on("navigated", (payload) => {
+  console.log("User navigated to:", payload.target);
+});
+
+settingsFlow.on("exit", () => {
+  console.log("User exited settings");
+});
+```
+
+### Payments Dashboard Flow
+
+```typescript
+// View all payments
+const dashboard = melioSDK.openPaymentsDashboard({
+  containerId: "dashboard-container"
+});
+
+// Or navigate directly to a specific payment
+const dashboardWithPayment = melioSDK.openPaymentsDashboard({
+  containerId: "dashboard-container",
+  paymentId: "payment_123"
+});
+
+dashboard.on("navigated", (payload) => {
+  if (payload.targetAction === "viewPayment") {
+    console.log("User viewing payment:", payload.target);
+  }
+});
+```
+
+## Testing Examples
 
 ### Running the Examples Locally
 
@@ -276,7 +445,7 @@ The Xero-style example includes:
   - Batch payment flows for multiple selected bills
   - Event logging and status management
 
-## 🔄 Session Keep-Alive
+## Session Keep-Alive
 
 When `keepAlive: true` is passed to `init()`, the SDK renders a hidden 1x1 pixel iframe that points to Melio's authentication endpoint. This iframe:
 
@@ -286,7 +455,7 @@ When `keepAlive: true` is passed to `init()`, the SDK renders a hidden 1x1 pixel
 
 This mechanism avoids redundant SSO handshakes and ensures seamless flow launches without delays.
 
-## 🏗️ How It Works
+## How It Works
 
 ### Session Initialization
 1. SDK uses the authorization code to perform a token exchange with Melio
@@ -303,7 +472,7 @@ This mechanism avoids redundant SSO handshakes and ensures seamless flow launche
 - SDK and Melio iframe communicate using `postMessage`
 - Navigation, height, session, and errors are synchronized
 
-## 🛠️ Development
+## Development
 
 ### Building
 
@@ -325,23 +494,23 @@ npm run docs:view   # Just view existing docs
 npm test
 ```
 
-## 📋 Requirements
+## Requirements
 
 - Modern browser with ES2020 support
 - HTTPS environment (required for iframe communication)
 - Valid Melio partner authorization code
 
-## 🔒 Security
+## Security
 
 - All communication is done over HTTPS
 - Origin validation for postMessage communication
 - Session tokens are managed securely
 - No sensitive data is stored in localStorage
 
-## 🤝 Support
+## Support
 
 For support, please contact the Melio team or create an issue in this repository.
 
-## 📄 License
+## License
 
-MIT 
+MIT            

package/package.json

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