@melio-eng/web-sdk 1.0.38 → 1.0.39-pr.83.c745e85

package/README.md

@@ -2,6 +2,11 @@
 
 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.
 
+## 📚 Documentation
+
+- **[Pay Flow Integration Guide](./guides/pay-flow-integration.md)** — the full end-to-end guide for embedding Melio payments (backend `prepare` call, auth code, SDK setup, events, testing checklist). **Start here.**
+- **[SDK Reference](https://melio.github.io/web-sdk/)** — auto-generated API reference for every class, config, and event.
+
 ## 🚀 Quick Start
 
 ### Installation
@@ -19,42 +24,48 @@ import { MelioSDK } from "@melio-eng/web-sdk";
 const melioSDK = new MelioSDK();
 
 // Initialize the SDK with your authorization code
-await melioSDK.init("partner_auth_code", { 
-  partnerName: "your-partner-name",
-  keepAlive: true,
-  environment: 'production' // Optional: defaults to 'production'
+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
 });
 
-// Launch onboarding flow
-const onboardingFlow = melioSDK.openOnboarding({
-  containerId: "melio-onboarding-container"
+init.on("authenticationSucceeded", () => {
+  // Open the Pay Flow with the Melio bill IDs returned by /pay-flow/prepare
+  const payFlow = melioSDK.openPayFlow({
+    containerId: "melio-payflow-container",
+    billIds: ["bill_abc123"],
+  });
+
+  payFlow.on("completed", (data) => {
+    console.log("Payment completed:", data);
+  });
 });
 
-// Listen for completion
-onboardingFlow.on("completed", (data) => {
-  console.log("Onboarding completed:", data);
+init.on("authenticationFailed", () => {
+  // Re-mint the auth code on your backend and retry
 });
 ```
 
+> The full integration (backend `POST /pay-flow/prepare`, minting the auth code, and handling every event) is documented in the **[Pay Flow Integration Guide](./guides/pay-flow-integration.md)**.
+
 ## 📖 API Reference
 
 ### Initialization
 
 ```typescript
-await melioSDK.init(authorizationCode: string, options?: InitOptions): Promise<void>
+melioSDK.init(authenticationCode: string, options: InitOptions): InitFlowInstance
 ```
 
 **Parameters:**
-- `authorizationCode` (string, required): OAuth code received from the partner
+- `authenticationCode` (string, required): short-lived, user-scoped code minted on your backend
 - `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:
-    - `'production'` (default): Production environment
-    - `'staging01'`: Staging environment
-    - `'public-qa'`: Public QA environment
-    - `'certification'`: Certification environment
-    - `'localhost'`: Local development environment
+  - `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`.
 
 ### Environment Configuration
 
@@ -62,61 +73,59 @@ The SDK supports multiple environments to facilitate development and testing:
 
 ```typescript
 // Production (default)
-await melioSDK.init("auth_code", { 
-  partnerName: "your-partner-name",
-  environment: 'production' 
-});
+melioSDK.init("auth_code", { partnerName: "your-partner-name", environment: "production" });
 
 // Staging
-await melioSDK.init("auth_code", { 
-  partnerName: "your-partner-name",
-  environment: 'staging01' 
-});
+melioSDK.init("auth_code", { partnerName: "your-partner-name", environment: "staging01" });
 
 // Public QA
-await melioSDK.init("auth_code", { 
-  partnerName: "your-partner-name",
-  environment: 'public-qa' 
-});
+melioSDK.init("auth_code", { partnerName: "your-partner-name", environment: "public-qa" });
 
 // Certification
-await melioSDK.init("auth_code", { 
-  partnerName: "your-partner-name",
-  environment: 'certification' 
-});
+melioSDK.init("auth_code", { partnerName: "your-partner-name", environment: "certification" });
 
 // Localhost (for local development)
-await melioSDK.init("auth_code", { 
-  partnerName: "your-partner-name",
-  environment: 'localhost' 
-});
+melioSDK.init("auth_code", { partnerName: "your-partner-name", environment: "localhost" });
 ```
 
-Each environment uses different base URLs:
-- **Production**: `https://partnerships.melioservices.com`
-- **Staging01**: `https://partnerships.staging01.melioservices.com`
-- **Public QA**: `https://partnerships.public-qa.melioservices.com`
-- **Certification**: `https://partnerships.certification.melioservices.com`
-- **Localhost**: `http://localhost:3005`
+Each environment uses a different base URL:
+
+| Environment | SDK `environment` | API base URL |
+|---|---|---|
+| Production | `production` (default) | `https://partnerships.melioservices.com` |
+| Staging | `staging01` | `https://partnerships.staging01.melioservices.com` |
+| Public QA | `public-qa` | `https://partnerships.public-qa.melioservices.com` |
+| Certification | `certification` | `https://partnerships.certification.melioservices.com` |
+| Localhost | `localhost` | `http://localhost:3005` |
 
 ### Flow Methods
 
-#### Onboarding Flow
+#### Pay Flow
+Pay one or more bills. Pass the **Melio bill IDs** returned by `POST /pay-flow/prepare`.
 ```typescript
-melioSDK.openOnboarding(config: OnboardingConfig): FlowInstance
+melioSDK.openPayFlow(config: PayFlowConfig): FlowInstance
 ```
 
-#### Single Pay Flow
+#### Just Pay Flow
+Vendor-based payment (start from a vendor rather than a specific bill).
 ```typescript
-melioSDK.openSinglePayFlow(config: SinglePayFlowConfig): FlowInstance
+melioSDK.openJustPayFlow(config: JustPayFlowConfig): FlowInstance
 ```
 
-#### Batch Pay Flow
+#### Payments Dashboard Flow
+Let users view and manage their payments inside your product.
 ```typescript
-melioSDK.openBatchPay(config: BatchPayConfig): FlowInstance
+melioSDK.openPaymentsDashboard(config: PaymentsDashboardConfig): FlowInstance
+```
+
+#### Onboarding Flow
+Collect any missing account / KYC information directly in Melio.
+```typescript
+melioSDK.openOnboarding(config: OnboardingConfig): FlowInstance
 ```
 
 #### Settings Flow
+Host Melio account settings within your product.
 ```typescript
 melioSDK.openSettings(config: SettingsConfig): FlowInstance
 ```
@@ -126,155 +135,90 @@ melioSDK.openSettings(config: SettingsConfig): FlowInstance
 Each flow method returns a `FlowInstance` that allows you to register event listeners:
 
 ```typescript
-const flow = melioSDK.openSinglePayFlow({
-  billId: "melio_bill_123",
-  containerId: "melio-payflow-container"
-});
-
-// Listen for completion
-flow.on("completed", (data) => {
-  console.log("Flow completed:", data);
+const flow = melioSDK.openPayFlow({
+  containerId: "melio-payflow-container",
+  billIds: ["bill_abc123"],
 });
 
-// Listen for exit
-flow.on("exit", () => {
-  console.log("User exited the flow");
-});
-
-// Listen for navigation
-flow.on("navigated", (payload) => {
-  console.log("Navigated to:", payload.target);
-});
+flow.on("loaded",    ()     => console.log("Flow rendered"));
+flow.on("completed", (data) => console.log("Payment completed:", data));
+flow.on("error",     (err)  => console.warn("Flow error:", err.errorCode));
+flow.on("exit",      ()     => console.log("User exited the flow"));
+flow.on("navigated", (p)    => console.log("Navigated to:", p.target));
 ```
 
 **Available Events:**
-- `completed`: Called when the user successfully finishes a flow
-- `exit`: Called when the user exits the iframe
-- `navigated`: Called when navigation occurs inside an iframe
+- `loaded`: The flow iframe has rendered
+- `completed`: The user successfully finished a flow
+- `error`: A flow error occurred (e.g. `billsSyncFailed`)
+- `exit`: The user exited the iframe
+- `navigated`: Navigation occurred inside the iframe
+- `authenticationSucceeded` / `authenticationFailed`: emitted on the `init` instance
 
 ## 💡 Examples
 
-### Basic Onboarding
+### Pay Flow
 
 ```typescript
-import { melioSDK } from "@melio-eng/web-sdk";
-
-// Initialize with production environment
-await melioSDK.init("your_auth_code", { 
-  partnerName: "your-partner-name",
-  environment: 'production' 
+const payFlow = melioSDK.openPayFlow({
+  containerId: "melio-payflow-container",
+  billIds: ["bill_abc123", "bill_def456"],   // Melio bill IDs from /pay-flow/prepare
 });
 
-// Launch onboarding
-const onboarding = melioSDK.openOnboarding({
-  containerId: "onboarding-container"
+payFlow.on("completed", (data) => {
+  console.log("Payment completed:", data);
 });
 
-onboarding.on("completed", (data) => {
-  console.log("User completed onboarding:", data);
+payFlow.on("exit", () => {
+  console.log("User exited the payment flow");
 });
 ```
 
 ### Development with Staging Environment
 
 ```typescript
-// Initialize with staging environment for development
-await melioSDK.init("your_auth_code", { 
+const init = melioSDK.init("your_auth_code", {
   partnerName: "your-partner-name",
-  environment: 'staging01',
-  keepAlive: true 
-});
-
-const payFlow = melioSDK.openSinglePayFlow({
-  billId: "melio_bill_123",
-  containerId: "payment-container"
-});
-```
-
-### Single Payment Flow
-
-```typescript
-const payFlow = melioSDK.openSinglePayFlow({
-  billId: "melio_bill_123",
-  containerId: "payment-container"
-});
-
-payFlow.on("completed", (data) => {
-  console.log("Payment completed:", data);
+  environment: "staging01",
+  keepAlive: true,
 });
 
-payFlow.on("exit", () => {
-  console.log("User exited payment flow");
+init.on("authenticationSucceeded", () => {
+  melioSDK.openPayFlow({
+    containerId: "payment-container",
+    billIds: ["bill_abc123"],
+  });
 });
 ```
 
-### Batch Payment Flow
+### Onboarding
 
 ```typescript
-const batchPayFlow = melioSDK.openBatchPay({
-  bills: [
-    { billId: "melio_bill_123" },
-    { billId: "melio_bill_456" }
-  ],
-  containerId: "batch-pay-container"
+const onboarding = melioSDK.openOnboarding({
+  containerId: "onboarding-container",
 });
 
-batchPayFlow.on("completed", (data) => {
-  console.log("Batch payment completed:", data);
+onboarding.on("completed", (data) => {
+  console.log("User completed onboarding:", data);
 });
 ```
 
-## 🧪 Testing Examples
-
-### Running the Examples Locally
+## 🧪 Running the Examples Locally
 
-The repository includes interactive examples that demonstrate the SDK functionality:
+The repository includes interactive examples that demonstrate the SDK functionality. They render a partner-style accounting UI (navigation, tabs, a bills table with single and batch selection) and wire the SDK into it end-to-end.
 
-#### Basic Usage Example
-```bash
-npm run examples:basic
-```
-Opens `http://localhost:3000/examples/basic-usage.html`
-
-#### Xero-Style Bill Pay Example
-```bash
-npm run examples:bill-pay
-```
-Opens `http://localhost:3000/examples/bill-pay-example.html`
-
-This example demonstrates:
-- **Xero-inspired UI**: Professional accounting interface with navigation, tabs, and tables
-- **Automatic SDK Initialization**: SDK initializes immediately on page load
-- **Interactive Bill Management**: 
-  - Checkbox selection for batch payments
-  - Individual "Pay bill" buttons for single payments
-  - Real-time total calculation
-  - Status updates after payment completion
-- **Full Integration**: Shows how the SDK integrates seamlessly into existing partner interfaces
-- **Responsive Design**: Modern UI with proper spacing, typography, and interactions
-
-#### All Examples Server
 ```bash
+# Serve all examples in the /examples directory
 npm run examples
 ```
-Starts a server on port 3000 serving all examples in the `/examples` directory.
-
-### Example Features
-
-The Xero-style example includes:
-- **Professional Header**: Company branding, navigation, and user controls
-- **Tab Navigation**: Filter bills by status (All, Draft, Awaiting payment, etc.)
-- **Search & Filters**: Date ranges, search functionality, and column controls
-- **Interactive Table**: 
-  - Checkbox selection with "Select All" functionality
-  - Status tags (Awaiting payment, Paid)
-  - Individual and batch payment options
-  - Real-time status updates
-- **SDK Integration**: 
-  - Automatic initialization with demo auth code
-  - Single payment flows for individual bills
-  - Batch payment flows for multiple selected bills
-  - Event logging and status management
+
+Then open the example HTML files (e.g. `http://localhost:3009/examples/basic-usage.html` or `http://localhost:3009/examples/bill-pay-example.html`).
+
+The bill-pay example demonstrates:
+- **Automatic SDK initialization** on page load
+- **Interactive bill management**: checkbox selection for batch payments, individual "Pay bill" buttons, real-time totals, and status updates after completion
+- **Full integration**: how the SDK slots into an existing partner interface
+- **Event logging** for every flow lifecycle event
 
 ## 🔄 Session Keep-Alive
 
@@ -290,14 +234,14 @@ This mechanism avoids redundant SSO handshakes and ensures seamless flow launche
 
 ### Session Initialization
 1. SDK uses the authorization code to perform a token exchange with Melio
-2. Melio receives the user's email from the partner
+2. Melio receives the user's identity from the partner
 3. Melio generates a new access token and initializes the session used for iframe-based flows
 4. A valid session is stored in local/session storage
 5. All future flows reuse this session if it is still valid
 
 ### iframe Injection
 1. SDK creates and injects an iframe into the specified `containerId`
-2. It builds an `authUrl` with token, target, entrypoint, and context (e.g., billId)
+2. It builds an `authUrl` with token, target, entrypoint, and context (e.g., billIds)
 
 ### Communication
 - SDK and Melio iframe communicate using `postMessage`
@@ -314,9 +258,9 @@ npm run build
 ### Documentation
 
 ```bash
-npm run docs
-npm run docs:serve  # Generate docs and start local server
-npm run docs:view   # Just view existing docs
+npm run docs        # generate the SDK reference + guides
+npm run docs:serve  # generate docs and start a local server
+npm run docs:view   # view already-generated docs
 ```
 
 ### Testing
@@ -336,7 +280,7 @@ npm test
 - All communication is done over HTTPS
 - Origin validation for postMessage communication
 - Session tokens are managed securely
-- No sensitive data is stored in localStorage
+- Your API key is used server-to-server only — never in the browser
 
 ## 🤝 Support
 
@@ -344,4 +288,4 @@ For support, please contact the Melio team or create an issue in this repository
 
 ## 📄 License
 
-MIT 
+MIT

package/dist/types.d.ts

@@ -43,7 +43,7 @@ export interface UserDetails {
 }
 /**
  * Entry point context for the flow, used to construct the externalOrigin parameter.
- * When provided, the externalOrigin becomes `${partnerName}-${entryPoint}` (e.g., 'xero-contacts').
+ * When provided, the externalOrigin becomes `${partnerName}-${entryPoint}` (e.g., 'your-partner-name-contacts').
  */
 export type ExternalEntryPoint = 'contacts';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@melio-eng/web-sdk",
-  "version": "1.0.38",
+  "version": "1.0.39-pr.83.c745e85",
   "description": "Melio Web SDK - Embed core Melio workflows directly into partner UI with minimal effort",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -9,7 +9,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "docs": "typedoc --out docs src/index.ts",
+    "docs": "typedoc --out docs src/index.ts && node scripts/copy-api-explorer.mjs",
     "docs:watch": "typedoc --out docs --watch src/index.ts",
     "docs:serve": "npm run docs && serve docs -p 8000",
     "docs:view": "serve docs -p 8000",
@@ -45,8 +45,10 @@
     "jest-environment-jsdom": "^30.0.5",
     "serve": "^14.2.4",
     "ts-jest": "^29.1.0",
-    "typedoc": "^0.25.0",
-    "typescript": "^5.0.0"
+    "typedoc": "^0.26.11",
+    "typedoc-plugin-mermaid": "^1.12.0",
+    "typescript": "^5.0.0",
+    "yaml": "^2.9.0"
   },
   "files": [
     "dist",