@edge-markets/connect-node 1.0.3 → 1.3.0

package/dist/index.d.ts

@@ -1,387 +1,79 @@
 import { EdgeEnvironment, EdgeTokens, User, Balance, Transfer, ListTransfersParams, TransferList } 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';
 
-/**
- * EdgeConnectServer - Server-Side SDK for EDGE Connect
- *
- * This SDK handles operations that require your client secret:
- * - Exchanging authorization codes for tokens
- * - Refreshing access tokens
- * - Making authenticated API calls
- *
- * **Security:** This SDK should ONLY run on your backend server.
- * Never expose your client secret to the browser.
- *
- * @module @edge-markets/connect-node
- *
- * @example
- * ```typescript
- * import { EdgeConnectServer } from '@edge-markets/connect-node'
- *
- * const edge = new EdgeConnectServer({
- *   clientId: process.env.EDGE_CLIENT_ID!,
- *   clientSecret: process.env.EDGE_CLIENT_SECRET!,
- *   environment: 'staging',
- * })
- *
- * // Exchange code from EdgeLink for tokens
- * const tokens = await edge.exchangeCode(code, codeVerifier)
- *
- * // Make API calls
- * const user = await edge.getUser(tokens.accessToken)
- * const balance = await edge.getBalance(tokens.accessToken)
- * ```
- */
-
-/**
- * Configuration for EdgeConnectServer.
- *
- * All fields except `environment` are required for production use.
- */
+interface RequestInfo {
+    method: string;
+    url: string;
+    body?: unknown;
+}
+interface ResponseInfo {
+    status: number;
+    body: unknown;
+    durationMs: number;
+}
+interface RetryConfig {
+    maxRetries?: number;
+    retryOn?: number[];
+    backoff?: 'linear' | 'exponential';
+    baseDelayMs?: number;
+}
 interface EdgeConnectServerConfig {
-    /**
-     * Your OAuth client ID from the EdgeBoost partner portal.
-     */
     clientId: string;
-    /**
-     * Your OAuth client secret.
-     * **Keep this secret!** Never expose in frontend code.
-     */
     clientSecret: string;
-    /**
-     * Environment to connect to.
-     * - `'production'` - Live environment with real money
-     * - `'staging'` - Test environment for development
-     * - `'sandbox'` - Isolated mock environment (coming soon)
-     */
     environment: EdgeEnvironment;
-    /**
-     * Custom API base URL (for local development).
-     * @default Derived from environment config
-     */
     apiBaseUrl?: string;
+    oauthBaseUrl?: string;
     /**
-     * Custom Cognito domain (for local development).
-     * @default Derived from environment config
-     */
-    authDomain?: string;
-    /**
-     * Request timeout in milliseconds.
-     * @default 30000 (30 seconds)
+     * @deprecated cognitoDomain is no longer used. Token exchange now goes through EdgeBoost API.
      */
+    cognitoDomain?: string;
+    redirectUri?: string;
     timeout?: number;
+    retry?: RetryConfig;
+    onRequest?: (info: RequestInfo) => void;
+    onResponse?: (info: ResponseInfo) => void;
+    mle?: {
+        enabled: boolean;
+        edgePublicKey: string;
+        edgeKeyId: string;
+        partnerPrivateKey: string;
+        partnerKeyId: string;
+        strictResponseEncryption?: boolean;
+    };
 }
-/**
- * Options for initiating a transfer.
- */
 interface TransferOptions {
-    /**
-     * Type of transfer.
-     * - `'debit'` - Pull funds FROM user's EdgeBoost TO partner
-     * - `'credit'` - Push funds FROM partner TO user's EdgeBoost
-     */
     type: 'debit' | 'credit';
-    /**
-     * Amount in USD as a string (preserves precision).
-     * @example '100.00'
-     */
     amount: string;
-    /**
-     * Unique key to prevent duplicate transfers.
-     * If a transfer with this key exists, its current status is returned.
-     *
-     * @example `txn_${userId}_${Date.now()}`
-     */
     idempotencyKey: string;
 }
-/**
- * Server-side SDK for EDGE Connect.
- *
- * Handles token exchange and API calls that require your client secret.
- * Create one instance and reuse it for all requests.
- *
- * @example
- * ```typescript
- * // Create instance (do once, e.g., in module scope)
- * const edge = new EdgeConnectServer({
- *   clientId: process.env.EDGE_CLIENT_ID!,
- *   clientSecret: process.env.EDGE_CLIENT_SECRET!,
- *   environment: 'staging',
- * })
- *
- * // In your API route handler
- * export async function POST(req: Request) {
- *   const { code, codeVerifier } = await req.json()
- *
- *   // Exchange code for tokens
- *   const tokens = await edge.exchangeCode(code, codeVerifier)
- *
- *   // Store tokens securely (e.g., encrypted in database)
- *   await saveTokens(userId, tokens)
- *
- *   return Response.json({ success: true })
- * }
- * ```
- */
 declare class EdgeConnectServer {
     private readonly config;
     private readonly apiBaseUrl;
     private readonly oauthBaseUrl;
     private readonly timeout;
-    /**
-     * Creates a new EdgeConnectServer instance.
-     *
-     * @param config - Server configuration
-     * @throws Error if required config is missing
-     */
+    private readonly retryConfig;
+    static getInstance(config: EdgeConnectServerConfig): EdgeConnectServer;
+    static clearInstances(): void;
     constructor(config: EdgeConnectServerConfig);
-    /**
-     * 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
-     * }
-     * ```
-     */
-    exchangeCode(code: string, codeVerifier: string): Promise<EdgeTokens>;
-    /**
-     * 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)
-     * }
-     * ```
-     */
+    exchangeCode(code: string, codeVerifier: string, redirectUri?: string): Promise<EdgeTokens>;
     refreshTokens(refreshToken: string): Promise<EdgeTokens>;
-    /**
-     * 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}`)
-     * ```
-     */
     getUser(accessToken: string): Promise<User>;
-    /**
-     * 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}`)
-     * ```
-     */
     getBalance(accessToken: string): Promise<Balance>;
-    /**
-     * 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}`)
-     * }
-     * ```
-     */
     initiateTransfer(accessToken: string, options: TransferOptions): Promise<Transfer>;
-    /**
-     * 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')
-     * }
-     * ```
-     */
+    private validateTransferOptions;
     verifyTransfer(accessToken: string, transferId: string, otp: string): Promise<Transfer>;
-    /**
-     * 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}`)
-     * ```
-     */
     getTransfer(accessToken: string, transferId: string): Promise<Transfer>;
-    /**
-     * 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`)
-     * ```
-     */
     listTransfers(accessToken: string, params?: ListTransfersParams): Promise<TransferList>;
-    /**
-     * 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')
-     * ```
-     */
     revokeConsent(accessToken: string): Promise<{
         revoked: boolean;
     }>;
-    /**
-     * Makes an authenticated API request.
-     */
+    private getRetryDelay;
+    private sleep;
     private apiRequest;
-    /**
-     * Fetch with timeout support.
-     */
     private fetchWithTimeout;
-    /**
-     * Parses token response from Cognito.
-     */
     private parseTokenResponse;
-    /**
-     * Handles token exchange errors.
-     */
     private handleTokenError;
-    /**
-     * Handles API errors.
-     */
-    private handleApiError;
+    private handleApiErrorFromBody;
 }
 
-export { EdgeConnectServer, type EdgeConnectServerConfig, type TransferOptions };
+export { EdgeConnectServer, type EdgeConnectServerConfig, type RequestInfo, type ResponseInfo, type RetryConfig, type TransferOptions };