@edge-markets/connect-node 1.4.0 → 1.5.0

package/README.md

@@ -6,7 +6,7 @@ Server SDK for EDGE Connect token exchange and API calls.
 
 - 🔐 **Secure token exchange** - Exchange codes for tokens with PKCE
 - 🔄 **Token refresh** - Automatic refresh token handling
-- 📡 **Full API client** - User, balance, transfers
+- 📡 **Full API client** - User, balance, transfers via `forUser()` pattern
 - 🛡️ **Typed errors** - Specific error classes for each scenario
 - 📝 **TypeScript first** - Complete type definitions
 
@@ -23,7 +23,7 @@ yarn add @edge-markets/connect-node
 ## Quick Start
 
 ```typescript
-import { EdgeConnectServer } from '@edgeboost/edge-connect-server'
+import { EdgeConnectServer } from '@edge-markets/connect-node'
 
 // Create instance once (reuse for all requests)
 const edge = new EdgeConnectServer({
@@ -35,9 +35,10 @@ const edge = new EdgeConnectServer({
 // Exchange code from EdgeLink for tokens
 const tokens = await edge.exchangeCode(code, codeVerifier)
 
-// Make API calls
-const user = await edge.getUser(tokens.accessToken)
-const balance = await edge.getBalance(tokens.accessToken)
+// Create a user-scoped client and make API calls
+const client = edge.forUser(tokens.accessToken)
+const user = await client.getUser()
+const balance = await client.getBalance()
 ```
 
 ## ⚠️ Security
