@edge-markets/connect-node 1.3.0 → 1.4.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { EdgeEnvironment, EdgeTokens, User, Balance, Transfer, ListTransfersParams, TransferList } from '@edge-markets/connect';
+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';
 
 interface RequestInfo {
@@ -46,6 +46,29 @@ interface TransferOptions {
     amount: string;
     idempotencyKey: string;
 }
+
+/**
+ * A lightweight, user-scoped API client created via {@link EdgeConnectServer.forUser}.
+ *
+ * Each instance holds a single access token and delegates the actual HTTP work
+ * to its parent {@link EdgeConnectServer}.
+ */
+declare class EdgeUserClient {
+    private readonly server;
+    readonly accessToken: string;
+    constructor(server: EdgeConnectServer, accessToken: string);
+    getUser(): Promise<User>;
+    verifyIdentity(options: VerifyIdentityOptions): Promise<VerifyIdentityResult>;
+    getBalance(): Promise<Balance>;
+    initiateTransfer(options: TransferOptions): Promise<Transfer>;
+    verifyTransfer(transferId: string, otp: string): Promise<Transfer>;
+    getTransfer(transferId: string): Promise<Transfer>;
+    listTransfers(params?: ListTransfersParams): Promise<TransferList>;
+    revokeConsent(): Promise<{
+        revoked: boolean;
+    }>;
+}
+
 declare class EdgeConnectServer {
     private readonly config;
     private readonly apiBaseUrl;
@@ -55,25 +78,23 @@ declare class EdgeConnectServer {
     static getInstance(config: EdgeConnectServerConfig): EdgeConnectServer;
     static clearInstances(): void;
     constructor(config: EdgeConnectServerConfig);
+    /**
+     * Create a user-scoped client for making authenticated API calls.
+     *
+     * The returned {@link EdgeUserClient} is lightweight — create one per request
+     * or per user session and discard it when the token changes.
+     */
+    forUser(accessToken: string): EdgeUserClient;
     exchangeCode(code: string, codeVerifier: string, redirectUri?: string): Promise<EdgeTokens>;
     refreshTokens(refreshToken: string): Promise<EdgeTokens>;
-    getUser(accessToken: string): Promise<User>;
-    getBalance(accessToken: string): Promise<Balance>;
-    initiateTransfer(accessToken: string, options: TransferOptions): Promise<Transfer>;
-    private validateTransferOptions;
-    verifyTransfer(accessToken: string, transferId: string, otp: string): Promise<Transfer>;
-    getTransfer(accessToken: string, transferId: string): Promise<Transfer>;
-    listTransfers(accessToken: string, params?: ListTransfersParams): Promise<TransferList>;
-    revokeConsent(accessToken: string): Promise<{
-        revoked: boolean;
-    }>;
+    /** @internal Called by {@link EdgeUserClient} — not part of the public API. */
+    _apiRequest<T>(method: string, path: string, accessToken: string, body?: unknown): Promise<T>;
     private getRetryDelay;
     private sleep;
-    private apiRequest;
     private fetchWithTimeout;
     private parseTokenResponse;
     private handleTokenError;
     private handleApiErrorFromBody;
 }
 
-export { EdgeConnectServer, type EdgeConnectServerConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type TransferOptions };
+export { EdgeConnectServer, type EdgeConnectServerConfig, EdgeUserClient, type RequestInfo, type ResponseInfo, type RetryConfig, type TransferOptions };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { EdgeEnvironment, EdgeTokens, User, Balance, Transfer, ListTransfersParams, TransferList } from '@edge-markets/connect';
+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';
 
 interface RequestInfo {
@@ -46,6 +46,29 @@ interface TransferOptions {
     amount: string;
     idempotencyKey: string;
 }
+
+/**
+ * A lightweight, user-scoped API client created via {@link EdgeConnectServer.forUser}.
+ *
+ * Each instance holds a single access token and delegates the actual HTTP work
+ * to its parent {@link EdgeConnectServer}.
+ */
+declare class EdgeUserClient {
+    private readonly server;
+    readonly accessToken: string;
+    constructor(server: EdgeConnectServer, accessToken: string);
+    getUser(): Promise<User>;
+    verifyIdentity(options: VerifyIdentityOptions): Promise<VerifyIdentityResult>;
+    getBalance(): Promise<Balance>;
+    initiateTransfer(options: TransferOptions): Promise<Transfer>;
+    verifyTransfer(transferId: string, otp: string): Promise<Transfer>;
+    getTransfer(transferId: string): Promise<Transfer>;
+    listTransfers(params?: ListTransfersParams): Promise<TransferList>;
+    revokeConsent(): Promise<{
+        revoked: boolean;
+    }>;
+}
+
 declare class EdgeConnectServer {
     private readonly config;
     private readonly apiBaseUrl;
@@ -55,25 +78,23 @@ declare class EdgeConnectServer {
     static getInstance(config: EdgeConnectServerConfig): EdgeConnectServer;
     static clearInstances(): void;
     constructor(config: EdgeConnectServerConfig);
+    /**
+     * Create a user-scoped client for making authenticated API calls.
+     *
+     * The returned {@link EdgeUserClient} is lightweight — create one per request
+     * or per user session and discard it when the token changes.
+     */
+    forUser(accessToken: string): EdgeUserClient;
     exchangeCode(code: string, codeVerifier: string, redirectUri?: string): Promise<EdgeTokens>;
     refreshTokens(refreshToken: string): Promise<EdgeTokens>;
-    getUser(accessToken: string): Promise<User>;
-    getBalance(accessToken: string): Promise<Balance>;
-    initiateTransfer(accessToken: string, options: TransferOptions): Promise<Transfer>;
-    private validateTransferOptions;
-    verifyTransfer(accessToken: string, transferId: string, otp: string): Promise<Transfer>;
-    getTransfer(accessToken: string, transferId: string): Promise<Transfer>;
-    listTransfers(accessToken: string, params?: ListTransfersParams): Promise<TransferList>;
-    revokeConsent(accessToken: string): Promise<{
-        revoked: boolean;
-    }>;
+    /** @internal Called by {@link EdgeUserClient} — not part of the public API. */
+    _apiRequest<T>(method: string, path: string, accessToken: string, body?: unknown): Promise<T>;
     private getRetryDelay;
     private sleep;
-    private apiRequest;
     private fetchWithTimeout;
     private parseTokenResponse;
     private handleTokenError;
     private handleApiErrorFromBody;
 }
 
-export { EdgeConnectServer, type EdgeConnectServerConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type TransferOptions };
+export { EdgeConnectServer, type EdgeConnectServerConfig, EdgeUserClient, type RequestInfo, type ResponseInfo, type RetryConfig, type TransferOptions };

package/dist/index.js

@@ -20,27 +20,125 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
-  EdgeApiError: () => import_connect2.EdgeApiError,
-  EdgeAuthenticationError: () => import_connect2.EdgeAuthenticationError,
+  EdgeApiError: () => import_connect3.EdgeApiError,
+  EdgeAuthenticationError: () => import_connect3.EdgeAuthenticationError,
   EdgeConnectServer: () => EdgeConnectServer,
-  EdgeConsentRequiredError: () => import_connect2.EdgeConsentRequiredError,
-  EdgeError: () => import_connect2.EdgeError,
-  EdgeInsufficientScopeError: () => import_connect2.EdgeInsufficientScopeError,
-  EdgeNetworkError: () => import_connect2.EdgeNetworkError,
-  EdgeNotFoundError: () => import_connect2.EdgeNotFoundError,
-  EdgeTokenExchangeError: () => import_connect2.EdgeTokenExchangeError,
-  getEnvironmentConfig: () => import_connect3.getEnvironmentConfig,
-  isApiError: () => import_connect2.isApiError,
-  isAuthenticationError: () => import_connect2.isAuthenticationError,
-  isConsentRequiredError: () => import_connect2.isConsentRequiredError,
-  isEdgeError: () => import_connect2.isEdgeError,
-  isNetworkError: () => import_connect2.isNetworkError,
-  isProductionEnvironment: () => import_connect3.isProductionEnvironment
+  EdgeConsentRequiredError: () => import_connect3.EdgeConsentRequiredError,
+  EdgeError: () => import_connect3.EdgeError,
+  EdgeInsufficientScopeError: () => import_connect3.EdgeInsufficientScopeError,
+  EdgeNetworkError: () => import_connect3.EdgeNetworkError,
+  EdgeNotFoundError: () => import_connect3.EdgeNotFoundError,
+  EdgeTokenExchangeError: () => import_connect3.EdgeTokenExchangeError,
+  EdgeUserClient: () => EdgeUserClient,
+  getEnvironmentConfig: () => import_connect4.getEnvironmentConfig,
+  isApiError: () => import_connect3.isApiError,
+  isAuthenticationError: () => import_connect3.isAuthenticationError,
+  isConsentRequiredError: () => import_connect3.isConsentRequiredError,
+  isEdgeError: () => import_connect3.isEdgeError,
+  isNetworkError: () => import_connect3.isNetworkError,
+  isProductionEnvironment: () => import_connect4.isProductionEnvironment
 });
 module.exports = __toCommonJS(index_exports);
 
 // src/edge-connect-server.ts
+var import_connect2 = require("@edge-markets/connect");
+
+// src/validators.ts
 var import_connect = require("@edge-markets/connect");
+function validateVerifyIdentityOptions(options) {
+  const errors = {};
+  const firstName = typeof options.firstName === "string" ? options.firstName.trim() : "";
+  if (!firstName) {
+    errors.firstName = ["firstName is required for identity verification"];
+  }
+  const lastName = typeof options.lastName === "string" ? options.lastName.trim() : "";
+  if (!lastName) {
+    errors.lastName = ["lastName is required for identity verification"];
+  }
+  if (!options.address || typeof options.address !== "object" || Array.isArray(options.address)) {
+    errors.address = ["address is required for identity verification"];
+  }
+  if (Object.keys(errors).length > 0) {
+    const firstMessage = Object.values(errors)[0][0];
+    throw new import_connect.EdgeValidationError(firstMessage, errors);
+  }
+}
+function validateTransferOptions(options) {
+  const errors = {};
+  if (!options.type || !["debit", "credit"].includes(options.type)) {
+    errors.type = ['Must be "debit" or "credit"'];
+  }
+  if (!options.amount) {
+    errors.amount = ["Amount is required"];
+  } else {
+    const amount = parseFloat(options.amount);
+    if (isNaN(amount)) {
+      errors.amount = ["Must be a valid number"];
+    } else if (amount <= 0) {
+      errors.amount = ["Must be greater than 0"];
+    } else if (!/^\d+(\.\d{1,2})?$/.test(options.amount)) {
+      errors.amount = ["Must have at most 2 decimal places"];
+    }
+  }
+  if (!options.idempotencyKey || options.idempotencyKey.trim() === "") {
+    errors.idempotencyKey = ["idempotencyKey is required"];
+  } else if (options.idempotencyKey.length > 255) {
+    errors.idempotencyKey = ["Must be 255 characters or less"];
+  }
+  if (Object.keys(errors).length > 0) {
+    throw new import_connect.EdgeValidationError("Invalid transfer options", errors);
+  }
+}
+
+// src/edge-user-client.ts
+var EdgeUserClient = class {
+  constructor(server, accessToken) {
+    this.server = server;
+    this.accessToken = accessToken;
+  }
+  async getUser() {
+    return this.server._apiRequest("GET", "/user", this.accessToken);
+  }
+  async verifyIdentity(options) {
+    validateVerifyIdentityOptions(options);
+    return this.server._apiRequest("POST", "/user/verify-identity", this.accessToken, options);
+  }
+  async getBalance() {
+    return this.server._apiRequest("GET", "/balance", this.accessToken);
+  }
+  async initiateTransfer(options) {
+    validateTransferOptions(options);
+    const body = {
+      type: options.type,
+      amount: options.amount,
+      idempotencyKey: options.idempotencyKey
+    };
+    return this.server._apiRequest("POST", "/transfer", this.accessToken, body);
+  }
+  async verifyTransfer(transferId, otp) {
+    return this.server._apiRequest(
+      "POST",
+      `/transfer/${encodeURIComponent(transferId)}/verify`,
+      this.accessToken,
+      { otp }
+    );
+  }
+  async getTransfer(transferId) {
+    return this.server._apiRequest("GET", `/transfer/${encodeURIComponent(transferId)}`, this.accessToken);
+  }
+  async listTransfers(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.limit) queryParams.set("limit", String(params.limit));
+    if (params?.offset) queryParams.set("offset", String(params.offset));
+    if (params?.status) queryParams.set("status", params.status);
+    const query = queryParams.toString();
+    const path = query ? `/transfers?${query}` : "/transfers";
+    return this.server._apiRequest("GET", path, this.accessToken);
+  }
+  async revokeConsent() {
+    return this.server._apiRequest("DELETE", "/consent", this.accessToken);
+  }
+};
 
 // src/mle.ts
 var import_crypto = require("crypto");
@@ -117,7 +215,7 @@ function fromBase64Url(value) {
   return Buffer.from(normalized, "base64");
 }
 
-// src/edge-connect-server.ts
+// src/types.ts
 var DEFAULT_TIMEOUT = 3e4;
 var USER_AGENT = "@edge-markets/connect-node/1.0.0";
 var DEFAULT_RETRY_CONFIG = {
@@ -126,6 +224,8 @@ var DEFAULT_RETRY_CONFIG = {
   backoff: "exponential",
   baseDelayMs: 1e3
 };
+
+// src/edge-connect-server.ts
 var instances = /* @__PURE__ */ new Map();
 function getInstanceKey(config) {
   return `${config.clientId}:${config.environment}`;
@@ -153,7 +253,7 @@ var EdgeConnectServer = class _EdgeConnectServer {
       throw new Error("EdgeConnectServer: environment is required");
     }
     this.config = config;
-    const envConfig = (0, import_connect.getEnvironmentConfig)(config.environment);
+    const envConfig = (0, import_connect2.getEnvironmentConfig)(config.environment);
     this.apiBaseUrl = config.apiBaseUrl || envConfig.apiBaseUrl;
     this.oauthBaseUrl = config.oauthBaseUrl || envConfig.oauthBaseUrl;
     this.timeout = config.timeout || DEFAULT_TIMEOUT;
@@ -162,6 +262,18 @@ var EdgeConnectServer = class _EdgeConnectServer {
       ...config.retry
     };
   }
+  /**
+   * Create a user-scoped client for making authenticated API calls.
+   *
+   * The returned {@link EdgeUserClient} is lightweight — create one per request
+   * or per user session and discard it when the token changes.
+   */
+  forUser(accessToken) {
+    if (!accessToken) {
+      throw new import_connect2.EdgeAuthenticationError("accessToken is required when calling forUser()");
+    }
+    return new EdgeUserClient(this, accessToken);
+  }
   async exchangeCode(code, codeVerifier, redirectUri) {
     const tokenUrl = `${this.oauthBaseUrl}/token`;
     const body = {
@@ -188,8 +300,8 @@ var EdgeConnectServer = class _EdgeConnectServer {
       const data = await response.json();
       return this.parseTokenResponse(data);
     } catch (error) {
-      if (error instanceof import_connect.EdgeError) throw error;
-      throw new import_connect.EdgeNetworkError("Failed to exchange code", error);
+      if (error instanceof import_connect2.EdgeError) throw error;
+      throw new import_connect2.EdgeNetworkError("Failed to exchange code", error);
     }
   }
   async refreshTokens(refreshToken) {
@@ -211,7 +323,7 @@ var EdgeConnectServer = class _EdgeConnectServer {
       });
       if (!response.ok) {
         const error = await response.json().catch(() => ({}));
-        throw new import_connect.EdgeAuthenticationError(
+        throw new import_connect2.EdgeAuthenticationError(
           error.message || error.error_description || "Token refresh failed. User may need to reconnect.",
           { tokenError: error }
         );
@@ -219,89 +331,12 @@ var EdgeConnectServer = class _EdgeConnectServer {
       const data = await response.json();
       return this.parseTokenResponse(data, refreshToken);
     } catch (error) {
-      if (error instanceof import_connect.EdgeError) throw error;
-      throw new import_connect.EdgeNetworkError("Failed to refresh tokens", error);
-    }
-  }
-  async getUser(accessToken) {
-    return this.apiRequest("GET", "/user", accessToken);
-  }
-  async getBalance(accessToken) {
-    return this.apiRequest("GET", "/balance", accessToken);
-  }
-  async initiateTransfer(accessToken, options) {
-    this.validateTransferOptions(options);
-    const body = {
-      type: options.type,
-      amount: options.amount,
-      idempotencyKey: options.idempotencyKey
-    };
-    return this.apiRequest("POST", "/transfer", accessToken, body);
-  }
-  validateTransferOptions(options) {
-    const errors = {};
-    if (!options.type || !["debit", "credit"].includes(options.type)) {
-      errors.type = ['Must be "debit" or "credit"'];
-    }
-    if (!options.amount) {
-      errors.amount = ["Amount is required"];
-    } else {
-      const amount = parseFloat(options.amount);
-      if (isNaN(amount)) {
-        errors.amount = ["Must be a valid number"];
-      } else if (amount <= 0) {
-        errors.amount = ["Must be greater than 0"];
-      } else if (!/^\d+(\.\d{1,2})?$/.test(options.amount)) {
-        errors.amount = ["Must have at most 2 decimal places"];
-      }
-    }
-    if (!options.idempotencyKey || options.idempotencyKey.trim() === "") {
-      errors.idempotencyKey = ["idempotencyKey is required"];
-    } else if (options.idempotencyKey.length > 255) {
-      errors.idempotencyKey = ["Must be 255 characters or less"];
-    }
-    if (Object.keys(errors).length > 0) {
-      throw new import_connect.EdgeValidationError("Invalid transfer options", errors);
-    }
-  }
-  async verifyTransfer(accessToken, transferId, otp) {
-    return this.apiRequest(
-      "POST",
-      `/transfer/${encodeURIComponent(transferId)}/verify`,
-      accessToken,
-      { otp }
-    );
-  }
-  async getTransfer(accessToken, transferId) {
-    return this.apiRequest(
-      "GET",
-      `/transfer/${encodeURIComponent(transferId)}`,
-      accessToken
-    );
-  }
-  async listTransfers(accessToken, params) {
-    const queryParams = new URLSearchParams();
-    if (params?.limit) queryParams.set("limit", String(params.limit));
-    if (params?.offset) queryParams.set("offset", String(params.offset));
-    if (params?.status) queryParams.set("status", params.status);
-    const query = queryParams.toString();
-    const path = query ? `/transfers?${query}` : "/transfers";
-    return this.apiRequest("GET", path, accessToken);
-  }
-  async revokeConsent(accessToken) {
-    return this.apiRequest("DELETE", "/consent", accessToken);
-  }
-  getRetryDelay(attempt) {
-    const { backoff, baseDelayMs } = this.retryConfig;
-    if (backoff === "exponential") {
-      return baseDelayMs * Math.pow(2, attempt);
+      if (error instanceof import_connect2.EdgeError) throw error;
+      throw new import_connect2.EdgeNetworkError("Failed to refresh tokens", error);
     }
-    return baseDelayMs * (attempt + 1);
   }
-  async sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-  async apiRequest(method, path, accessToken, body) {
+  /** @internal Called by {@link EdgeUserClient} — not part of the public API. */
+  async _apiRequest(method, path, accessToken, body) {
     const url = `${this.apiBaseUrl}${path}`;
     let lastError = null;
     const mleConfig = this.config.mle;
@@ -335,14 +370,14 @@ var EdgeConnectServer = class _EdgeConnectServer {
         if (mleEnabled && typeof rawResponseBody?.jwe === "string") {
           responseBody = decryptMle(rawResponseBody.jwe, mleConfig);
         } else if (!mleEnabled && typeof rawResponseBody?.jwe === "string") {
-          throw new import_connect.EdgeApiError(
+          throw new import_connect2.EdgeApiError(
             "mle_required",
             "The API responded with message-level encryption. Enable MLE in SDK config.",
             response.status,
             rawResponseBody
           );
         } else if (mleEnabled && mleConfig?.strictResponseEncryption !== false && response.ok && typeof rawResponseBody?.jwe !== "string") {
-          throw new import_connect.EdgeApiError(
+          throw new import_connect2.EdgeApiError(
             "mle_response_missing",
             "Expected encrypted response payload but received plaintext.",
             response.status,
@@ -360,8 +395,8 @@ var EdgeConnectServer = class _EdgeConnectServer {
         }
         return responseBody;
       } catch (error) {
-        if (error instanceof import_connect.EdgeError) {
-          if (!(error instanceof import_connect.EdgeNetworkError) || attempt >= this.retryConfig.maxRetries) {
+        if (error instanceof import_connect2.EdgeError) {
+          if (!(error instanceof import_connect2.EdgeNetworkError) || attempt >= this.retryConfig.maxRetries) {
             throw error;
           }
           lastError = error;
@@ -369,11 +404,24 @@ var EdgeConnectServer = class _EdgeConnectServer {
         }
         lastError = error;
         if (attempt >= this.retryConfig.maxRetries) {
-          throw new import_connect.EdgeNetworkError(`API request failed: ${method} ${path}`, lastError);
+          throw new import_connect2.EdgeNetworkError(`API request failed: ${method} ${path}`, lastError);
         }
       }
     }
-    throw new import_connect.EdgeNetworkError(`API request failed after ${this.retryConfig.maxRetries} retries: ${method} ${path}`, lastError);
+    throw new import_connect2.EdgeNetworkError(
+      `API request failed after ${this.retryConfig.maxRetries} retries: ${method} ${path}`,
+      lastError
+    );
+  }
+  getRetryDelay(attempt) {
+    const { backoff, baseDelayMs } = this.retryConfig;
+    if (backoff === "exponential") {
+      return baseDelayMs * Math.pow(2, attempt);
+    }
+    return baseDelayMs * (attempt + 1);
+  }
+  async sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
   }
   async fetchWithTimeout(url, options) {
     const controller = new AbortController();
@@ -401,45 +449,37 @@ var EdgeConnectServer = class _EdgeConnectServer {
     const errorCode = error.error;
     const errorMessage = error.message || error.error_description;
     if (errorCode === "invalid_grant" || errorMessage?.includes("Invalid or expired")) {
-      return new import_connect.EdgeTokenExchangeError(
-        "Authorization code is invalid, expired, or already used. Please try again.",
-        { edgeBoostError: error }
-      );
+      return new import_connect2.EdgeTokenExchangeError("Authorization code is invalid, expired, or already used. Please try again.", {
+        edgeBoostError: error
+      });
     }
     if (errorCode === "invalid_client" || errorMessage?.includes("Invalid client")) {
-      return new import_connect.EdgeAuthenticationError(
-        "Invalid client credentials. Check your client ID and secret.",
-        { edgeBoostError: error }
-      );
+      return new import_connect2.EdgeAuthenticationError("Invalid client credentials. Check your client ID and secret.", {
+        edgeBoostError: error
+      });
     }
     if (errorMessage?.includes("code_verifier") || errorMessage?.includes("PKCE")) {
-      return new import_connect.EdgeTokenExchangeError(
-        "PKCE verification failed. Please try again.",
-        { edgeBoostError: error }
-      );
+      return new import_connect2.EdgeTokenExchangeError("PKCE verification failed. Please try again.", { edgeBoostError: error });
     }
-    return new import_connect.EdgeTokenExchangeError(
-      errorMessage || "Failed to exchange authorization code",
-      { edgeBoostError: error, statusCode: status }
-    );
+    return new import_connect2.EdgeTokenExchangeError(errorMessage || "Failed to exchange authorization code", {
+      edgeBoostError: error,
+      statusCode: status
+    });
   }
   async handleApiErrorFromBody(error, status, path) {
     if (status === 401) {
-      return new import_connect.EdgeAuthenticationError(
-        error.message || "Access token is invalid or expired",
-        error
-      );
+      return new import_connect2.EdgeAuthenticationError(error.message || "Access token is invalid or expired", error);
     }
     if (status === 403) {
       if (error.error === "consent_required") {
-        return new import_connect.EdgeConsentRequiredError(
+        return new import_connect2.EdgeConsentRequiredError(
           this.config.clientId,
           error.consentUrl,
           error.message
         );
       }
       if (error.error === "insufficient_scope" || error.error === "insufficient_consent") {
-        return new import_connect.EdgeInsufficientScopeError(
+        return new import_connect2.EdgeInsufficientScopeError(
           error.missing_scopes || error.missingScopes || [],
           error.message
         );
@@ -448,9 +488,15 @@ var EdgeConnectServer = class _EdgeConnectServer {
     if (status === 404) {
       const resourceType = path.includes("/transfer") ? "Transfer" : "Resource";
       const resourceId = path.split("/").pop() || "unknown";
-      return new import_connect.EdgeNotFoundError(resourceType, resourceId);
+      return new import_connect2.EdgeNotFoundError(resourceType, resourceId);
     }
-    return new import_connect.EdgeApiError(
+    if (status === 422 && error.error === "identity_verification_failed") {
+      return new import_connect2.EdgeIdentityVerificationError(
+        error.fieldErrors || {},
+        error.message
+      );
+    }
+    return new import_connect2.EdgeApiError(
       error.error || "api_error",
       error.message || error.error_description || `Request failed with status ${status}`,
       status,
@@ -460,8 +506,8 @@ var EdgeConnectServer = class _EdgeConnectServer {
 };
 
 // src/index.ts
-var import_connect2 = require("@edge-markets/connect");
 var import_connect3 = require("@edge-markets/connect");
+var import_connect4 = require("@edge-markets/connect");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   EdgeApiError,
@@ -473,6 +519,7 @@ var import_connect3 = require("@edge-markets/connect");
   EdgeNetworkError,
   EdgeNotFoundError,
   EdgeTokenExchangeError,
+  EdgeUserClient,
   getEnvironmentConfig,
   isApiError,
   isAuthenticationError,

package/dist/index.mjs

@@ -1,17 +1,114 @@
 // src/edge-connect-server.ts
 import {
-  getEnvironmentConfig,
-  EdgeError,
+  EdgeApiError,
   EdgeAuthenticationError,
-  EdgeTokenExchangeError,
   EdgeConsentRequiredError,
+  EdgeError,
+  EdgeIdentityVerificationError,
   EdgeInsufficientScopeError,
-  EdgeApiError,
-  EdgeNotFoundError,
   EdgeNetworkError,
-  EdgeValidationError
+  EdgeNotFoundError,
+  EdgeTokenExchangeError,
+  getEnvironmentConfig
 } from "@edge-markets/connect";
 
+// src/validators.ts
+import { EdgeValidationError } from "@edge-markets/connect";
+function validateVerifyIdentityOptions(options) {
+  const errors = {};
+  const firstName = typeof options.firstName === "string" ? options.firstName.trim() : "";
+  if (!firstName) {
+    errors.firstName = ["firstName is required for identity verification"];
+  }
+  const lastName = typeof options.lastName === "string" ? options.lastName.trim() : "";
+  if (!lastName) {
+    errors.lastName = ["lastName is required for identity verification"];
+  }
+  if (!options.address || typeof options.address !== "object" || Array.isArray(options.address)) {
+    errors.address = ["address is required for identity verification"];
+  }
+  if (Object.keys(errors).length > 0) {
+    const firstMessage = Object.values(errors)[0][0];
+    throw new EdgeValidationError(firstMessage, errors);
+  }
+}
+function validateTransferOptions(options) {
+  const errors = {};
+  if (!options.type || !["debit", "credit"].includes(options.type)) {
+    errors.type = ['Must be "debit" or "credit"'];
+  }
+  if (!options.amount) {
+    errors.amount = ["Amount is required"];
+  } else {
+    const amount = parseFloat(options.amount);
+    if (isNaN(amount)) {
+      errors.amount = ["Must be a valid number"];
+    } else if (amount <= 0) {
+      errors.amount = ["Must be greater than 0"];
+    } else if (!/^\d+(\.\d{1,2})?$/.test(options.amount)) {
+      errors.amount = ["Must have at most 2 decimal places"];
+    }
+  }
+  if (!options.idempotencyKey || options.idempotencyKey.trim() === "") {
+    errors.idempotencyKey = ["idempotencyKey is required"];
+  } else if (options.idempotencyKey.length > 255) {
+    errors.idempotencyKey = ["Must be 255 characters or less"];
+  }
+  if (Object.keys(errors).length > 0) {
+    throw new EdgeValidationError("Invalid transfer options", errors);
+  }
+}
+
+// src/edge-user-client.ts
+var EdgeUserClient = class {
+  constructor(server, accessToken) {
+    this.server = server;
+    this.accessToken = accessToken;
+  }
+  async getUser() {
+    return this.server._apiRequest("GET", "/user", this.accessToken);
+  }
+  async verifyIdentity(options) {
+    validateVerifyIdentityOptions(options);
+    return this.server._apiRequest("POST", "/user/verify-identity", this.accessToken, options);
+  }
+  async getBalance() {
+    return this.server._apiRequest("GET", "/balance", this.accessToken);
+  }
+  async initiateTransfer(options) {
+    validateTransferOptions(options);
+    const body = {
+      type: options.type,
+      amount: options.amount,
+      idempotencyKey: options.idempotencyKey
+    };
+    return this.server._apiRequest("POST", "/transfer", this.accessToken, body);
+  }
+  async verifyTransfer(transferId, otp) {
+    return this.server._apiRequest(
+      "POST",
+      `/transfer/${encodeURIComponent(transferId)}/verify`,
+      this.accessToken,
+      { otp }
+    );
+  }
+  async getTransfer(transferId) {
+    return this.server._apiRequest("GET", `/transfer/${encodeURIComponent(transferId)}`, this.accessToken);
+  }
+  async listTransfers(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.limit) queryParams.set("limit", String(params.limit));
+    if (params?.offset) queryParams.set("offset", String(params.offset));
+    if (params?.status) queryParams.set("status", params.status);
+    const query = queryParams.toString();
+    const path = query ? `/transfers?${query}` : "/transfers";
+    return this.server._apiRequest("GET", path, this.accessToken);
+  }
+  async revokeConsent() {
+    return this.server._apiRequest("DELETE", "/consent", this.accessToken);
+  }
+};
+
 // src/mle.ts
 import { randomUUID, randomBytes, createCipheriv, createDecipheriv, publicEncrypt, privateDecrypt, constants } from "crypto";
 function encryptMle(payload, clientId, config) {
@@ -87,7 +184,7 @@ function fromBase64Url(value) {
   return Buffer.from(normalized, "base64");
 }
 
-// src/edge-connect-server.ts
+// src/types.ts
 var DEFAULT_TIMEOUT = 3e4;
 var USER_AGENT = "@edge-markets/connect-node/1.0.0";
 var DEFAULT_RETRY_CONFIG = {
@@ -96,6 +193,8 @@ var DEFAULT_RETRY_CONFIG = {
   backoff: "exponential",
   baseDelayMs: 1e3
 };
+
+// src/edge-connect-server.ts
 var instances = /* @__PURE__ */ new Map();
 function getInstanceKey(config) {
   return `${config.clientId}:${config.environment}`;
@@ -132,6 +231,18 @@ var EdgeConnectServer = class _EdgeConnectServer {
       ...config.retry
     };
   }
+  /**
+   * Create a user-scoped client for making authenticated API calls.
+   *
+   * The returned {@link EdgeUserClient} is lightweight — create one per request
+   * or per user session and discard it when the token changes.
+   */
+  forUser(accessToken) {
+    if (!accessToken) {
+      throw new EdgeAuthenticationError("accessToken is required when calling forUser()");
+    }
+    return new EdgeUserClient(this, accessToken);
+  }
   async exchangeCode(code, codeVerifier, redirectUri) {
     const tokenUrl = `${this.oauthBaseUrl}/token`;
     const body = {
@@ -193,85 +304,8 @@ var EdgeConnectServer = class _EdgeConnectServer {
       throw new EdgeNetworkError("Failed to refresh tokens", error);
     }
   }
-  async getUser(accessToken) {
-    return this.apiRequest("GET", "/user", accessToken);
-  }
-  async getBalance(accessToken) {
-    return this.apiRequest("GET", "/balance", accessToken);
-  }
-  async initiateTransfer(accessToken, options) {
-    this.validateTransferOptions(options);
-    const body = {
-      type: options.type,
-      amount: options.amount,
-      idempotencyKey: options.idempotencyKey
-    };
-    return this.apiRequest("POST", "/transfer", accessToken, body);
-  }
-  validateTransferOptions(options) {
-    const errors = {};
-    if (!options.type || !["debit", "credit"].includes(options.type)) {
-      errors.type = ['Must be "debit" or "credit"'];
-    }
-    if (!options.amount) {
-      errors.amount = ["Amount is required"];
-    } else {
-      const amount = parseFloat(options.amount);
-      if (isNaN(amount)) {
-        errors.amount = ["Must be a valid number"];
-      } else if (amount <= 0) {
-        errors.amount = ["Must be greater than 0"];
-      } else if (!/^\d+(\.\d{1,2})?$/.test(options.amount)) {
-        errors.amount = ["Must have at most 2 decimal places"];
-      }
-    }
-    if (!options.idempotencyKey || options.idempotencyKey.trim() === "") {
-      errors.idempotencyKey = ["idempotencyKey is required"];
-    } else if (options.idempotencyKey.length > 255) {
-      errors.idempotencyKey = ["Must be 255 characters or less"];
-    }
-    if (Object.keys(errors).length > 0) {
-      throw new EdgeValidationError("Invalid transfer options", errors);
-    }
-  }
-  async verifyTransfer(accessToken, transferId, otp) {
-    return this.apiRequest(
-      "POST",
-      `/transfer/${encodeURIComponent(transferId)}/verify`,
-      accessToken,
-      { otp }
-    );
-  }
-  async getTransfer(accessToken, transferId) {
-    return this.apiRequest(
-      "GET",
-      `/transfer/${encodeURIComponent(transferId)}`,
-      accessToken
-    );
-  }
-  async listTransfers(accessToken, params) {
-    const queryParams = new URLSearchParams();
-    if (params?.limit) queryParams.set("limit", String(params.limit));
-    if (params?.offset) queryParams.set("offset", String(params.offset));
-    if (params?.status) queryParams.set("status", params.status);
-    const query = queryParams.toString();
-    const path = query ? `/transfers?${query}` : "/transfers";
-    return this.apiRequest("GET", path, accessToken);
-  }
-  async revokeConsent(accessToken) {
-    return this.apiRequest("DELETE", "/consent", accessToken);
-  }
-  getRetryDelay(attempt) {
-    const { backoff, baseDelayMs } = this.retryConfig;
-    if (backoff === "exponential") {
-      return baseDelayMs * Math.pow(2, attempt);
-    }
-    return baseDelayMs * (attempt + 1);
-  }
-  async sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-  }
-  async apiRequest(method, path, accessToken, body) {
+  /** @internal Called by {@link EdgeUserClient} — not part of the public API. */
+  async _apiRequest(method, path, accessToken, body) {
     const url = `${this.apiBaseUrl}${path}`;
     let lastError = null;
     const mleConfig = this.config.mle;
@@ -343,7 +377,20 @@ var EdgeConnectServer = class _EdgeConnectServer {
         }
       }
     }
-    throw new EdgeNetworkError(`API request failed after ${this.retryConfig.maxRetries} retries: ${method} ${path}`, lastError);
+    throw new EdgeNetworkError(
+      `API request failed after ${this.retryConfig.maxRetries} retries: ${method} ${path}`,
+      lastError
+    );
+  }
+  getRetryDelay(attempt) {
+    const { backoff, baseDelayMs } = this.retryConfig;
+    if (backoff === "exponential") {
+      return baseDelayMs * Math.pow(2, attempt);
+    }
+    return baseDelayMs * (attempt + 1);
+  }
+  async sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
   }
   async fetchWithTimeout(url, options) {
     const controller = new AbortController();
@@ -371,34 +418,26 @@ var EdgeConnectServer = class _EdgeConnectServer {
     const errorCode = error.error;
     const errorMessage = error.message || error.error_description;
     if (errorCode === "invalid_grant" || errorMessage?.includes("Invalid or expired")) {
-      return new EdgeTokenExchangeError(
-        "Authorization code is invalid, expired, or already used. Please try again.",
-        { edgeBoostError: error }
-      );
+      return new EdgeTokenExchangeError("Authorization code is invalid, expired, or already used. Please try again.", {
+        edgeBoostError: error
+      });
     }
     if (errorCode === "invalid_client" || errorMessage?.includes("Invalid client")) {
-      return new EdgeAuthenticationError(
-        "Invalid client credentials. Check your client ID and secret.",
-        { edgeBoostError: error }
-      );
+      return new EdgeAuthenticationError("Invalid client credentials. Check your client ID and secret.", {
+        edgeBoostError: error
+      });
     }
     if (errorMessage?.includes("code_verifier") || errorMessage?.includes("PKCE")) {
-      return new EdgeTokenExchangeError(
-        "PKCE verification failed. Please try again.",
-        { edgeBoostError: error }
-      );
+      return new EdgeTokenExchangeError("PKCE verification failed. Please try again.", { edgeBoostError: error });
     }
-    return new EdgeTokenExchangeError(
-      errorMessage || "Failed to exchange authorization code",
-      { edgeBoostError: error, statusCode: status }
-    );
+    return new EdgeTokenExchangeError(errorMessage || "Failed to exchange authorization code", {
+      edgeBoostError: error,
+      statusCode: status
+    });
   }
   async handleApiErrorFromBody(error, status, path) {
     if (status === 401) {
-      return new EdgeAuthenticationError(
-        error.message || "Access token is invalid or expired",
-        error
-      );
+      return new EdgeAuthenticationError(error.message || "Access token is invalid or expired", error);
     }
     if (status === 403) {
       if (error.error === "consent_required") {
@@ -420,6 +459,12 @@ var EdgeConnectServer = class _EdgeConnectServer {
       const resourceId = path.split("/").pop() || "unknown";
       return new EdgeNotFoundError(resourceType, resourceId);
     }
+    if (status === 422 && error.error === "identity_verification_failed") {
+      return new EdgeIdentityVerificationError(
+        error.fieldErrors || {},
+        error.message
+      );
+    }
     return new EdgeApiError(
       error.error || "api_error",
       error.message || error.error_description || `Request failed with status ${status}`,
@@ -431,24 +476,21 @@ var EdgeConnectServer = class _EdgeConnectServer {
 
 // src/index.ts
 import {
-  EdgeError as EdgeError2,
+  EdgeApiError as EdgeApiError2,
   EdgeAuthenticationError as EdgeAuthenticationError2,
-  EdgeTokenExchangeError as EdgeTokenExchangeError2,
   EdgeConsentRequiredError as EdgeConsentRequiredError2,
+  EdgeError as EdgeError2,
   EdgeInsufficientScopeError as EdgeInsufficientScopeError2,
-  EdgeApiError as EdgeApiError2,
-  EdgeNotFoundError as EdgeNotFoundError2,
   EdgeNetworkError as EdgeNetworkError2,
-  isEdgeError,
+  EdgeNotFoundError as EdgeNotFoundError2,
+  EdgeTokenExchangeError as EdgeTokenExchangeError2,
+  isApiError,
   isAuthenticationError,
   isConsentRequiredError,
-  isApiError,
+  isEdgeError,
   isNetworkError
 } from "@edge-markets/connect";
-import {
-  getEnvironmentConfig as getEnvironmentConfig2,
-  isProductionEnvironment
-} from "@edge-markets/connect";
+import { getEnvironmentConfig as getEnvironmentConfig2, isProductionEnvironment } from "@edge-markets/connect";
 export {
   EdgeApiError2 as EdgeApiError,
   EdgeAuthenticationError2 as EdgeAuthenticationError,
@@ -459,6 +501,7 @@ export {
   EdgeNetworkError2 as EdgeNetworkError,
   EdgeNotFoundError2 as EdgeNotFoundError,
   EdgeTokenExchangeError2 as EdgeTokenExchangeError,
+  EdgeUserClient,
   getEnvironmentConfig2 as getEnvironmentConfig,
   isApiError,
   isAuthenticationError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edge-markets/connect-node",
-  "version": "1.3.0",
+  "version": "1.4.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.2.0"
+    "@edge-markets/connect": "^1.3.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",