@edge-markets/connect-react-native 1.0.0

package/dist/index.d.ts

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