@edge-markets/connect-node 1.0.0

package/dist/index.js

@@ -0,0 +1,543 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  EdgeApiError: () => import_connect2.EdgeApiError,
+  EdgeAuthenticationError: () => import_connect2.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
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/edge-connect-server.ts
+var import_connect = require("@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
+   */
+  constructor(config) {
+    if (!config.clientId) {
+      throw new Error("EdgeConnectServer: clientId is required");
+    }
+    if (!config.clientSecret) {
+      throw new Error("EdgeConnectServer: clientSecret is required");
+    }
+    if (!config.environment) {
+      throw new Error("EdgeConnectServer: environment is required");
+    }
+    this.config = config;
+    const envConfig = (0, import_connect.getEnvironmentConfig)(config.environment);
+    this.apiBaseUrl = config.apiBaseUrl || envConfig.apiBaseUrl;
+    this.oauthBaseUrl = envConfig.oauthBaseUrl;
+    this.timeout = config.timeout || DEFAULT_TIMEOUT;
+  }
+  // ===========================================================================
+  // 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`;
+    const body = {
+      grant_type: "authorization_code",
+      code,
+      code_verifier: codeVerifier,
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret
+    };
+    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"
+        },
+        body: JSON.stringify(body)
+      });
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({}));
+        throw this.handleTokenError(error, response.status);
+      }
+      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);
+    }
+  }
+  /**
+   * 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 body = {
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: this.config.clientId,
+      client_secret: this.config.clientSecret
+    };
+    try {
+      const response = await this.fetchWithTimeout(tokenUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          "User-Agent": USER_AGENT,
+          "ngrok-skip-browser-warning": "true"
+        },
+        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.",
+          { tokenError: error }
+        );
+      }
+      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);
+    }
+  }
+  // ===========================================================================
+  // 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) {
+    const body = {
+      type: options.type,
+      amount: options.amount,
+      idempotencyKey: options.idempotencyKey
+    };
+    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')
+   * }
+   * ```
+   */
+  async verifyTransfer(accessToken, transferId, otp) {
+    return this.apiRequest(
+      "POST",
+      `/transfer/${encodeURIComponent(transferId)}/verify`,
+      accessToken,
+      { 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",
+      `/transfer/${encodeURIComponent(transferId)}`,
+      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));
+    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);
+  }
+  // ===========================================================================
+  // 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.
+   */
+  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);
+      }
+      return response.json();
+    } catch (error) {
+      if (error instanceof import_connect.EdgeError) throw error;
+      throw new import_connect.EdgeNetworkError(`API request failed: ${method} ${path}`, error);
+    }
+  }
+  /**
+   * Fetch with timeout support.
+   */
+  async fetchWithTimeout(url, options) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(url, {
+        ...options,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Parses token response from Cognito.
+   */
+  parseTokenResponse(data, existingRefreshToken) {
+    return {
+      accessToken: data.access_token,
+      refreshToken: data.refresh_token || existingRefreshToken || "",
+      idToken: data.id_token,
+      expiresIn: data.expires_in,
+      expiresAt: Date.now() + data.expires_in * 1e3,
+      scope: data.scope || ""
+    };
+  }
+  /**
+   * Handles token exchange errors.
+   */
+  handleTokenError(error, status) {
+    const errorCode = error.error;
+    const errorDescription = error.error_description;
+    if (errorCode === "invalid_grant") {
+      return new import_connect.EdgeTokenExchangeError(
+        "Authorization code is invalid, expired, or already used. Please try again.",
+        { cognitoError: error }
+      );
+    }
+    if (errorCode === "invalid_client") {
+      return new import_connect.EdgeAuthenticationError(
+        "Invalid client credentials. Check your client ID and secret.",
+        { cognitoError: error }
+      );
+    }
+    return new import_connect.EdgeTokenExchangeError(
+      errorDescription || "Failed to exchange authorization code",
+      { cognitoError: error, statusCode: status }
+    );
+  }
+  /**
+   * Handles API errors.
+   */
+  async handleApiError(response, path) {
+    const error = await response.json().catch(() => ({}));
+    const status = response.status;
+    if (status === 401) {
+      return new import_connect.EdgeAuthenticationError(
+        error.message || "Access token is invalid or expired",
+        error
+      );
+    }
+    if (status === 403) {
+      if (error.error === "consent_required") {
+        return new import_connect.EdgeConsentRequiredError(
+          this.config.clientId,
+          error.consentUrl,
+          error.message
+        );
+      }
+      if (error.error === "insufficient_scope" || error.error === "insufficient_consent") {
+        return new import_connect.EdgeInsufficientScopeError(
+          error.missing_scopes || error.missingScopes || [],
+          error.message
+        );
+      }
+    }
+    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_connect.EdgeApiError(
+      error.error || "api_error",
+      error.message || error.error_description || `Request failed with status ${status}`,
+      status,
+      error
+    );
+  }
+};
+
+// src/index.ts
+var import_connect2 = require("@edge-markets/connect");
+var import_connect3 = require("@edge-markets/connect");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EdgeApiError,
+  EdgeAuthenticationError,
+  EdgeConnectServer,
+  EdgeConsentRequiredError,
+  EdgeError,
+  EdgeInsufficientScopeError,
+  EdgeNetworkError,
+  EdgeNotFoundError,
+  EdgeTokenExchangeError,
+  getEnvironmentConfig,
+  isApiError,
+  isAuthenticationError,
+  isConsentRequiredError,
+  isEdgeError,
+  isNetworkError,
+  isProductionEnvironment
+});