@edge-markets/connect-node 1.0.3 → 1.3.0

package/dist/index.js

@@ -41,15 +41,107 @@ module.exports = __toCommonJS(index_exports);
 
 // src/edge-connect-server.ts
 var import_connect = require("@edge-markets/connect");
+
+// src/mle.ts
+var import_crypto = require("crypto");
+function encryptMle(payload, clientId, config) {
+  const header = {
+    alg: "RSA-OAEP-256",
+    enc: "A256GCM",
+    kid: config.edgeKeyId,
+    typ: "application/json",
+    iat: Math.floor(Date.now() / 1e3),
+    jti: (0, import_crypto.randomUUID)(),
+    clientId
+  };
+  const protectedHeaderB64 = toBase64Url(Buffer.from(JSON.stringify(header), "utf8"));
+  const aad = Buffer.from(protectedHeaderB64, "utf8");
+  const cek = (0, import_crypto.randomBytes)(32);
+  const iv = (0, import_crypto.randomBytes)(12);
+  const cipher = (0, import_crypto.createCipheriv)("aes-256-gcm", cek, iv);
+  cipher.setAAD(aad);
+  const plaintext = Buffer.from(JSON.stringify(payload), "utf8");
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  const encryptedKey = (0, import_crypto.publicEncrypt)(
+    {
+      key: config.edgePublicKey,
+      padding: import_crypto.constants.RSA_PKCS1_OAEP_PADDING,
+      oaepHash: "sha256"
+    },
+    cek
+  );
+  return [
+    protectedHeaderB64,
+    toBase64Url(encryptedKey),
+    toBase64Url(iv),
+    toBase64Url(ciphertext),
+    toBase64Url(tag)
+  ].join(".");
+}
+function decryptMle(jwe, config) {
+  const parts = jwe.split(".");
+  if (parts.length !== 5) {
+    throw new Error("Invalid MLE payload format");
+  }
+  const [protectedHeaderB64, encryptedKeyB64, ivB64, ciphertextB64, tagB64] = parts;
+  const protectedHeader = JSON.parse(fromBase64Url(protectedHeaderB64).toString("utf8"));
+  if (protectedHeader.alg !== "RSA-OAEP-256" || protectedHeader.enc !== "A256GCM") {
+    throw new Error("Unsupported MLE algorithms");
+  }
+  if (protectedHeader.kid && protectedHeader.kid !== config.partnerKeyId) {
+    throw new Error(`Unexpected response key id: ${protectedHeader.kid}`);
+  }
+  const cek = (0, import_crypto.privateDecrypt)(
+    {
+      key: config.partnerPrivateKey,
+      padding: import_crypto.constants.RSA_PKCS1_OAEP_PADDING,
+      oaepHash: "sha256"
+    },
+    fromBase64Url(encryptedKeyB64)
+  );
+  const decipher = (0, import_crypto.createDecipheriv)("aes-256-gcm", cek, fromBase64Url(ivB64));
+  decipher.setAAD(Buffer.from(protectedHeaderB64, "utf8"));
+  decipher.setAuthTag(fromBase64Url(tagB64));
+  const plaintext = Buffer.concat([
+    decipher.update(fromBase64Url(ciphertextB64)),
+    decipher.final()
+  ]);
+  return JSON.parse(plaintext.toString("utf8"));
+}
+function toBase64Url(buffer) {
+  return buffer.toString("base64").replace(/=/g, "").replace(/\+/g, "-").replace(/\//g, "_");
+}
+function fromBase64Url(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+  return Buffer.from(normalized, "base64");
+}
+
+// src/edge-connect-server.ts
 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");
@@ -63,66 +155,29 @@ var EdgeConnectServer = class {
     this.config = config;
     const envConfig = (0, import_connect.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)
       });
@@ -137,44 +192,8 @@ var EdgeConnectServer = class {
       throw new import_connect.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,
@@ -186,15 +205,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 import_connect.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 }
         );
       }
@@ -205,80 +223,14 @@ var EdgeConnectServer = class {
       throw new import_connect.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,
@@ -286,28 +238,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 import_connect.EdgeValidationError("Invalid transfer options", errors);
+    }
+  }
   async verifyTransfer(accessToken, transferId, otp) {
     return this.apiRequest(
       "POST",
@@ -316,21 +272,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",
@@ -338,27 +279,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));
@@ -368,68 +288,93 @@ 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: {
+    let lastError = null;
+    const mleConfig = this.config.mle;
+    const mleEnabled = !!mleConfig?.enabled;
+    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 requestHeaders = {
           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);
+          "User-Agent": USER_AGENT
+        };
+        let requestBody = body;
+        if (mleEnabled) {
+          requestHeaders["X-Edge-MLE"] = "v1";
+          if (body !== void 0) {
+            requestBody = { jwe: encryptMle(body, this.config.clientId, mleConfig) };
+          }
+        }
+        const response = await this.fetchWithTimeout(url, {
+          method,
+          headers: requestHeaders,
+          body: requestBody !== void 0 ? JSON.stringify(requestBody) : void 0
+        });
+        const rawResponseBody = await response.json().catch(() => ({}));
+        let responseBody = rawResponseBody;
+        if (mleEnabled && typeof rawResponseBody?.jwe === "string") {
+          responseBody = decryptMle(rawResponseBody.jwe, mleConfig);
+        } else if (!mleEnabled && typeof rawResponseBody?.jwe === "string") {
+          throw new import_connect.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(
+            "mle_response_missing",
+            "Expected encrypted response payload but received plaintext.",
+            response.status,
+            rawResponseBody
+          );
+        }
+        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 import_connect.EdgeError) {
+          if (!(error instanceof import_connect.EdgeNetworkError) || attempt >= this.retryConfig.maxRetries) {
+            throw error;
+          }
+          lastError = error;
+          continue;
+        }
+        lastError = error;
+        if (attempt >= this.retryConfig.maxRetries) {
+          throw new import_connect.EdgeNetworkError(`API request failed: ${method} ${path}`, lastError);
+        }
       }
-      return response.json();
-    } catch (error) {
-      if (error instanceof import_connect.EdgeError) throw error;
-      throw new import_connect.EdgeNetworkError(`API request failed: ${method} ${path}`, error);
     }
+    throw new import_connect.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);
@@ -442,9 +387,6 @@ var EdgeConnectServer = class {
       clearTimeout(timeoutId);
     }
   }
-  /**
-   * Parses token response from Cognito.
-   */
   parseTokenResponse(data, existingRefreshToken) {
     return {
       accessToken: data.access_token,
@@ -455,35 +397,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 import_connect.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 import_connect.EdgeAuthenticationError(
         "Invalid client credentials. Check your client ID and secret.",
-        { cognitoError: error }
+        { 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_connect.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 import_connect.EdgeAuthenticationError(
         error.message || "Access token is invalid or expired",