@edge-markets/connect-node 1.0.0

package/dist/index.mjs

@@ -0,0 +1,528 @@
+// src/edge-connect-server.ts
+import {
+  getEnvironmentConfig,
+  EdgeError,
+  EdgeAuthenticationError,
+  EdgeTokenExchangeError,
+  EdgeConsentRequiredError,
+  EdgeInsufficientScopeError,
+  EdgeApiError,
+  EdgeNotFoundError,
+  EdgeNetworkError
+} 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
+   */
+  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 = 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 EdgeError) throw error;
+      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 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 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 EdgeError) throw error;
+      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) {
+    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 EdgeError) throw error;
+      throw new 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 EdgeTokenExchangeError(
+        "Authorization code is invalid, expired, or already used. Please try again.",
+        { cognitoError: error }
+      );
+    }
+    if (errorCode === "invalid_client") {
+      return new EdgeAuthenticationError(
+        "Invalid client credentials. Check your client ID and secret.",
+        { cognitoError: error }
+      );
+    }
+    return new 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 EdgeAuthenticationError(
+        error.message || "Access token is invalid or expired",
+        error
+      );
+    }
+    if (status === 403) {
+      if (error.error === "consent_required") {
+        return new EdgeConsentRequiredError(
+          this.config.clientId,
+          error.consentUrl,
+          error.message
+        );
+      }
+      if (error.error === "insufficient_scope" || error.error === "insufficient_consent") {
+        return new 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 EdgeNotFoundError(resourceType, resourceId);
+    }
+    return new EdgeApiError(
+      error.error || "api_error",
+      error.message || error.error_description || `Request failed with status ${status}`,
+      status,
+      error
+    );
+  }
+};
+
+// src/index.ts
+import {
+  EdgeError as EdgeError2,
+  EdgeAuthenticationError as EdgeAuthenticationError2,
+  EdgeTokenExchangeError as EdgeTokenExchangeError2,
+  EdgeConsentRequiredError as EdgeConsentRequiredError2,
+  EdgeInsufficientScopeError as EdgeInsufficientScopeError2,
+  EdgeApiError as EdgeApiError2,
+  EdgeNotFoundError as EdgeNotFoundError2,
+  EdgeNetworkError as EdgeNetworkError2,
+  isEdgeError,
+  isAuthenticationError,
+  isConsentRequiredError,
+  isApiError,
+  isNetworkError
+} from "@edge-markets/connect";
+import {
+  getEnvironmentConfig as getEnvironmentConfig2,
+  isProductionEnvironment
+} from "@edge-markets/connect";
+export {
+  EdgeApiError2 as EdgeApiError,
+  EdgeAuthenticationError2 as EdgeAuthenticationError,
+  EdgeConnectServer,
+  EdgeConsentRequiredError2 as EdgeConsentRequiredError,
+  EdgeError2 as EdgeError,
+  EdgeInsufficientScopeError2 as EdgeInsufficientScopeError,
+  EdgeNetworkError2 as EdgeNetworkError,
+  EdgeNotFoundError2 as EdgeNotFoundError,
+  EdgeTokenExchangeError2 as EdgeTokenExchangeError,
+  getEnvironmentConfig2 as getEnvironmentConfig,
+  isApiError,
+  isAuthenticationError,
+  isConsentRequiredError,
+  isEdgeError,
+  isNetworkError,
+  isProductionEnvironment
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@edge-markets/connect-node",
+  "version": "1.0.0",
+  "description": "Server SDK for EDGE Connect token exchange and API calls",
+  "author": "Edge Markets",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "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",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "@edge-markets/connect": "workspace:^"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "edgeboost",
+    "edge-connect",
+    "sdk",
+    "server",
+    "oauth",
+    "token-exchange",
+    "api-client"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/edgeboost/edge-connect-sdk.git",
+    "directory": "packages/server"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}
+
+