@edge-markets/connect-node 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,387 @@
+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 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;
+    /**
+     * Custom Cognito domain (for local development).
+     * @default Derived from environment config
+     */
+    authDomain?: string;
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+}
+/**
+ * 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
+     */
+    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)
+     * }
+     * ```
+     */
+    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')
+     * }
+     * ```
+     */
+    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 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;
+}
+
+export { EdgeConnectServer, type EdgeConnectServerConfig, type TransferOptions };