@edge-markets/connect-node 1.0.0

package/README.md

@@ -0,0 +1,314 @@
+# @edgeboost/edge-connect-server
+
+Server SDK for EDGE Connect token exchange and API calls.
+
+## Features
+
+- 🔐 **Secure token exchange** - Exchange codes for tokens with PKCE
+- 🔄 **Token refresh** - Automatic refresh token handling
+- 📡 **Full API client** - User, balance, transfers
+- 🛡️ **Typed errors** - Specific error classes for each scenario
+- 📝 **TypeScript first** - Complete type definitions
+
+## Installation
+
+```bash
+npm install @edgeboost/edge-connect-server
+# or
+pnpm add @edgeboost/edge-connect-server
+# or
+yarn add @edgeboost/edge-connect-server
+```
+
+## Quick Start
+
+```typescript
+import { EdgeConnectServer } from '@edgeboost/edge-connect-server'
+
+// Create instance once (reuse for all requests)
+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)
+```
+
+## ⚠️ Security
+
+**This SDK requires your client secret. Use it ONLY on your backend server!**
+
+Never expose your client secret to browsers or client-side code.
+
+## Configuration
+
+```typescript
+interface EdgeConnectServerConfig {
+  clientId: string              // Your OAuth client ID
+  clientSecret: string          // Your OAuth client secret (keep secret!)
+  environment: EdgeEnvironment  // 'production' | 'staging' | 'sandbox'
+  
+  // Optional
+  apiBaseUrl?: string           // Custom API URL (dev only)
+  authDomain?: string           // Custom Cognito domain (dev only)
+  timeout?: number              // Request timeout (default: 30000ms)
+}
+```
+
+## Token Exchange
+
+After EdgeLink completes, exchange the code for tokens:
+
+```typescript
+// In your /api/edge/exchange endpoint
+export async function POST(req: Request) {
+  const { code, codeVerifier } = await req.json()
+  
+  try {
+    const tokens = await edge.exchangeCode(code, codeVerifier)
+    
+    // Store tokens securely (encrypted in database)
+    await db.edgeConnections.upsert({
+      userId: req.user.id,
+      accessToken: encrypt(tokens.accessToken),
+      refreshToken: encrypt(tokens.refreshToken),
+      expiresAt: new Date(tokens.expiresAt),
+    })
+    
+    return Response.json({ success: true })
+  } catch (error) {
+    if (error instanceof EdgeTokenExchangeError) {
+      // Code expired or already used
+      return Response.json({ error: 'Please try again' }, { status: 400 })
+    }
+    throw error
+  }
+}
+```
+
+## Token Refresh
+
+Refresh tokens before they expire:
+
+```typescript
+async function getValidAccessToken(userId: string): Promise<string> {
+  const connection = await db.edgeConnections.get(userId)
+  
+  // Refresh 5 minutes before expiry
+  const BUFFER = 5 * 60 * 1000
+  
+  if (Date.now() > connection.expiresAt.getTime() - BUFFER) {
+    const newTokens = await edge.refreshTokens(
+      decrypt(connection.refreshToken)
+    )
+    
+    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)
+}
+```
+
+## API Methods
+
+### User & Balance
+
+```typescript
+// Get user profile
+const user = await edge.getUser(accessToken)
+// Returns: { id, email, firstName, lastName, createdAt }
+
+// Get balance
+const balance = await edge.getBalance(accessToken)
+// Returns: { userId, availableBalance, currency, asOf }
+```
+
+### Transfers
+
+```typescript
+// Initiate transfer (requires OTP verification)
+const transfer = await edge.initiateTransfer(accessToken, {
+  type: 'debit',           // 'debit' = pull from user, 'credit' = push to user
+  amount: '100.00',
+  idempotencyKey: `txn_${userId}_${Date.now()}`,
+})
+// Returns: { transferId, status: 'pending_verification', otpMethod }
+
+// Verify with OTP
+const result = await edge.verifyTransfer(accessToken, transfer.transferId, userOtp)
+// Returns: { transferId, status: 'completed' | 'failed' }
+
+// Get transfer status
+const status = await edge.getTransfer(accessToken, transferId)
+
+// List transfers
+const { transfers, total } = await edge.listTransfers(accessToken, {
+  status: 'completed',
+  limit: 10,
+  offset: 0,
+})
+```
+
+### Consent
+
+```typescript
+// Revoke consent (disconnect user)
+await edge.revokeConsent(accessToken)
+
+// Clean up stored tokens
+await db.edgeConnections.delete(userId)
+```
+
+## Error Handling
+
+```typescript
+import {
+  EdgeError,
+  EdgeAuthenticationError,
+  EdgeTokenExchangeError,
+  EdgeConsentRequiredError,
+  isEdgeError,
+} from '@edgeboost/edge-connect-server'
+
+try {
+  const balance = await edge.getBalance(accessToken)
+} catch (error) {
+  if (error instanceof EdgeAuthenticationError) {
+    // Token expired - try refresh or reconnect
+    return { error: 'session_expired' }
+  }
+  
+  if (error instanceof EdgeConsentRequiredError) {
+    // User revoked consent - need to reconnect
+    return { error: 'reconnect_required' }
+  }
+  
+  if (isEdgeError(error)) {
+    // Some other SDK error
+    console.error(`Edge Error [${error.code}]: ${error.message}`)
+    return { error: error.code }
+  }
+  
+  // Unknown error
+  throw error
+}
+```
+
+### Error Types
+
+| Error | When | What to do |
+|-------|------|------------|
+| `EdgeAuthenticationError` | Token invalid/expired | Refresh token or reconnect |
+| `EdgeTokenExchangeError` | Code exchange failed | Ask user to try again |
+| `EdgeConsentRequiredError` | User hasn't granted consent | Open EdgeLink |
+| `EdgeInsufficientScopeError` | Missing required scopes | Request more scopes |
+| `EdgeNotFoundError` | Resource not found | Check ID |
+| `EdgeApiError` | Other API error | Check error.code |
+| `EdgeNetworkError` | Network failure | Retry request |
+
+## NestJS Example
+
+```typescript
+import { Injectable, Logger } from '@nestjs/common'
+import { ConfigService } from '@nestjs/config'
+import { EdgeConnectServer, EdgeConsentRequiredError } from '@edgeboost/edge-connect-server'
+
+@Injectable()
+export class EdgeService {
+  private readonly edge: EdgeConnectServer
+  private readonly logger = new Logger(EdgeService.name)
+
+  constructor(private config: ConfigService) {
+    this.edge = new EdgeConnectServer({
+      clientId: this.config.getOrThrow('EDGE_CLIENT_ID'),
+      clientSecret: this.config.getOrThrow('EDGE_CLIENT_SECRET'),
+      environment: this.config.get('EDGE_ENVIRONMENT', 'staging'),
+    })
+  }
+
+  async exchangeCode(code: string, codeVerifier: string) {
+    return this.edge.exchangeCode(code, codeVerifier)
+  }
+
+  async getBalance(accessToken: string) {
+    try {
+      return await this.edge.getBalance(accessToken)
+    } catch (error) {
+      if (error instanceof EdgeConsentRequiredError) {
+        this.logger.warn('User consent required')
+        throw error
+      }
+      this.logger.error('Failed to get balance', error)
+      throw error
+    }
+  }
+}
+```
+
+## Express Example
+
+```typescript
+import express from 'express'
+import { EdgeConnectServer, isEdgeError } from '@edgeboost/edge-connect-server'
+
+const edge = new EdgeConnectServer({
+  clientId: process.env.EDGE_CLIENT_ID!,
+  clientSecret: process.env.EDGE_CLIENT_SECRET!,
+  environment: 'staging',
+})
+
+const app = express()
+app.use(express.json())
+
+// Exchange code for tokens
+app.post('/api/edge/exchange', async (req, res) => {
+  try {
+    const { code, codeVerifier } = req.body
+    const tokens = await edge.exchangeCode(code, codeVerifier)
+    
+    // Store tokens for user...
+    
+    res.json({ success: true })
+  } catch (error) {
+    if (isEdgeError(error)) {
+      res.status(400).json({ error: error.code, message: error.message })
+    } else {
+      res.status(500).json({ error: 'internal_error' })
+    }
+  }
+})
+
+// Get balance
+app.get('/api/edge/balance', async (req, res) => {
+  try {
+    const accessToken = await getAccessTokenForUser(req.user.id)
+    const balance = await edge.getBalance(accessToken)
+    res.json(balance)
+  } catch (error) {
+    // Handle errors...
+  }
+})
+```
+
+## Related Packages
+
+- `@edgeboost/edge-connect-sdk` - Core types and utilities
+- `@edgeboost/edge-connect-link` - Browser SDK for popup authentication
+
+## License
+
+MIT
+
+

package/dist/index.d.mts

@@ -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 };