@edge-markets/connect-node 1.0.3 → 1.2.0

package/dist/index.mjs

@@ -8,17 +8,33 @@ import {
   EdgeInsufficientScopeError,
   EdgeApiError,
   EdgeNotFoundError,
-  EdgeNetworkError
+  EdgeNetworkError,
+  EdgeValidationError
 } from "@edge-markets/connect";
 var DEFAULT_TIMEOUT = 3e4;
 var USER_AGENT = "@edge-markets/connect-node/1.0.0";
-var EdgeConnectServer = class {
-  /**
-   * Creates a new EdgeConnectServer instance.
-   *
-   * @param config - Server configuration
-   * @throws Error if required config is missing
-   */
+var DEFAULT_RETRY_CONFIG = {
+  maxRetries: 3,
+  retryOn: [408, 429, 500, 502, 503, 504],
+  backoff: "exponential",
+  baseDelayMs: 1e3
+};
+var instances = /* @__PURE__ */ new Map();
+function getInstanceKey(config) {
+  return `${config.clientId}:${config.environment}`;
+}
+var EdgeConnectServer = class _EdgeConnectServer {
+  static getInstance(config) {
+    const key = getInstanceKey(config);
+    const existing = instances.get(key);
+    if (existing) return existing;
+    const instance = new _EdgeConnectServer(config);
+    instances.set(key, instance);
+    return instance;
+  }
+  static clearInstances() {
+    instances.clear();
+  }
   constructor(config) {
     if (!config.clientId) {
       throw new Error("EdgeConnectServer: clientId is required");
@@ -32,66 +48,29 @@ var EdgeConnectServer = class {
     this.config = config;
     const envConfig = getEnvironmentConfig(config.environment);
     this.apiBaseUrl = config.apiBaseUrl || envConfig.apiBaseUrl;
-    this.oauthBaseUrl = envConfig.oauthBaseUrl;
+    this.oauthBaseUrl = config.oauthBaseUrl || envConfig.oauthBaseUrl;
     this.timeout = config.timeout || DEFAULT_TIMEOUT;
+    this.retryConfig = {
+      ...DEFAULT_RETRY_CONFIG,
+      ...config.retry
+    };
   }
-  // ===========================================================================
-  // TOKEN OPERATIONS
-  // ===========================================================================
-  /**
-   * Exchanges an authorization code for tokens.
-   *
-   * Call this after receiving the code from EdgeLink's `onSuccess` callback.
-   * The code is single-use and expires in ~10 minutes.
-   *
-   * @param code - Authorization code from EdgeLink
-   * @param codeVerifier - PKCE code verifier from EdgeLink
-   * @returns Access token, refresh token, and metadata
-   * @throws EdgeTokenExchangeError if exchange fails
-   *
-   * @example
-   * ```typescript
-   * // In your /api/edge/exchange endpoint
-   * const { code, codeVerifier } = req.body
-   *
-   * try {
-   *   const tokens = await edge.exchangeCode(code, codeVerifier)
-   *
-   *   // Store tokens securely
-   *   await db.edgeConnections.upsert({
-   *     userId: req.user.id,
-   *     accessToken: encrypt(tokens.accessToken),
-   *     refreshToken: encrypt(tokens.refreshToken),
-   *     expiresAt: new Date(tokens.expiresAt),
-   *   })
-   *
-   *   return { success: true }
-   * } catch (error) {
-   *   if (error instanceof EdgeTokenExchangeError) {
-   *     // Code expired or already used
-   *     return { error: 'Please try connecting again' }
-   *   }
-   *   throw error
-   * }
-   * ```
-   */
-  async exchangeCode(code, codeVerifier) {
-    const tokenUrl = `${this.oauthBaseUrl}/oauth/token`;
+  async exchangeCode(code, codeVerifier, redirectUri) {
+    const tokenUrl = `${this.oauthBaseUrl}/token`;
     const body = {
       grant_type: "authorization_code",
       code,
       code_verifier: codeVerifier,
       client_id: this.config.clientId,
-      client_secret: this.config.clientSecret
+      client_secret: this.config.clientSecret,
+      redirect_uri: redirectUri || this.config.redirectUri || ""
     };
     try {
       const response = await this.fetchWithTimeout(tokenUrl, {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          "User-Agent": USER_AGENT,
-          // Required for ngrok tunnels in local development
-          "ngrok-skip-browser-warning": "true"
+          "User-Agent": USER_AGENT
         },
         body: JSON.stringify(body)
       });
@@ -106,44 +85,8 @@ var EdgeConnectServer = class {
       throw new EdgeNetworkError("Failed to exchange code", error);
     }
   }
-  /**
-   * Refreshes an access token using a refresh token.
-   *
-   * Call this when the access token is expired or about to expire.
-   * Check `tokens.expiresAt` to know when to refresh.
-   *
-   * @param refreshToken - Refresh token from previous exchange
-   * @returns New tokens (refresh token may or may not change)
-   * @throws EdgeAuthenticationError if refresh fails
-   *
-   * @example
-   * ```typescript
-   * // Check if token needs refresh (with 5 minute buffer)
-   * const BUFFER_MS = 5 * 60 * 1000
-   *
-   * async function getValidAccessToken(userId: string): Promise<string> {
-   *   const connection = await db.edgeConnections.get(userId)
-   *
-   *   if (Date.now() > connection.expiresAt.getTime() - BUFFER_MS) {
-   *     // Token expired or expiring soon - refresh it
-   *     const newTokens = await edge.refreshTokens(decrypt(connection.refreshToken))
-   *
-   *     // Update stored tokens
-   *     await db.edgeConnections.update(userId, {
-   *       accessToken: encrypt(newTokens.accessToken),
-   *       refreshToken: encrypt(newTokens.refreshToken),
-   *       expiresAt: new Date(newTokens.expiresAt),
-   *     })
-   *
-   *     return newTokens.accessToken
-   *   }
-   *
-   *   return decrypt(connection.accessToken)
-   * }
-   * ```
-   */
   async refreshTokens(refreshToken) {
-    const tokenUrl = `${this.oauthBaseUrl}/oauth/token`;
+    const tokenUrl = `${this.oauthBaseUrl}/token`;
     const body = {
       grant_type: "refresh_token",
       refresh_token: refreshToken,
@@ -155,15 +98,14 @@ var EdgeConnectServer = class {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          "User-Agent": USER_AGENT,
-          "ngrok-skip-browser-warning": "true"
+          "User-Agent": USER_AGENT
         },
         body: JSON.stringify(body)
       });
       if (!response.ok) {
         const error = await response.json().catch(() => ({}));
         throw new EdgeAuthenticationError(
-          error.error_description || "Token refresh failed. User may need to reconnect.",
+          error.message || error.error_description || "Token refresh failed. User may need to reconnect.",
           { tokenError: error }
         );
       }
@@ -174,80 +116,14 @@ var EdgeConnectServer = class {
       throw new EdgeNetworkError("Failed to refresh tokens", error);
     }
   }
-  // ===========================================================================
-  // USER & BALANCE
-  // ===========================================================================
-  /**
-   * Gets the connected user's profile.
-   *
-   * Requires scope: `user.read`
-   *
-   * @param accessToken - Valid access token
-   * @returns User profile information
-   *
-   * @example
-   * ```typescript
-   * const user = await edge.getUser(accessToken)
-   * console.log(`Connected: ${user.firstName} ${user.lastName}`)
-   * ```
-   */
   async getUser(accessToken) {
     return this.apiRequest("GET", "/user", accessToken);
   }
-  /**
-   * Gets the connected user's EdgeBoost balance.
-   *
-   * Requires scope: `balance.read`
-   *
-   * @param accessToken - Valid access token
-   * @returns Balance information
-   *
-   * @example
-   * ```typescript
-   * const balance = await edge.getBalance(accessToken)
-   * console.log(`Balance: $${balance.availableBalance.toFixed(2)} ${balance.currency}`)
-   * ```
-   */
   async getBalance(accessToken) {
     return this.apiRequest("GET", "/balance", accessToken);
   }
-  // ===========================================================================
-  // TRANSFERS
-  // ===========================================================================
-  /**
-   * Initiates a fund transfer.
-   *
-   * Requires scope: `transfer.write`
-   *
-   * **Transfer Types:**
-   * - `debit`: Pull funds FROM user's EdgeBoost TO your platform
-   * - `credit`: Push funds FROM your platform TO user's EdgeBoost
-   *
-   * **Idempotency:** Using the same `idempotencyKey` returns the existing
-   * transfer instead of creating a duplicate. Use a unique key per transaction.
-   *
-   * **OTP Verification:** Transfers require OTP verification before completion.
-   * The response includes `otpMethod` indicating how the user will receive the code.
-   *
-   * @param accessToken - Valid access token
-   * @param options - Transfer options
-   * @returns Transfer with status and OTP method
-   *
-   * @example
-   * ```typescript
-   * const transfer = await edge.initiateTransfer(accessToken, {
-   *   type: 'debit',
-   *   amount: '100.00',
-   *   idempotencyKey: `withdraw_${userId}_${Date.now()}`,
-   * })
-   *
-   * if (transfer.status === 'pending_verification') {
-   *   // Show OTP input to user
-   *   console.log(`Enter code sent via ${transfer.otpMethod}`)
-   * }
-   * ```
-   */
   async initiateTransfer(accessToken, options) {
+    this.validateTransferOptions(options);
     const body = {
       type: options.type,
       amount: options.amount,
@@ -255,28 +131,32 @@ var EdgeConnectServer = class {
     };
     return this.apiRequest("POST", "/transfer", accessToken, body);
   }
-  /**
-   * Verifies a pending transfer with OTP.
-   *
-   * Call this after the user enters the OTP code they received.
-   * The OTP is valid for ~5 minutes.
-   *
-   * @param accessToken - Valid access token
-   * @param transferId - Transfer ID from initiateTransfer
-   * @param otp - 6-digit OTP code from user
-   * @returns Updated transfer (status will be 'completed' or 'failed')
-   *
-   * @example
-   * ```typescript
-   * const result = await edge.verifyTransfer(accessToken, transferId, userOtp)
-   *
-   * if (result.status === 'completed') {
-   *   console.log('Transfer successful!')
-   * } else if (result.status === 'failed') {
-   *   console.log('Transfer failed - possibly wrong OTP')
-   * }
-   * ```
-   */
+  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",
@@ -285,21 +165,6 @@ var EdgeConnectServer = class {
       { otp }
     );
   }
-  /**
-   * Gets the status of a transfer.
-   *
-   * Use for polling after initiating a transfer.
-   *
-   * @param accessToken - Valid access token
-   * @param transferId - Transfer ID
-   * @returns Current transfer status
-   *
-   * @example
-   * ```typescript
-   * const transfer = await edge.getTransfer(accessToken, transferId)
-   * console.log(`Status: ${transfer.status}`)
-   * ```
-   */
   async getTransfer(accessToken, transferId) {
     return this.apiRequest(
       "GET",
@@ -307,27 +172,6 @@ var EdgeConnectServer = class {
       accessToken
     );
   }
-  /**
-   * Lists transfers for the connected user.
-   *
-   * Useful for reconciliation and showing transfer history.
-   *
-   * @param accessToken - Valid access token
-   * @param params - Pagination and filter options
-   * @returns Paginated list of transfers
-   *
-   * @example
-   * ```typescript
-   * // Get first page of completed transfers
-   * const { transfers, total } = await edge.listTransfers(accessToken, {
-   *   status: 'completed',
-   *   limit: 10,
-   *   offset: 0,
-   * })
-   *
-   * console.log(`Showing ${transfers.length} of ${total} transfers`)
-   * ```
-   */
   async listTransfers(accessToken, params) {
     const queryParams = new URLSearchParams();
     if (params?.limit) queryParams.set("limit", String(params.limit));
@@ -337,68 +181,65 @@ var EdgeConnectServer = class {
     const path = query ? `/transfers?${query}` : "/transfers";
     return this.apiRequest("GET", path, accessToken);
   }
-  // ===========================================================================
-  // CONSENT
-  // ===========================================================================
-  /**
-   * Revokes the user's consent (disconnects their account).
-   *
-   * After revocation:
-   * - All API calls will fail with `consent_required` error
-   * - User must go through EdgeLink again to reconnect
-   * - Stored tokens become invalid
-   *
-   * Use this for "Disconnect" or "Unlink" features in your app.
-   *
-   * @param accessToken - Valid access token
-   * @returns Confirmation of revocation
-   *
-   * @example
-   * ```typescript
-   * // Disconnect user's EdgeBoost account
-   * await edge.revokeConsent(accessToken)
-   *
-   * // Clean up stored tokens
-   * await db.edgeConnections.delete(userId)
-   *
-   * console.log('EdgeBoost disconnected')
-   * ```
-   */
   async revokeConsent(accessToken) {
     return this.apiRequest("DELETE", "/consent", accessToken);
   }
-  // ===========================================================================
-  // PRIVATE HELPERS
-  // ===========================================================================
-  /**
-   * Makes an authenticated API request.
-   */
+  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) {
     const url = `${this.apiBaseUrl}${path}`;
-    try {
-      const response = await this.fetchWithTimeout(url, {
-        method,
-        headers: {
-          Authorization: `Bearer ${accessToken}`,
-          "Content-Type": "application/json",
-          "User-Agent": USER_AGENT,
-          // For ngrok during development
-          "ngrok-skip-browser-warning": "true"
-        },
-        body: body ? JSON.stringify(body) : void 0
-      });
-      if (!response.ok) {
-        throw await this.handleApiError(response, path);
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.retryConfig.maxRetries; attempt++) {
+      const startTime = Date.now();
+      if (attempt > 0) {
+        await this.sleep(this.getRetryDelay(attempt - 1));
+      }
+      this.config.onRequest?.({ method, url, body });
+      try {
+        const response = await this.fetchWithTimeout(url, {
+          method,
+          headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT
+          },
+          body: body ? JSON.stringify(body) : void 0
+        });
+        const responseBody = await response.json().catch(() => ({}));
+        const durationMs = Date.now() - startTime;
+        this.config.onResponse?.({ status: response.status, body: responseBody, durationMs });
+        if (!response.ok) {
+          if (this.retryConfig.retryOn.includes(response.status) && attempt < this.retryConfig.maxRetries) {
+            lastError = await this.handleApiErrorFromBody(responseBody, response.status, path);
+            continue;
+          }
+          throw await this.handleApiErrorFromBody(responseBody, response.status, path);
+        }
+        return responseBody;
+      } catch (error) {
+        if (error instanceof EdgeError) {
+          if (!(error instanceof EdgeNetworkError) || attempt >= this.retryConfig.maxRetries) {
+            throw error;
+          }
+          lastError = error;
+          continue;
+        }
+        lastError = error;
+        if (attempt >= this.retryConfig.maxRetries) {
+          throw new EdgeNetworkError(`API request failed: ${method} ${path}`, lastError);
+        }
       }
-      return response.json();
-    } catch (error) {
-      if (error instanceof EdgeError) throw error;
-      throw new EdgeNetworkError(`API request failed: ${method} ${path}`, error);
     }
+    throw new EdgeNetworkError(`API request failed after ${this.retryConfig.maxRetries} retries: ${method} ${path}`, lastError);
   }
-  /**
-   * Fetch with timeout support.
-   */
   async fetchWithTimeout(url, options) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeout);
@@ -411,9 +252,6 @@ var EdgeConnectServer = class {
       clearTimeout(timeoutId);
     }
   }
-  /**
-   * Parses token response from Cognito.
-   */
   parseTokenResponse(data, existingRefreshToken) {
     return {
       accessToken: data.access_token,
@@ -424,35 +262,33 @@ var EdgeConnectServer = class {
       scope: data.scope || ""
     };
   }
-  /**
-   * Handles token exchange errors.
-   */
   handleTokenError(error, status) {
     const errorCode = error.error;
-    const errorDescription = error.error_description;
-    if (errorCode === "invalid_grant") {
+    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.",
-        { cognitoError: error }
+        { edgeBoostError: error }
       );
     }
-    if (errorCode === "invalid_client") {
+    if (errorCode === "invalid_client" || errorMessage?.includes("Invalid client")) {
       return new EdgeAuthenticationError(
         "Invalid client credentials. Check your client ID and secret.",
-        { cognitoError: error }
+        { edgeBoostError: error }
+      );
+    }
+    if (errorMessage?.includes("code_verifier") || errorMessage?.includes("PKCE")) {
+      return new EdgeTokenExchangeError(
+        "PKCE verification failed. Please try again.",
+        { edgeBoostError: error }
       );
     }
     return new EdgeTokenExchangeError(
-      errorDescription || "Failed to exchange authorization code",
-      { cognitoError: error, statusCode: status }
+      errorMessage || "Failed to exchange authorization code",
+      { edgeBoostError: error, statusCode: status }
     );
   }
-  /**
-   * Handles API errors.
-   */
-  async handleApiError(response, path) {
-    const error = await response.json().catch(() => ({}));
-    const status = response.status;
+  async handleApiErrorFromBody(error, status, path) {
     if (status === 401) {
       return new EdgeAuthenticationError(
         error.message || "Access token is invalid or expired",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edge-markets/connect-node",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Server SDK for EDGE Connect token exchange and API calls",
   "author": "Edge Markets",
   "license": "MIT",
@@ -20,15 +20,8 @@
       }
     }
   },
-  "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest --passWithNoTests",
-    "test:run": "vitest run --passWithNoTests"
-  },
   "dependencies": {
-    "@edge-markets/connect": "^1.0.0"
+    "@edge-markets/connect": "^1.2.0"
   },
   "devDependencies": {
     "tsup": "^8.0.0",
@@ -55,7 +48,12 @@
   },
   "engines": {
     "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest --passWithNoTests",
+    "test:run": "vitest run --passWithNoTests"
   }
-}
-
-
+}