@edge-markets/connect-react-native 1.0.0

package/README.md

@@ -0,0 +1,307 @@
+# @edgeboost/edge-connect-react-native
+
+React Native SDK for EDGE Connect - Plaid-like authentication flow for mobile apps.
+
+## Features
+
+- 🔐 **Secure OAuth 2.0 with PKCE** - No client secrets in mobile app
+- 📱 **Native In-App Browser** - Uses SFSafariViewController (iOS) / Chrome Custom Tabs (Android)
+- 🔗 **Deep Link Support** - Seamless callback handling
+- ⚛️ **React Hooks** - Simple, declarative API
+- 📊 **Event Tracking** - Analytics and debugging support
+- 🎨 **Customizable** - Works with your app's flow
+
+## Installation
+
+```bash
+# npm
+npm install @edgeboost/edge-connect-react-native react-native-inappbrowser-reborn
+
+# yarn
+yarn add @edgeboost/edge-connect-react-native react-native-inappbrowser-reborn
+
+# pnpm
+pnpm add @edgeboost/edge-connect-react-native react-native-inappbrowser-reborn
+```
+
+### iOS Setup
+
+```bash
+cd ios && pod install
+```
+
+### For Expo Projects
+
+```bash
+npx expo install expo-web-browser
+```
+
+The SDK will automatically use `expo-web-browser` if available.
+
+## Quick Start
+
+### 1. Configure Deep Linking
+
+**iOS (Info.plist):**
+```xml
+<key>CFBundleURLTypes</key>
+<array>
+  <dict>
+    <key>CFBundleURLSchemes</key>
+    <array>
+      <string>myapp</string>
+    </array>
+  </dict>
+</array>
+```
+
+**Android (AndroidManifest.xml):**
+```xml
+<intent-filter>
+  <action android:name="android.intent.action.VIEW" />
+  <category android:name="android.intent.category.DEFAULT" />
+  <category android:name="android.intent.category.BROWSABLE" />
+  <data android:scheme="myapp" android:host="oauth" android:pathPrefix="/callback" />
+</intent-filter>
+```
+
+### 2. Use the Hook
+
+```tsx
+import { useEdgeLink } from '@edgeboost/edge-connect-react-native'
+import { Button, Alert } from 'react-native'
+
+function ConnectEdgeButton() {
+  const { open, isOpen, isSuccess, result, error, reset } = useEdgeLink({
+    clientId: 'your-client-id',
+    environment: 'staging',
+    redirectUri: 'myapp://oauth/callback',
+  })
+
+  // Handle success
+  React.useEffect(() => {
+    if (isSuccess && result) {
+      // Send code to your backend for token exchange
+      fetch('https://your-api.com/edge/exchange', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          code: result.code,
+          codeVerifier: result.codeVerifier,
+        }),
+      })
+        .then(res => res.json())
+        .then(data => {
+          Alert.alert('Success', 'EdgeBoost connected!')
+          reset() // Reset for next use
+        })
+        .catch(err => {
+          Alert.alert('Error', 'Failed to connect EdgeBoost')
+          reset()
+        })
+    }
+  }, [isSuccess, result])
+
+  // Handle errors
+  React.useEffect(() => {
+    if (error) {
+      Alert.alert('Error', error.message)
+      reset()
+    }
+  }, [error])
+
+  return (
+    <Button
+      title={isOpen ? 'Connecting...' : 'Connect EdgeBoost'}
+      onPress={open}
+      disabled={isOpen}
+    />
+  )
+}
+```
+
+## API Reference
+
+### `useEdgeLink(config)`
+
+React hook for EdgeLink integration.
+
+**Config:**
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `clientId` | `string` | ✅ | Your OAuth client ID |
+| `environment` | `'production' \| 'staging' \| 'sandbox'` | ✅ | Environment |
+| `redirectUri` | `string` | ✅ | Deep link URI for callback |
+| `scopes` | `EdgeScope[]` | ❌ | Requested permissions |
+| `linkUrl` | `string` | ❌ | Custom Link URL (dev only) |
+| `useExternalBrowser` | `boolean` | ❌ | Use external browser |
+
+**Returns:**
+| Property | Type | Description |
+|----------|------|-------------|
+| `open` | `() => Promise<void>` | Opens the Link flow |
+| `close` | `() => Promise<void>` | Closes the Link flow |
+| `isOpen` | `boolean` | Whether flow is open |
+| `isSuccess` | `boolean` | Whether flow succeeded |
+| `isError` | `boolean` | Whether there was an error |
+| `result` | `EdgeLinkSuccess \| null` | Success result with code |
+| `error` | `{ code, message } \| null` | Error info |
+| `reset` | `() => void` | Reset state for retry |
+
+### `EdgeLink` Class
+
+For more control, use the class directly:
+
+```typescript
+import { EdgeLink } from '@edgeboost/edge-connect-react-native'
+
+const link = new EdgeLink({
+  clientId: 'your-client-id',
+  environment: 'staging',
+  redirectUri: 'myapp://oauth/callback',
+  onSuccess: (result) => {
+    console.log('Auth code:', result.code)
+    console.log('Code verifier:', result.codeVerifier)
+  },
+  onExit: (metadata) => {
+    if (metadata.error) {
+      console.error('Error:', metadata.error.message)
+    } else {
+      console.log('User closed')
+    }
+  },
+  onEvent: (event) => {
+    analytics.track('edge_link_event', event)
+  },
+})
+
+// Open the flow
+await link.open()
+
+// Later, cleanup
+link.destroy()
+```
+
+## Deep Link Handling
+
+The SDK automatically sets up deep link listeners. If you have custom routing, you can handle links manually:
+
+```typescript
+import { useEdgeLinkHandler } from '@edgeboost/edge-connect-react-native'
+import { Linking } from 'react-native'
+
+function App() {
+  const { handleUrl } = useEdgeLinkHandler({
+    redirectUri: 'myapp://oauth/callback',
+    onSuccess: (result) => {
+      // Handle success
+    },
+    onError: (error) => {
+      // Handle error
+    },
+  })
+
+  useEffect(() => {
+    const subscription = Linking.addEventListener('url', ({ url }) => {
+      if (!handleUrl(url)) {
+        // Handle other deep links
+        handleOtherDeepLinks(url)
+      }
+    })
+
+    return () => subscription.remove()
+  }, [handleUrl])
+
+  return <YourApp />
+}
+```
+
+## Security Considerations
+
+### PKCE
+
+The SDK uses PKCE (Proof Key for Code Exchange) to secure the OAuth flow. This prevents authorization code interception attacks without requiring a client secret in the mobile app.
+
+### In-App Browser
+
+The SDK uses secure system browsers (SFSafariViewController / Chrome Custom Tabs) instead of WebViews. This is more secure because:
+
+- Cookies are isolated from your app
+- Users can verify they're on the real EdgeBoost domain
+- Prevents credential theft by malicious apps
+
+### Secure Random
+
+For production, install a cryptographic random number generator:
+
+```bash
+npm install react-native-get-random-values
+```
+
+Then import it at the top of your entry file:
+
+```javascript
+import 'react-native-get-random-values'
+```
+
+Without this, the SDK falls back to less secure random generation and will log a warning.
+
+## Backend Integration
+
+The `result.code` and `result.codeVerifier` must be sent to your backend for token exchange:
+
+```typescript
+// Your backend (using @edgeboost/edge-connect-server)
+import { EdgeConnectServer } from '@edgeboost/edge-connect-server'
+
+const server = new EdgeConnectServer({
+  clientId: 'your-client-id',
+  clientSecret: 'your-client-secret',
+  environment: 'staging',
+})
+
+// In your API endpoint
+app.post('/edge/exchange', async (req, res) => {
+  const { code, codeVerifier } = req.body
+
+  const tokens = await server.exchangeCode(code, codeVerifier)
+
+  // Store tokens securely
+  await saveTokensForUser(req.user.id, tokens)
+
+  res.json({ success: true })
+})
+```
+
+## Troubleshooting
+
+### Deep link not working
+
+1. Verify your URL scheme is registered in both iOS and Android configs
+2. Test with `npx uri-scheme open myapp://oauth/callback --ios` or `--android`
+3. Make sure the redirectUri matches exactly (including trailing slashes)
+
+### In-app browser not opening
+
+1. Install `react-native-inappbrowser-reborn` and run `pod install`
+2. Or for Expo, install `expo-web-browser`
+3. The SDK will fall back to external browser if neither is available
+
+### "Insecure random" warning
+
+Install and import `react-native-get-random-values` before any crypto operations.
+
+## Comparison with Browser SDK
+
+| Feature | Browser SDK | React Native SDK |
+|---------|-------------|------------------|
+| Auth UI | Popup window | In-app browser |
+| Callback | postMessage | Deep links |
+| Crypto | Web Crypto API | Polyfills/native |
+| API | `EdgeLink` class | `EdgeLink` + hooks |
+
+## License
+
+MIT
+
+

