@edge-markets/connect-link 1.0.0

package/README.md

@@ -0,0 +1,271 @@
+# @edgeboost/edge-connect-link
+
+Browser SDK for EDGE Connect popup authentication - inspired by [Plaid Link](https://plaid.com/docs/link/).
+
+## Features
+
+- 🔒 **Secure by default** - PKCE OAuth flow, no client secret in browser
+- 🚀 **Simple API** - Just `new EdgeLink()` and `link.open()`
+- 📱 **Works everywhere** - Handles popup blockers gracefully
+- 📊 **Event tracking** - `onSuccess`, `onExit`, `onEvent` callbacks
+- 🎨 **Beautiful loading state** - Professional branded experience
+- 📝 **Full TypeScript** - Complete type definitions
+
+## Installation
+
+```bash
+npm install @edgeboost/edge-connect-link
+# or
+pnpm add @edgeboost/edge-connect-link
+# or
+yarn add @edgeboost/edge-connect-link
+```
+
+## Quick Start
+
+```typescript
+import { EdgeLink } from '@edgeboost/edge-connect-link'
+
+// 1. Create instance (do this once)
+const link = new EdgeLink({
+  clientId: 'your-client-id',
+  environment: 'staging',
+  onSuccess: (result) => {
+    // Send to your backend for token exchange
+    fetch('/api/edge/exchange', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        code: result.code,
+        codeVerifier: result.codeVerifier,
+      }),
+    })
+  },
+  onExit: (metadata) => {
+    if (metadata.reason === 'popup_blocked') {
+      alert('Please allow popups for this site')
+    }
+  },
+})
+
+// 2. Open from a click handler
+document.getElementById('connect-btn')!.onclick = () => link.open()
+```
+
+## ⚠️ Important: User Gesture Requirement
+
+**`link.open()` MUST be called directly from a user click handler!**
+
+Browsers block popups that aren't triggered by user interaction. Any async work before calling `open()` will break this.
+
+```typescript
+// ✅ Correct - direct click handler
+button.onclick = () => link.open()
+
+// ✅ Correct - immediate call in handler
+button.onclick = () => {
+  trackClick() // sync ok
+  link.open()
+}
+
+// ❌ Wrong - async gap breaks user gesture
+button.onclick = async () => {
+  await someAsyncWork() // breaks it!
+  link.open() // BLOCKED
+}
+
+// ❌ Wrong - setTimeout breaks user gesture
+button.onclick = () => {
+  setTimeout(() => link.open(), 100) // BLOCKED
+}
+```
+
+## Configuration
+
+```typescript
+interface EdgeLinkConfig {
+  // Required
+  clientId: string              // Your OAuth client ID
+  environment: EdgeEnvironment  // 'production' | 'staging' | 'sandbox'
+  onSuccess: (result) => void   // Called on successful auth
+
+  // Optional
+  onExit?: (metadata) => void   // Called when user exits
+  onEvent?: (event) => void     // Called for analytics events
+  scopes?: EdgeScope[]          // Scopes to request (default: all)
+  linkUrl?: string              // Custom Link URL (dev only)
+  redirectUri?: string          // Custom redirect URI
+}
+```
+
+## Callbacks
+
+### onSuccess
+
+Called when user successfully authenticates and grants consent:
+
+```typescript
+onSuccess: (result) => {
+  // result.code - Authorization code (send to backend)
+  // result.codeVerifier - PKCE verifier (send to backend)
+  // result.state - State parameter (for validation)
+
+  // IMPORTANT: Exchange tokens on your backend, not here!
+  // The backend has your client secret, the browser doesn't.
+}
+```
+
+### onExit
+
+Called when user exits the flow:
+
+```typescript
+onExit: (metadata) => {
+  switch (metadata.reason) {
+    case 'user_closed':
+      // User closed the popup
+      break
+    case 'popup_blocked':
+      // Popup was blocked - show instructions
+      alert('Please allow popups')
+      break
+    case 'error':
+      // An error occurred
+      console.error(metadata.error?.message)
+      break
+  }
+}
+```
+
+### onEvent
+
+Called for analytics and debugging:
+
+```typescript
+onEvent: (event) => {
+  // event.eventName - 'OPEN' | 'CLOSE' | 'HANDOFF' | 'SUCCESS' | 'ERROR'
+  // event.timestamp - Unix timestamp
+  // event.metadata - Additional context
+
+  analytics.track('edge_link_event', event)
+}
+```
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `open(options?)` | Opens the Link popup (must be from click handler) |
+| `close()` | Closes the popup programmatically |
+| `destroy()` | Cleans up resources (call when done) |
+| `isOpen()` | Returns true if popup is open |
+
+## Scopes
+
+Request only the permissions you need:
+
+```typescript
+import { EdgeLink, EDGE_SCOPES } from '@edgeboost/edge-connect-link'
+
+const link = new EdgeLink({
+  clientId: 'your-client-id',
+  environment: 'staging',
+  scopes: [
+    EDGE_SCOPES.USER_READ,    // Read profile
+    EDGE_SCOPES.BALANCE_READ, // Read balance
+    // EDGE_SCOPES.TRANSFER_WRITE - Only if you need transfers
+  ],
+  onSuccess: handleSuccess,
+})
+```
+
+## React Example
+
+```tsx
+import { useEffect, useRef, useCallback } from 'react'
+import { EdgeLink } from '@edgeboost/edge-connect-link'
+
+function ConnectButton() {
+  const linkRef = useRef<EdgeLink | null>(null)
+
+  useEffect(() => {
+    linkRef.current = new EdgeLink({
+      clientId: process.env.NEXT_PUBLIC_EDGE_CLIENT_ID!,
+      environment: 'staging',
+      onSuccess: async (result) => {
+        await fetch('/api/edge/exchange', {
+          method: 'POST',
+          body: JSON.stringify(result),
+        })
+        // Refresh user state
+      },
+      onExit: (metadata) => {
+        if (metadata.reason === 'popup_blocked') {
+          alert('Please allow popups')
+        }
+      },
+    })
+
+    return () => linkRef.current?.destroy()
+  }, [])
+
+  const handleClick = useCallback(() => {
+    linkRef.current?.open()
+  }, [])
+
+  return (
+    <button onClick={handleClick}>
+      Connect EdgeBoost
+    </button>
+  )
+}
+```
+
+## How It Works
+
+1. **User clicks button** → `link.open()` is called
+2. **Popup opens immediately** → Shows branded loading state
+3. **PKCE generated** → Secure OAuth without client secret
+4. **Popup navigates to Link page** → User logs in & grants consent
+5. **Code returned via postMessage** → Secure cross-origin communication
+6. **onSuccess called** → You send code to backend for token exchange
+
+```
+┌─────────────┐     ┌─────────────────┐     ┌──────────────┐
+│   Your App  │     │  EdgeLink Popup │     │ Your Backend │
+└──────┬──────┘     └────────┬────────┘     └──────┬───────┘
+       │                     │                     │
+       │ link.open()         │                     │
+       ├────────────────────►│                     │
+       │                     │                     │
+       │           (user logs in, grants consent)  │
+       │                     │                     │
+       │   postMessage(code) │                     │
+       │◄────────────────────┤                     │
+       │                     │                     │
+       │ onSuccess(result)   │                     │
+       ├─────────────────────┼────────────────────►│
+       │                     │   POST /api/exchange │
+       │                     │                     │
+       │                     │   tokens             │
+       │◄────────────────────┼─────────────────────┤
+       │                     │                     │
+```
+
+## Security
+
+- **PKCE** - Prevents authorization code interception
+- **State parameter** - Prevents CSRF attacks
+- **Origin validation** - postMessage only accepted from expected origin
+- **No client secret in browser** - Token exchange happens on your backend
+
+## Related Packages
+
+- `@edgeboost/edge-connect-sdk` - Core types and utilities
+- `@edgeboost/edge-connect-server` - Server SDK for token exchange
+
+## License
+
+MIT
+
+

package/dist/index.d.mts

@@ -0,0 +1,409 @@
+import { EdgeEnvironment, EdgeLinkSuccess, EdgeLinkExit, EdgeScope } from '@edge-markets/connect';
+export { ALL_EDGE_SCOPES, EDGE_SCOPES, EdgeEnvironment, EdgeError, EdgeLinkExit, EdgeLinkSuccess, EdgePopupBlockedError, EdgeScope, EdgeStateMismatchError, isEdgeError } from '@edge-markets/connect';
+
+/**
+ * EdgeLink - Plaid-Style Popup Authentication for EDGE Connect
+ *
+ * EdgeLink provides a simple, reliable way to authenticate users with EdgeBoost
+ * using a popup window - similar to how Plaid Link works.
+ *
+ * **Key Features:**
+ * - Callback-based API (onSuccess, onExit, onEvent)
+ * - Handles popup blockers gracefully
+ * - PKCE for secure OAuth (no client secret in browser)
+ * - Cross-origin communication via postMessage
+ * - CSRF protection via state parameter
+ *
+ * @module @edge-markets/connect-link
+ *
+ * @example
+ * ```typescript
+ * import { EdgeLink } from '@edge-markets/connect-link'
+ *
+ * const link = new EdgeLink({
+ *   clientId: 'your-client-id',
+ *   environment: 'staging',
+ *   onSuccess: (result) => {
+ *     // Send to your backend for token exchange
+ *     fetch('/api/edge/exchange', {
+ *       method: 'POST',
+ *       body: JSON.stringify({
+ *         code: result.code,
+ *         codeVerifier: result.codeVerifier,
+ *       }),
+ *     })
+ *   },
+ *   onExit: (metadata) => {
+ *     if (metadata.reason === 'popup_blocked') {
+ *       alert('Please allow popups for this site')
+ *     }
+ *   },
+ * })
+ *
+ * // In a click handler
+ * document.getElementById('connect-btn')!.onclick = () => link.open()
+ * ```
+ */
+
+/**
+ * Configuration options for EdgeLink.
+ *
+ * Only `clientId`, `environment`, and `onSuccess` are required.
+ * Everything else has sensible defaults.
+ */
+interface EdgeLinkConfig {
+    /**
+     * Your OAuth client ID from the EdgeBoost partner portal.
+     * This is public and safe to include in frontend code.
+     */
+    clientId: string;
+    /**
+     * Environment to connect to.
+     * - `'production'` - Live environment with real money
+     * - `'staging'` - Test environment for development
+     * - `'sandbox'` - Isolated mock environment (coming soon)
+     */
+    environment: EdgeEnvironment;
+    /**
+     * Called when user successfully authenticates and grants consent.
+     *
+     * Send the `code` and `codeVerifier` to your backend for token exchange.
+     * **Never exchange tokens in the frontend** - that would expose your client secret.
+     *
+     * @example
+     * ```typescript
+     * onSuccess: async (result) => {
+     *   const response = await fetch('/api/edge/exchange', {
+     *     method: 'POST',
+     *     headers: { 'Content-Type': 'application/json' },
+     *     body: JSON.stringify({
+     *       code: result.code,
+     *       codeVerifier: result.codeVerifier,
+     *     }),
+     *   })
+     *   if (response.ok) {
+     *     showSuccess('EdgeBoost connected!')
+     *   }
+     * }
+     * ```
+     */
+    onSuccess: (result: EdgeLinkSuccess) => void;
+    /**
+     * Called when user exits the Link flow (closes popup, error, etc.).
+     *
+     * Use this to handle errors and provide user feedback.
+     *
+     * @example
+     * ```typescript
+     * onExit: (metadata) => {
+     *   switch (metadata.reason) {
+     *     case 'user_closed':
+     *       // User closed popup - maybe show "Connect later" option
+     *       break
+     *     case 'popup_blocked':
+     *       showMessage('Please allow popups and try again')
+     *       break
+     *     case 'error':
+     *       showError(metadata.error?.message || 'Something went wrong')
+     *       break
+     *   }
+     * }
+     * ```
+     */
+    onExit?: (metadata: EdgeLinkExit) => void;
+    /**
+     * Called for various events during the Link flow.
+     * Useful for analytics and debugging.
+     *
+     * @example
+     * ```typescript
+     * onEvent: (event) => {
+     *   analytics.track('edge_link_event', {
+     *     eventName: event.eventName,
+     *     timestamp: event.timestamp,
+     *   })
+     * }
+     * ```
+     */
+    onEvent?: (event: EdgeLinkEvent) => void;
+    /**
+     * OAuth scopes to request.
+     * @default All available scopes
+     *
+     * @example
+     * ```typescript
+     * // Request only what you need
+     * scopes: ['user.read', 'balance.read']
+     * ```
+     */
+    scopes?: EdgeScope[];
+    /**
+     * Custom URL for the Link page.
+     * Only use for local development.
+     *
+     * @default Derived from environment config
+     */
+    linkUrl?: string;
+    /**
+     * Custom redirect URI after authentication.
+     * Must be registered in your OAuth client settings.
+     *
+     * @default `${window.location.origin}/oauth/edge/callback`
+     */
+    redirectUri?: string;
+}
+/**
+ * Event emitted during the Link flow.
+ */
+interface EdgeLinkEvent {
+    /** Name of the event */
+    eventName: EdgeLinkEventName;
+    /** Unix timestamp when event occurred */
+    timestamp: number;
+    /** Additional event-specific data */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Possible Link events.
+ */
+type EdgeLinkEventName = 'OPEN' | 'CLOSE' | 'HANDOFF' | 'TRANSITION' | 'ERROR' | 'SUCCESS';
+/**
+ * Options for opening Link.
+ */
+interface EdgeLinkOpenOptions {
+    /**
+     * Override scopes for this open call.
+     */
+    scopes?: EdgeScope[];
+}
+/**
+ * EdgeLink - Simple popup-based authentication for EDGE Connect.
+ *
+ * Create one instance and reuse it. Call `open()` from a click handler.
+ *
+ * @example
+ * ```typescript
+ * // Create instance once
+ * const link = new EdgeLink({
+ *   clientId: 'your-client-id',
+ *   environment: 'staging',
+ *   onSuccess: handleSuccess,
+ *   onExit: handleExit,
+ * })
+ *
+ * // Open from click handler (required for popup to work)
+ * connectButton.onclick = () => link.open()
+ *
+ * // Clean up when done
+ * link.destroy()
+ * ```
+ */
+declare class EdgeLink {
+    private readonly config;
+    private readonly popup;
+    private readonly expectedOrigin;
+    private pkce;
+    private state;
+    private messageHandler;
+    private isDestroyed;
+    /**
+     * Creates a new EdgeLink instance.
+     *
+     * @param config - Configuration options
+     * @throws Error if required config is missing or crypto is unavailable
+     */
+    constructor(config: EdgeLinkConfig);
+    /**
+     * Opens the EdgeLink popup.
+     *
+     * **MUST be called directly from a user click handler!**
+     * Calling from setTimeout, Promise.then, or other async contexts will fail.
+     *
+     * @param options - Optional overrides for this open call
+     * @throws EdgePopupBlockedError if popup is blocked
+     *
+     * @example
+     * ```typescript
+     * // ✅ Correct - direct click handler
+     * button.onclick = () => link.open()
+     *
+     * // ❌ Wrong - async gap
+     * button.onclick = async () => {
+     *   await someAsyncWork()
+     *   link.open() // Will be blocked!
+     * }
+     * ```
+     */
+    open(options?: EdgeLinkOpenOptions): void;
+    /**
+     * Closes the EdgeLink popup if open.
+     *
+     * Call this to programmatically close the popup without triggering onExit.
+     */
+    close(): void;
+    /**
+     * Destroys the EdgeLink instance.
+     *
+     * Call this when unmounting your component or when done with EdgeLink.
+     * After destroy(), the instance cannot be reused.
+     *
+     * @example
+     * ```typescript
+     * // React cleanup
+     * useEffect(() => {
+     *   const link = new EdgeLink({ ... })
+     *   return () => link.destroy()
+     * }, [])
+     * ```
+     */
+    destroy(): void;
+    /**
+     * Checks if the popup is currently open.
+     */
+    isOpen(): boolean;
+    /**
+     * Initializes PKCE and navigates popup to auth URL.
+     */
+    private initializeAuth;
+    /**
+     * Builds the URL for the EdgeLink page.
+     *
+     * The Link page handles:
+     * - User authentication (if not logged in)
+     * - Consent UI (showing requested permissions)
+     * - OAuth redirect to Cognito
+     * - Returning code via postMessage
+     */
+    private buildLinkUrl;
+    /**
+     * Sets up the postMessage listener.
+     */
+    private setupMessageListener;
+    /**
+     * Removes the postMessage listener.
+     */
+    private removeMessageListener;
+    /**
+     * Handles successful authentication from popup.
+     */
+    private handleSuccess;
+    /**
+     * Handles exit from popup.
+     */
+    private handleExit;
+    /**
+     * Handles user closing the popup manually.
+     */
+    private handleUserClose;
+    /**
+     * Emits an event.
+     */
+    private emitEvent;
+    /**
+     * Cleans up stored state.
+     */
+    private cleanup;
+}
+
+/**
+ * PKCE (Proof Key for Code Exchange) Utilities
+ *
+ * PKCE is a security extension to OAuth 2.0 that prevents authorization code
+ * interception attacks. It's essential for public clients like browser apps
+ * where you can't securely store a client secret.
+ *
+ * How it works:
+ * 1. Generate a random `code_verifier` (high entropy secret)
+ * 2. Create `code_challenge` = base64url(sha256(code_verifier))
+ * 3. Send `code_challenge` in the authorization request
+ * 4. Send `code_verifier` in the token exchange
+ * 5. Server verifies: sha256(code_verifier) === code_challenge
+ *
+ * This ensures only the client that started the flow can complete it.
+ *
+ * @module @edge-markets/connect-link/pkce
+ */
+/**
+ * A PKCE code verifier and challenge pair.
+ *
+ * Keep the `verifier` secret until token exchange.
+ * Send the `challenge` in the authorization URL.
+ */
+interface PKCEPair {
+    /**
+     * High-entropy random string (43-128 characters).
+     * Keep this secret - only send during token exchange.
+     */
+    verifier: string;
+    /**
+     * SHA-256 hash of verifier, base64url encoded.
+     * This is public - include in authorization URL.
+     */
+    challenge: string;
+}
+/**
+ * Generates a PKCE code verifier and challenge pair.
+ *
+ * The verifier is a 128-character hex string (64 bytes of entropy).
+ * This exceeds the OAuth 2.0 PKCE spec minimum of 43 characters.
+ *
+ * @returns Promise resolving to verifier and challenge
+ *
+ * @example
+ * ```typescript
+ * const pkce = await generatePKCE()
+ *
+ * // Include challenge in authorization URL
+ * const authUrl = new URL('https://auth.example.com/authorize')
+ * authUrl.searchParams.set('code_challenge', pkce.challenge)
+ * authUrl.searchParams.set('code_challenge_method', 'S256')
+ *
+ * // Later, include verifier in token exchange
+ * const tokens = await exchangeCode(code, pkce.verifier)
+ * ```
+ */
+declare function generatePKCE(): Promise<PKCEPair>;
+/**
+ * Generates a random state parameter for CSRF protection.
+ *
+ * The state parameter prevents cross-site request forgery attacks by ensuring
+ * the authorization response came from a request we initiated.
+ *
+ * @returns 64-character hex string (32 bytes of entropy)
+ *
+ * @example
+ * ```typescript
+ * const state = generateState()
+ *
+ * // Store state before redirect
+ * sessionStorage.setItem('oauth_state', state)
+ *
+ * // Include in authorization URL
+ * authUrl.searchParams.set('state', state)
+ *
+ * // After redirect, verify state matches
+ * if (responseState !== sessionStorage.getItem('oauth_state')) {
+ *   throw new Error('State mismatch - possible CSRF attack')
+ * }
+ * ```
+ */
+declare function generateState(): string;
+/**
+ * Validates that the Web Crypto API is available.
+ *
+ * Call this early to fail fast if running in an unsupported environment.
+ *
+ * @throws Error if Web Crypto API is not available
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   assertCryptoAvailable()
+ * } catch {
+ *   showMessage('Please use a modern browser with HTTPS')
+ * }
+ * ```
+ */
+declare function assertCryptoAvailable(): void;
+
+export { EdgeLink, type EdgeLinkConfig, type EdgeLinkEvent, type EdgeLinkEventName, type EdgeLinkOpenOptions, type PKCEPair, assertCryptoAvailable, generatePKCE, generateState };