@@ -56,8 +57,11 @@ interface EdgeConnectServerConfig {
   
   // Optional
   apiBaseUrl?: string           // Custom API URL (dev only)
-  authDomain?: string           // Custom Cognito domain (dev only)
+  oauthBaseUrl?: string         // Custom OAuth URL (dev only)
   timeout?: number              // Request timeout (default: 30000ms)
+  retry?: RetryConfig           // Retry configuration
+  onRequest?: (info) => void    // Hook called before each request
+  onResponse?: (info) => void   // Hook called after each response
 
   // Optional: Message Level Encryption (Connect endpoints only)
   mle?: {
@@ -152,15 +156,19 @@ async function getValidAccessToken(userId: string): Promise<string> {
 
 ## API Methods
 
+All user-scoped API methods live on `EdgeUserClient`, created via `edge.forUser(accessToken)`:
+
+```typescript
+const client = edge.forUser(accessToken)
+```
+
 ### User & Balance
 
 ```typescript
-// Get user profile
-const user = await edge.getUser(accessToken)
+const user = await client.getUser()
 // Returns: { id, email, firstName, lastName, createdAt }
 
-// Get balance
-const balance = await edge.getBalance(accessToken)
+const balance = await client.getBalance()
 // Returns: { userId, availableBalance, currency, asOf }
 ```
 
@@ -168,7 +176,7 @@ const balance = await edge.getBalance(accessToken)
 
 ```typescript
 // Initiate transfer (requires OTP verification)
-const transfer = await edge.initiateTransfer(accessToken, {
+const transfer = await client.initiateTransfer({
   type: 'debit',           // 'debit' = pull from user, 'credit' = push to user
   amount: '100.00',
   idempotencyKey: `txn_${userId}_${Date.now()}`,
@@ -176,14 +184,14 @@ const transfer = await edge.initiateTransfer(accessToken, {
 // Returns: { transferId, status: 'pending_verification', otpMethod }
 
 // Verify with OTP
-const result = await edge.verifyTransfer(accessToken, transfer.transferId, userOtp)
+const result = await client.verifyTransfer(transfer.transferId, userOtp)
 // Returns: { transferId, status: 'completed' | 'failed' }
 
 // Get transfer status
-const status = await edge.getTransfer(accessToken, transferId)
+const status = await client.getTransfer(transferId)
 
 // List transfers
-const { transfers, total } = await edge.listTransfers(accessToken, {
+const { transfers, total } = await client.listTransfers({
   status: 'completed',
   limit: 10,
   offset: 0,
@@ -194,7 +202,7 @@ const { transfers, total } = await edge.listTransfers(accessToken, {
 
 ```typescript
 // Revoke consent (disconnect user)
-await edge.revokeConsent(accessToken)
+await client.revokeConsent()
 
 // Clean up stored tokens
 await db.edgeConnections.delete(userId)
@@ -212,7 +220,8 @@ import {
 } from '@edge-markets/connect-node'
 
 try {
-  const balance = await edge.getBalance(accessToken)
+  const client = edge.forUser(accessToken)
+  const balance = await client.getBalance()
 } catch (error) {
   if (error instanceof EdgeAuthenticationError) {
     // Token expired - try refresh or reconnect
@@ -273,7 +282,8 @@ export class EdgeService {
 
   async getBalance(accessToken: string) {
     try {
-      return await this.edge.getBalance(accessToken)
+      const client = this.edge.forUser(accessToken)
+      return await client.getBalance()
     } catch (error) {
       if (error instanceof EdgeConsentRequiredError) {
         this.logger.warn('User consent required')
@@ -323,7 +333,8 @@ app.post('/api/edge/exchange', async (req, res) => {
 app.get('/api/edge/balance', async (req, res) => {
   try {
     const accessToken = await getAccessTokenForUser(req.user.id)
-    const balance = await edge.getBalance(accessToken)
+    const client = edge.forUser(accessToken)
+    const balance = await client.getBalance()
     res.json(balance)
   } catch (error) {
     // Handle errors...
@@ -339,10 +350,3 @@ app.get('/api/edge/balance', async (req, res) => {
 ## License
 
 MIT
-
-
-
-
-
-
-

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { EdgeEnvironment, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, EdgeTokens } from '@edge-markets/connect';
-export { Balance, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, ListTransfersParams, Transfer, TransferList, TransferListItem, TransferStatus, TransferType, User, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
+import { EdgeEnvironment, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSession, VerificationSessionStatusResponse, EdgeTokens } from '@edge-markets/connect';
+export { Balance, CreateVerificationSessionRequest, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, ListTransfersParams, Transfer, TransferList, TransferListItem, TransferStatus, TransferType, User, VerificationSession, VerificationSessionStatus, VerificationSessionStatusResponse, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
 
 interface RequestInfo {
     method: string;
@@ -67,6 +67,17 @@ declare class EdgeUserClient {
     revokeConsent(): Promise<{
         revoked: boolean;
     }>;
+    /**
+     * Creates an EDGE-hosted transfer verification session.
+     * Returns a `verificationUrl` to open in an iframe or popup.
+     * The handoff token is single-use and expires in 120 seconds.
+     */
+    createVerificationSession(transferId: string, options: CreateVerificationSessionRequest): Promise<VerificationSession>;
+    /**
+     * Polls the status of a verification session.
+     * Use as an alternative to postMessage events.
+     */
+    getVerificationSessionStatus(transferId: string, sessionId: string): Promise<VerificationSessionStatusResponse>;
 }
 
 declare class EdgeConnectServer {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { EdgeEnvironment, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, EdgeTokens } from '@edge-markets/connect';
-export { Balance, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, ListTransfersParams, Transfer, TransferList, TransferListItem, TransferStatus, TransferType, User, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
+import { EdgeEnvironment, User, VerifyIdentityOptions, VerifyIdentityResult, Balance, Transfer, ListTransfersParams, TransferList, CreateVerificationSessionRequest, VerificationSession, VerificationSessionStatusResponse, EdgeTokens } from '@edge-markets/connect';
+export { Balance, CreateVerificationSessionRequest, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeInsufficientScopeError, EdgeNetworkError, EdgeNotFoundError, EdgeTokenExchangeError, EdgeTokens, ListTransfersParams, Transfer, TransferList, TransferListItem, TransferStatus, TransferType, User, VerificationSession, VerificationSessionStatus, VerificationSessionStatusResponse, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isEdgeError, isNetworkError, isProductionEnvironment } from '@edge-markets/connect';
 
 interface RequestInfo {
     method: string;
@@ -67,6 +67,17 @@ declare class EdgeUserClient {
     revokeConsent(): Promise<{
         revoked: boolean;
     }>;
+    /**
+     * Creates an EDGE-hosted transfer verification session.
+     * Returns a `verificationUrl` to open in an iframe or popup.
+     * The handoff token is single-use and expires in 120 seconds.
+     */
+    createVerificationSession(transferId: string, options: CreateVerificationSessionRequest): Promise<VerificationSession>;
+    /**
+     * Polls the status of a verification session.
+     * Use as an alternative to postMessage events.
+     */
+    getVerificationSessionStatus(transferId: string, sessionId: string): Promise<VerificationSessionStatusResponse>;
 }
 
 declare class EdgeConnectServer {

package/dist/index.js

@@ -138,6 +138,30 @@ var EdgeUserClient = class {
   async revokeConsent() {
     return this.server._apiRequest("DELETE", "/consent", this.accessToken);
   }
+  /**
+   * Creates an EDGE-hosted transfer verification session.
+   * Returns a `verificationUrl` to open in an iframe or popup.
+   * The handoff token is single-use and expires in 120 seconds.
+   */
+  async createVerificationSession(transferId, options) {
+    return this.server._apiRequest(
+      "POST",
+      `/transfer/${encodeURIComponent(transferId)}/verification-session`,
+      this.accessToken,
+      { origin: options.origin }
+    );
+  }
+  /**
+   * Polls the status of a verification session.
+   * Use as an alternative to postMessage events.
+   */
+  async getVerificationSessionStatus(transferId, sessionId) {
+    return this.server._apiRequest(
+      "GET",
+      `/transfer/${encodeURIComponent(transferId)}/verification-session/${encodeURIComponent(sessionId)}`,
+      this.accessToken
+    );
+  }
 };
 
 // src/mle.ts
@@ -486,8 +510,21 @@ var EdgeConnectServer = class _EdgeConnectServer {
       }
     }
     if (status === 404) {
-      const resourceType = path.includes("/transfer") ? "Transfer" : "Resource";
-      const resourceId = path.split("/").pop() || "unknown";
+      let resourceType = "Resource";
+      let resourceId = path.split("/").pop() || "unknown";
+      if (path.includes("/verification-session/")) {
+        resourceType = "VerificationSession";
+        const parts = path.split("/");
+        const vsIdx = parts.indexOf("verification-session");
+        resourceId = vsIdx >= 0 && parts[vsIdx + 1] ? parts[vsIdx + 1] : "unknown";
+      } else if (path.includes("/verification-session")) {
+        resourceType = "Transfer";
+        const parts = path.split("/");
+        const txIdx = parts.indexOf("transfer");
+        resourceId = txIdx >= 0 && parts[txIdx + 1] ? parts[txIdx + 1] : "unknown";
+      } else if (path.includes("/transfer")) {
+        resourceType = "Transfer";
+      }
       return new import_connect2.EdgeNotFoundError(resourceType, resourceId);
     }
     if (status === 422 && error.error === "identity_verification_failed") {

package/dist/index.mjs

@@ -107,6 +107,30 @@ var EdgeUserClient = class {
   async revokeConsent() {
     return this.server._apiRequest("DELETE", "/consent", this.accessToken);
   }
+  /**
+   * Creates an EDGE-hosted transfer verification session.
+   * Returns a `verificationUrl` to open in an iframe or popup.
+   * The handoff token is single-use and expires in 120 seconds.
+   */
+  async createVerificationSession(transferId, options) {
+    return this.server._apiRequest(
+      "POST",
+      `/transfer/${encodeURIComponent(transferId)}/verification-session`,
+      this.accessToken,
+      { origin: options.origin }
+    );
+  }
+  /**
+   * Polls the status of a verification session.
+   * Use as an alternative to postMessage events.
+   */
+  async getVerificationSessionStatus(transferId, sessionId) {
+    return this.server._apiRequest(
+      "GET",
+      `/transfer/${encodeURIComponent(transferId)}/verification-session/${encodeURIComponent(sessionId)}`,
+      this.accessToken
+    );
+  }
 };
 
 // src/mle.ts
@@ -455,8 +479,21 @@ var EdgeConnectServer = class _EdgeConnectServer {
       }
     }
     if (status === 404) {
-      const resourceType = path.includes("/transfer") ? "Transfer" : "Resource";
-      const resourceId = path.split("/").pop() || "unknown";
+      let resourceType = "Resource";
+      let resourceId = path.split("/").pop() || "unknown";
+      if (path.includes("/verification-session/")) {
+        resourceType = "VerificationSession";
+        const parts = path.split("/");
+        const vsIdx = parts.indexOf("verification-session");
+        resourceId = vsIdx >= 0 && parts[vsIdx + 1] ? parts[vsIdx + 1] : "unknown";
+      } else if (path.includes("/verification-session")) {
+        resourceType = "Transfer";
+        const parts = path.split("/");
+        const txIdx = parts.indexOf("transfer");
+        resourceId = txIdx >= 0 && parts[txIdx + 1] ? parts[txIdx + 1] : "unknown";
+      } else if (path.includes("/transfer")) {
+        resourceType = "Transfer";
+      }
       return new EdgeNotFoundError(resourceType, resourceId);
     }
     if (status === 422 && error.error === "identity_verification_failed") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edge-markets/connect-node",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Server SDK for EDGE Connect token exchange and API calls",
   "author": "Edge Markets",
   "license": "MIT",
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@edge-markets/connect": "^1.3.0"
+    "@edge-markets/connect": "^1.4.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",