package/dist/index.d.mts

@@ -0,0 +1,355 @@
+import { EdgeEnvironment, EdgeLinkSuccess, EdgeLinkExit, EdgeScope } from '@edge-markets/connect';
+export { ALL_EDGE_SCOPES, Balance, EDGE_ENVIRONMENTS, EdgeApiError, EdgeAuthenticationError, EdgeConsentRequiredError, EdgeEnvironment, EdgeError, EdgeLinkExit, EdgeLinkSuccess, EdgeNetworkError, EdgePopupBlockedError, EdgeScope, EdgeStateMismatchError, EdgeTokenExchangeError, EdgeTokens, SCOPE_DESCRIPTIONS, Transfer, User, formatScopesForEnvironment, getEnvironmentConfig, isApiError, isAuthenticationError, isConsentRequiredError, isNetworkError } from '@edge-markets/connect';
+
+/**
+ * EdgeLink for React Native - Plaid-Style Authentication Flow
+ *
+ * Unlike the browser SDK which uses popups, the React Native SDK uses:
+ * - In-App Browser (SFSafariViewController / Chrome Custom Tabs)
+ * - Deep Links for OAuth callback
+ * - Secure storage for PKCE state
+ *
+ * This provides a native, secure authentication experience similar to Plaid Link.
+ *
+ * @module @edge-markets/connect-react-native
+ *
+ * @example
+ * ```typescript
+ * import { EdgeLink } from '@edge-markets/connect-react-native'
+ *
+ * const link = new EdgeLink({
+ *   clientId: 'your-client-id',
+ *   environment: 'staging',
+ *   redirectUri: 'myapp://oauth/callback',
+ *   onSuccess: async (result) => {
+ *     await sendToBackend(result.code, result.codeVerifier)
+ *   },
+ *   onExit: (metadata) => {
+ *     console.log('User exited:', metadata.reason)
+ *   },
+ * })
+ *
+ * // Open from a button press
+ * <Button onPress={() => link.open()} title="Connect EdgeBoost" />
+ * ```
+ */
+
+/**
+ * Configuration for EdgeLink React Native.
+ */
+interface EdgeLinkConfig {
+    /**
+     * Your OAuth client ID from the EdgeBoost partner portal.
+     */
+    clientId: string;
+    /**
+     * Environment to connect to.
+     */
+    environment: EdgeEnvironment;
+    /**
+     * Deep link URI for OAuth callback.
+     *
+     * This must be registered in your app's URL schemes (iOS) and
+     * intent filters (Android), and in your EdgeBoost OAuth client settings.
+     *
+     * @example
+     * - Custom scheme: `myapp://oauth/callback`
+     * - Universal link: `https://myapp.com/oauth/callback`
+     */
+    redirectUri: string;
+    /**
+     * Called when user successfully authenticates and grants consent.
+     */
+    onSuccess: (result: EdgeLinkSuccess) => void;
+    /**
+     * Called when user exits the flow.
+     */
+    onExit?: (metadata: EdgeLinkExit) => void;
+    /**
+     * Called for various events during the flow.
+     */
+    onEvent?: (event: EdgeLinkEvent) => void;
+    /**
+     * OAuth scopes to request.
+     * @default All available scopes
+     */
+    scopes?: EdgeScope[];
+    /**
+     * Custom URL for the Link page (development only).
+     */
+    linkUrl?: string;
+    /**
+     * Use external browser instead of in-app browser.
+     * @default false
+     */
+    useExternalBrowser?: boolean;
+}
+/**
+ * Event emitted during the Link flow.
+ */
+interface EdgeLinkEvent {
+    eventName: EdgeLinkEventName;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+type EdgeLinkEventName = 'OPEN' | 'CLOSE' | 'HANDOFF' | 'SUCCESS' | 'ERROR' | 'REDIRECT';
+/**
+ * EdgeLink for React Native - handles OAuth flow with in-app browser.
+ *
+ * @example
+ * ```typescript
+ * const link = new EdgeLink({
+ *   clientId: 'your-client-id',
+ *   environment: 'staging',
+ *   redirectUri: 'myapp://oauth/callback',
+ *   onSuccess: handleSuccess,
+ *   onExit: handleExit,
+ * })
+ *
+ * // Later, in response to user action
+ * await link.open()
+ * ```
+ */
+declare class EdgeLink {
+    private readonly config;
+    private pkce;
+    private state;
+    private linkListener;
+    private isOpen;
+    private isDestroyed;
+    constructor(config: EdgeLinkConfig);
+    /**
+     * Opens the EdgeLink authentication flow.
+     *
+     * This launches an in-app browser with the EdgeBoost login/consent page.
+     * When complete, the browser redirects to your redirectUri and the
+     * onSuccess/onExit callback is called.
+     */
+    open(): Promise<void>;
+    /**
+     * Manually handles a deep link URL.
+     *
+     * Use this if you're handling deep links yourself instead of relying
+     * on the automatic listener.
+     *
+     * @param url - The deep link URL received
+     * @returns true if the URL was handled, false otherwise
+     */
+    handleDeepLink(url: string): boolean;
+    /**
+     * Closes the EdgeLink flow.
+     */
+    close(): Promise<void>;
+    /**
+     * Destroys the EdgeLink instance.
+     */
+    destroy(): void;
+    private buildLinkUrl;
+    private setupLinkListener;
+    private removeLinkListener;
+    private processCallback;
+    private cleanup;
+    private emitEvent;
+}
+
+/**
+ * React Hooks for EdgeLink React Native
+ *
+ * These hooks provide a convenient, React-idiomatic way to integrate
+ * EdgeLink into your React Native application.
+ *
+ * @module @edge-markets/connect-react-native/hooks
+ */
+
+/**
+ * Configuration for useEdgeLink hook.
+ */
+interface UseEdgeLinkConfig {
+    /** Your OAuth client ID */
+    clientId: string;
+    /** Environment to connect to */
+    environment: EdgeEnvironment;
+    /** Deep link URI for OAuth callback */
+    redirectUri: string;
+    /** OAuth scopes to request */
+    scopes?: EdgeScope[];
+    /** Custom Link URL (development only) */
+    linkUrl?: string;
+    /** Use external browser instead of in-app browser */
+    useExternalBrowser?: boolean;
+}
+/**
+ * Return type for useEdgeLink hook.
+ */
+interface UseEdgeLinkReturn {
+    /** Opens the EdgeLink flow */
+    open: () => Promise<void>;
+    /** Closes the EdgeLink flow */
+    close: () => Promise<void>;
+    /** Whether the Link flow is currently open */
+    isOpen: boolean;
+    /** Whether the flow completed successfully */
+    isSuccess: boolean;
+    /** Whether there was an error */
+    isError: boolean;
+    /** The success result (code, codeVerifier, state) */
+    result: EdgeLinkSuccess | null;
+    /** Error information if the flow failed */
+    error: {
+        code: string;
+        message: string;
+    } | null;
+    /** Resets the state to allow another attempt */
+    reset: () => void;
+}
+/**
+ * React hook for EdgeLink integration.
+ *
+ * Provides a simple, declarative API for connecting EdgeBoost accounts.
+ *
+ * @example
+ * ```tsx
+ * function ConnectButton() {
+ *   const { open, isOpen, isSuccess, result, error } = useEdgeLink({
+ *     clientId: 'your-client-id',
+ *     environment: 'staging',
+ *     redirectUri: 'myapp://oauth/callback',
+ *   })
+ *
+ *   useEffect(() => {
+ *     if (isSuccess && result) {
+ *       // Send to your backend
+ *       exchangeCode(result.code, result.codeVerifier)
+ *     }
+ *   }, [isSuccess, result])
+ *
+ *   return (
+ *     <Button
+ *       onPress={open}
+ *       disabled={isOpen}
+ *       title={isOpen ? 'Connecting...' : 'Connect EdgeBoost'}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+declare function useEdgeLink(config: UseEdgeLinkConfig): UseEdgeLinkReturn;
+/**
+ * Hook to manually handle EdgeLink deep links.
+ *
+ * Use this if you have custom deep link routing and want to
+ * handle EdgeLink callbacks yourself.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   const { handleUrl, isHandled } = useEdgeLinkHandler({
+ *     redirectUri: 'myapp://oauth/callback',
+ *     onSuccess: (result) => {
+ *       console.log('Auth code:', result.code)
+ *     },
+ *     onExit: (error) => {
+ *       console.log('Auth failed:', error)
+ *     },
+ *   })
+ *
+ *   useEffect(() => {
+ *     const sub = Linking.addEventListener('url', ({ url }) => {
+ *       if (!handleUrl(url)) {
+ *         // Handle other deep links
+ *       }
+ *     })
+ *     return () => sub.remove()
+ *   }, [handleUrl])
+ *
+ *   return <YourApp />
+ * }
+ * ```
+ */
+interface UseEdgeLinkHandlerConfig {
+    /** Your redirect URI prefix */
+    redirectUri: string;
+    /** Called on successful auth */
+    onSuccess: (result: EdgeLinkSuccess) => void;
+    /** Called on error or user exit */
+    onError?: (error: {
+        code: string;
+        message: string;
+    }) => void;
+}
+interface UseEdgeLinkHandlerReturn {
+    /** Process a URL. Returns true if it was an EdgeLink callback. */
+    handleUrl: (url: string) => boolean;
+}
+declare function useEdgeLinkHandler(config: UseEdgeLinkHandlerConfig): UseEdgeLinkHandlerReturn;
+/**
+ * Hook to listen to EdgeLink events for analytics.
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   useEdgeLinkEvents((event) => {
+ *     analytics.track('edge_link_event', {
+ *       name: event.eventName,
+ *       timestamp: event.timestamp,
+ *       ...event.metadata,
+ *     })
+ *   })
+ *
+ *   // ...
+ * }
+ * ```
+ */
+declare function useEdgeLinkEvents(onEvent: (event: EdgeLinkEvent) => void, deps?: React.DependencyList): void;
+
+/**
+ * PKCE (Proof Key for Code Exchange) Utilities for React Native
+ *
+ * React Native doesn't have Web Crypto API natively, so we use a
+ * compatible implementation that works across platforms.
+ *
+ * For production apps, consider installing:
+ * - `react-native-get-random-values` (polyfill for crypto.getRandomValues)
+ * - `expo-crypto` (if using Expo)
+ *
+ * @module @edge-markets/connect-react-native/pkce
+ */
+/**
+ * A PKCE code verifier and challenge pair.
+ */
+interface PKCEPair {
+    /** High-entropy random string (43-128 characters). Keep secret until token exchange. */
+    verifier: string;
+    /** SHA-256 hash of verifier, base64url encoded. Include in authorization URL. */
+    challenge: string;
+}
+/**
+ * Generates a PKCE code verifier and challenge pair.
+ *
+ * @example
+ * ```typescript
+ * const pkce = await generatePKCE()
+ *
+ * // Include challenge in authorization URL
+ * const authUrl = `https://auth.example.com/authorize?code_challenge=${pkce.challenge}&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.
+ *
+ * @returns 64-character hex string (32 bytes of entropy)
+ */
+declare function generateState(): string;
+/**
+ * Checks if secure crypto is available.
+ *
+ * Returns false if only Math.random fallback is being used.
+ * Use this to warn users in development.
+ */
+declare function isSecureCryptoAvailable(): boolean;
+
+export { EdgeLink, type EdgeLinkConfig, type EdgeLinkEvent, type EdgeLinkEventName, type PKCEPair, type UseEdgeLinkConfig, type UseEdgeLinkHandlerConfig, type UseEdgeLinkHandlerReturn, type UseEdgeLinkReturn, generatePKCE, generateState, isSecureCryptoAvailable, useEdgeLink, useEdgeLinkEvents, useEdgeLinkHandler };