@openfort/react-native 0.1.21 → 0.1.23

package/dist/core/provider.js

@@ -39,13 +39,22 @@ function startEmbeddedStatePolling(client, onChange, intervalMs = 1000) {
     };
 }
 /**
- * Provider component that initialises the Openfort SDK and exposes its state via {@link OpenfortContext}
+ * Root provider component that initializes the Openfort SDK and makes it available throughout your app.
  *
- * This component must wrap your React Native app to provide Openfort functionality to all child components.
- * It initializes the SDK with the provided configuration and manages authentication state.
+ * This component must wrap your React Native application to enable Openfort functionality.
+ * It initializes the SDK, manages authentication state, handles embedded wallet connections,
+ * and provides context to all child components through {@link OpenfortContext}.
  *
- * @param props - Provider configuration including the publishable key and optional overrides
- * @returns A React element that provides the Openfort context to its children
+ * **Key Features:**
+ * - Initializes Openfort client with platform-specific configuration
+ * - Manages user authentication state and session persistence
+ * - Polls embedded wallet state for real-time status updates
+ * - Provides hidden WebView for embedded wallet communication
+ * - Supports multiple blockchain networks via supportedChains
+ * - Integrates Shield for secure embedded wallet management
+ *
+ * @param props - Provider configuration, see {@link OpenfortProviderProps}
+ * @returns React element that provides Openfort context to all children
  *
  * @example
  * ```tsx
@@ -59,7 +68,12 @@ function startEmbeddedStatePolling(client, onChange, intervalMs = 1000) {
  *       supportedChains={[polygon, polygonMumbai]}
  *       walletConfig={{
  *         shieldPublishableKey: "shield_pk_...",
- *         getEncryptionSession: () => fetchEncryptionSession(),
+ *         getEncryptionSession: async () => {
+ *           // Fetch session from your backend
+ *           const response = await fetch('/api/encryption-session');
+ *           return response.text();
+ *         },
+ *         recoveryMethod: 'automatic',
  *       }}
  *       verbose={true}
  *     >

package/dist/hooks/auth/useEmailAuth.js

@@ -15,12 +15,23 @@ const mapStatus = (status) => {
 /**
  * Hook for email and password authentication.
  *
- * This hook provides email/password authentication flows including sign-in, sign-up, and
- * account linking. Password reset and verification helpers are exposed but currently stubbed
- * (TODOs) until the SDK wiring is complete.
+ * This hook provides comprehensive email/password authentication flows including sign-in,
+ * sign-up, account linking, password reset, and email verification functionality.
  *
- * @param hookOptions - Optional configuration with callback functions and email verification settings.
- * @returns Email authentication state and methods with flow status indicators.
+ * @param hookOptions - Optional configuration with callback functions and email verification settings
+ * @returns Email authentication state and methods with flow status indicators including:
+ *   - `signInEmail` - Sign in with email and password
+ *   - `signUpEmail` - Create new account with email and password
+ *   - `linkEmail` - Link email/password to existing authenticated account
+ *   - `requestResetPassword` - Request password reset email
+ *   - `resetPassword` - Complete password reset with token from email
+ *   - `verifyEmail` - Verify email address with verification code
+ *   - `reset` - Reset flow state to initial
+ *   - `isLoading` - Whether an operation is in progress
+ *   - `isError` - Whether the last operation failed
+ *   - `isSuccess` - Whether the last operation succeeded
+ *   - `requiresEmailVerification` - Whether email verification is pending
+ *   - `error` - Error from the last failed operation
  *
  * @example
  * ```tsx
@@ -29,12 +40,14 @@ const mapStatus = (status) => {
  *   onError: ({ error }) => console.error('Email auth failed:', error?.message),
  * });
  *
+ * // Sign up a new user
  * await signUpEmail({ email: 'user@example.com', password: 'securePassword123' });
  *
  * if (requiresEmailVerification) {
  *   console.log('Check email for verification code');
  * }
  *
+ * // Sign in existing user
  * await signInEmail({ email: 'user@example.com', password: 'securePassword123' });
  * ```
  */

package/dist/hooks/auth/useGuestAuth.js

@@ -4,24 +4,34 @@ import { onError, onSuccess } from '../../lib/hookConsistency';
 import { mapStatus } from '../../types/baseFlowState';
 import { OpenfortError, OpenfortErrorType } from '../../types/openfortError';
 /**
- * Hook for creating guest accounts.
+ * Hook for guest account authentication.
  *
- * Guest accounts allow users to access certain features without full authentication and can later be upgraded to full accounts
- * by linking additional authentication methods.
+ * This hook provides functionality for creating anonymous guest accounts that allow
+ * users to access features without full authentication. Guest accounts can later be
+ * upgraded to permanent accounts by linking email, OAuth, or wallet authentication.
  *
- * @param hookOptions - Configuration options including success and error callbacks.
- * @returns Current guest authentication helpers with flow status indicators.
+ * @param hookOptions - Configuration options including success and error callbacks
+ * @returns Guest authentication method and flow state including:
+ *   - `signUpGuest` - Create anonymous guest account
+ *   - `isLoading` - Whether guest account creation is in progress
+ *   - `isError` - Whether guest account creation failed
+ *   - `isSuccess` - Whether guest account was created successfully
+ *   - `error` - Error from the last failed operation
  *
  * @example
  * ```tsx
  * const { signUpGuest, isLoading } = useGuestAuth({
- *   onSuccess: ({ user }) => console.log('Guest account created:', user),
+ *   onSuccess: ({ user }) => console.log('Guest account created:', user?.id),
  *   onError: ({ error }) => console.error('Failed to create guest account:', error),
  * });
  *
+ * // Create guest account for anonymous access
  * if (!isLoading) {
  *   await signUpGuest();
  * }
+ *
+ * // Later, upgrade to permanent account by linking authentication
+ * // Use linkEmail, linkOauth, or linkSiwe from other hooks
  * ```
  */
 export const useGuestAuth = (hookOptions = {}) => {

package/dist/hooks/auth/useOAuth.js

@@ -8,15 +8,24 @@ import { OpenfortError, OpenfortErrorType } from '../../types/openfortError';
 /**
  * Hook for OAuth-based authentication with supported providers.
  *
- * This hook provides helpers for starting OAuth login flows (`initOAuth`) and linking
- * additional providers to an authenticated user (`linkOauth`). Some advanced flows may
- * require manual credential storage via `storeCredentials`, which is currently a TODO.
+ * This hook provides OAuth authentication flows including login and account linking
+ * for various OAuth providers (Google, Apple, Discord, Twitter, Facebook, etc.).
+ * Supports both web-based OAuth flows and native Apple Sign-In on iOS.
  *
- * @param hookOptions - Configuration options including success and error callbacks.
- * @returns OAuth helpers and derived flow state flags.
+ * @param hookOptions - Configuration options including success and error callbacks
+ * @returns OAuth authentication methods and flow state including:
+ *   - `initOAuth` - Start OAuth login flow for authentication
+ *   - `linkOauth` - Link additional OAuth provider to authenticated account
+ *   - `storeCredentials` - (Reserved for future use)
+ *   - `isLoading` - Whether OAuth flow is in progress
+ *   - `isError` - Whether the last OAuth flow failed
+ *   - `isSuccess` - Whether the last OAuth flow succeeded
+ *   - `error` - Error from the last failed OAuth operation
  *
  * @example
  * ```tsx
+ * import { OAuthProvider } from '@openfort/openfort-js';
+ *
  * const { initOAuth, linkOauth, isLoading, isError, error } = useOAuth({
  *   onSuccess: ({ user }) => console.log('OAuth completed for', user?.id),
  * });

package/dist/hooks/auth/useWalletAuth.js

@@ -16,28 +16,47 @@ const mapStatus = (status) => {
     };
 };
 /**
- * Hook for handling Sign-In With Ethereum (SIWE) flows.
+ * Hook for Sign-In With Ethereum (SIWE) authentication flows.
  *
- * This hook orchestrates SIWE message generation, signature submission, and state
- * tracking so that external wallets can either authenticate a user (`signInWithSiwe`)
- * or be linked to an existing account (`linkSiwe`).
+ * This hook provides SIWE authentication functionality allowing users to authenticate
+ * or link accounts using their external Ethereum wallets. It handles message generation,
+ * signature verification, and state management throughout the authentication flow.
  *
- * @param hookOptions - Optional callbacks for handling success or error events from the SIWE flows.
- * @returns SIWE helpers for generating messages, signing in, linking wallets, and inspecting flow status.
+ * @param hookOptions - Optional callbacks for handling success or error events from SIWE flows
+ * @returns SIWE authentication methods and flow state including:
+ *   - `generateSiweMessage` - Generate SIWE message for wallet to sign
+ *   - `signInWithSiwe` - Authenticate user with signed SIWE message
+ *   - `linkSiwe` - Link external wallet to existing authenticated account
+ *   - `isLoading` - Whether a SIWE operation is in progress
+ *   - `isError` - Whether the last SIWE operation failed
+ *   - `isSuccess` - Whether the last SIWE operation succeeded
+ *   - `isAwaitingSignature` - Whether waiting for user to sign message
+ *   - `isGeneratingMessage` - Whether generating SIWE message
+ *   - `isSubmittingSignature` - Whether submitting signature to server
+ *   - `error` - Error from the last failed operation
  *
  * @example
  * ```tsx
- * const { generateSiweMessage, signInWithSiwe, linkSiwe, isAwaitingSignature } = useWalletAuth({
- *   onSuccess: ({ user }) => console.log('SIWE flow completed for', user?.id),
+ * // Using with an external wallet like WalletConnect or MetaMask
+ * const { generateSiweMessage, signInWithSiwe, isAwaitingSignature } = useWalletAuth({
+ *   onSuccess: ({ user }) => console.log('SIWE authentication successful:', user?.id),
  * });
  *
+ * // Step 1: Generate SIWE message
  * const { message } = await generateSiweMessage({
  *   wallet: connectedWallet.address,
- *   from: { domain: 'app.openfort.io', uri: 'https://app.openfort.io' },
+ *   from: { domain: 'myapp.com', uri: 'https://myapp.com' },
  * });
  *
+ * // Step 2: Request signature from user's wallet
  * const signature = await connectedWallet.signMessage(message);
- * await signInWithSiwe({ walletAddress: connectedWallet.address, signature, messageOverride: message });
+ *
+ * // Step 3: Authenticate with signed message
+ * await signInWithSiwe({
+ *   walletAddress: connectedWallet.address,
+ *   signature,
+ *   messageOverride: message
+ * });
  * ```
  */
 export function useWalletAuth(hookOptions) {

package/dist/hooks/wallet/solanaProvider.js

@@ -38,16 +38,13 @@ export class OpenfortSolanaProvider {
     async request(args) {
         switch (args.method) {
             case 'signMessage': {
-                // Convert message string to Uint8Array
                 const signature = await this._signMessage(args.params.message);
-                return { signature: signature };
+                return { signature };
             }
             case 'signTransaction': {
                 const signedTransaction = await this._signTransaction(args.params.transaction);
                 return { signedTransaction };
             }
-            default:
-                throw new Error(`Unsupported method: ${args.method}`);
         }
     }
     /**

package/dist/hooks/wallet/useEmbeddedEthereumWallet.js

@@ -8,39 +8,90 @@ import { buildRecoveryParams } from './utils';
 /**
  * Hook for managing embedded Ethereum wallets.
  *
- * This hook provides comprehensive Ethereum wallet management including creation, activation,
- * and recovery. It returns a discriminated union state that enables type-safe wallet interactions.
+ * This hook provides comprehensive management of embedded Ethereum wallets including creation,
+ * recovery, activation, and EIP-1193 provider access. Returns a discriminated union state that
+ * enables type-safe wallet interactions based on connection status.
  *
- * @param options - Configuration with default chainId and callback functions
- * @returns Discriminated union state object. The `status` field determines available properties.
- * Possible states: 'disconnected', 'connecting', 'reconnecting', 'creating', 'needs-recovery',
- * 'connected', 'error'. When connected, includes `provider` and `activeWallet`. All states include
- * `create`, `setActive`, `setRecovery`, `exportPrivateKey`, and `wallets` methods/properties.
+ * **Wallet Types Supported:**
+ * - Smart Contract Accounts (Account Abstraction)
+ * - EOA (Externally Owned Accounts)
+ *
+ * **Recovery Methods:**
+ * - Automatic recovery (via encryption session)
+ * - Password-based recovery
+ *
+ * @param options - Configuration options including:
+ *   - `chainId` - Default chain ID for wallet operations
+ *   - `onCreateSuccess` - Callback when wallet is created
+ *   - `onCreateError` - Callback when wallet creation fails
+ *   - `onSetActiveSuccess` - Callback when wallet is activated/recovered
+ *   - `onSetActiveError` - Callback when wallet activation fails
+ *   - `onSetRecoverySuccess` - Callback when recovery method is updated
+ *   - `onSetRecoveryError` - Callback when recovery update fails
+ *
+ * @returns Discriminated union state based on `status` field:
+ *   - **'disconnected'**: No active wallet. Properties: `create`, `setActive`, `wallets`, `setRecovery`, `exportPrivateKey`
+ *   - **'connecting'**: Activating wallet. Properties: same as disconnected + `activeWallet`
+ *   - **'reconnecting'**: Reconnecting to wallet. Properties: same as connecting
+ *   - **'creating'**: Creating new wallet. Properties: same as disconnected
+ *   - **'needs-recovery'**: Recovery required. Properties: same as connecting
+ *   - **'connected'**: Wallet ready. Properties: all + `provider` (EIP-1193 provider)
+ *   - **'error'**: Operation failed. Properties: all + `error` message
  *
  * @example
  * ```tsx
- * import { useEmbeddedEthereumWallet, isConnected, isLoading } from '@openfort/react-native';
+ * import { useEmbeddedEthereumWallet } from '@openfort/react-native';
+ * import { ActivityIndicator } from 'react-native';
  *
- * const ethereum = useEmbeddedEthereumWallet({
- *   chainId: 1,
- *   onCreateSuccess: (account, provider) => console.log('Wallet created:', account.address),
- * });
+ * function WalletComponent() {
+ *   const ethereum = useEmbeddedEthereumWallet({
+ *     chainId: 137, // Polygon
+ *     onCreateSuccess: (account, provider) => {
+ *       console.log('Wallet created:', account.address);
+ *     },
+ *   });
  *
- * if (isLoading(ethereum)) {
- *   return <ActivityIndicator />;
- * }
+ *   // Handle loading states
+ *   if (ethereum.status === 'creating' || ethereum.status === 'connecting') {
+ *     return <ActivityIndicator />;
+ *   }
  *
- * if (isConnected(ethereum)) {
- *   // TypeScript knows provider and activeWallet are available
- *   const tx = await ethereum.provider.request({
- *     method: 'eth_sendTransaction',
- *     params: [{ from: ethereum.activeWallet.address, to: '0x...', value: '0x0' }]
- *   });
- * }
+ *   // Create first wallet
+ *   if (ethereum.status === 'disconnected' && ethereum.wallets.length === 0) {
+ *     return <Button onPress={() => ethereum.create()} title="Create Wallet" />;
+ *   }
+ *
+ *   // Activate existing wallet
+ *   if (ethereum.status === 'disconnected' && ethereum.wallets.length > 0) {
+ *     return (
+ *       <Button
+ *         onPress={() => ethereum.setActive({
+ *           address: ethereum.wallets[0].address,
+ *           recoveryPassword: 'optional-password'
+ *         })}
+ *         title="Connect Wallet"
+ *       />
+ *     );
+ *   }
+ *
+ *   // Use connected wallet
+ *   if (ethereum.status === 'connected') {
+ *     const sendTransaction = async () => {
+ *       const tx = await ethereum.provider.request({
+ *         method: 'eth_sendTransaction',
+ *         params: [{
+ *           from: ethereum.activeWallet.address,
+ *           to: '0x...',
+ *           value: '0x0'
+ *         }]
+ *       });
+ *       console.log('Transaction hash:', tx);
+ *     };
+ *
+ *     return <Button onPress={sendTransaction} title="Send Transaction" />;
+ *   }
  *
- * // Create wallet if none exist
- * if (ethereum.status === 'disconnected' && ethereum.wallets.length === 0) {
- *   await ethereum.create({ chainId: 1 });
+ *   return null;
  * }
  * ```
  */
@@ -200,10 +251,11 @@ export function useEmbeddedEthereumWallet(options = {}) {
             }
             // Build recovery params
             const recoveryParams = await buildRecoveryParams(createOptions, walletConfig);
+            const accountType = createOptions?.accountType || walletConfig?.accountType || AccountTypeEnum.SMART_ACCOUNT;
             // Create embedded wallet
             const embeddedAccount = await client.embeddedWallet.create({
-                chainId,
-                accountType: createOptions?.accountType || walletConfig?.accountType || AccountTypeEnum.SMART_ACCOUNT,
+                chainId: accountType === AccountTypeEnum.EOA ? undefined : chainId,
+                accountType,
                 chainType: ChainTypeEnum.EVM,
                 recoveryParams,
             });

package/dist/hooks/wallet/useEmbeddedSolanaWallet.js

@@ -9,36 +9,100 @@ import { buildRecoveryParams } from './utils';
 /**
  * Hook for managing embedded Solana wallets.
  *
- * This hook provides comprehensive Solana wallet management including creation, activation,
- * and recovery. It returns a discriminated union state that enables type-safe wallet interactions.
+ * This hook provides comprehensive management of embedded Solana (SVM) wallets including
+ * creation, recovery, activation, and transaction signing. Returns a discriminated union
+ * state that enables type-safe wallet interactions based on connection status.
  *
- * @param options - Configuration with callback functions
- * @returns Discriminated union state object. The `status` field determines available properties.
- * Possible states: 'disconnected', 'connecting', 'reconnecting', 'creating', 'needs-recovery',
- * 'connected', 'error'. When connected, includes `provider` and `activeWallet`. All states include
- * `create`, `setActive`, and `wallets` methods/properties.
+ * **Note:** Solana wallets are always EOA (Externally Owned Accounts) and work across
+ * all Solana networks (mainnet, devnet, testnet).
+ *
+ * **Recovery Methods:**
+ * - Automatic recovery (via encryption session)
+ * - Password-based recovery
+ *
+ * @param options - Configuration options including:
+ *   - `onCreateSuccess` - Callback when wallet is created
+ *   - `onCreateError` - Callback when wallet creation fails
+ *   - `onSetActiveSuccess` - Callback when wallet is activated/recovered
+ *   - `onSetActiveError` - Callback when wallet activation fails
+ *
+ * @returns Discriminated union state based on `status` field:
+ *   - **'disconnected'**: No active wallet. Properties: `create`, `setActive`, `wallets`
+ *   - **'connecting'**: Activating wallet. Properties: same as disconnected
+ *   - **'reconnecting'**: Reconnecting to wallet. Properties: same as disconnected + `activeWallet`
+ *   - **'creating'**: Creating new wallet. Properties: same as disconnected
+ *   - **'needs-recovery'**: Recovery required. Properties: same as reconnecting
+ *   - **'connected'**: Wallet ready. Properties: all + `provider` (Solana wallet adapter)
+ *   - **'error'**: Operation failed. Properties: all + `error` message + optional `activeWallet`
  *
  * @example
  * ```tsx
- * import { useEmbeddedSolanaWallet, isConnected, isLoading } from '@openfort/react-native';
+ * import { useEmbeddedSolanaWallet } from '@openfort/react-native';
+ * import { Transaction } from '@solana/web3.js';
+ * import { ActivityIndicator } from 'react-native';
  *
- * const solana = useEmbeddedSolanaWallet({
- *   onCreateSuccess: (account, provider) => console.log('Wallet created:', account.address),
- * });
+ * function SolanaWalletComponent() {
+ *   const solana = useEmbeddedSolanaWallet({
+ *     onCreateSuccess: (account, provider) => {
+ *       console.log('Solana wallet created:', account.address);
+ *       console.log('Public key:', provider.publicKey);
+ *     },
+ *   });
  *
- * if (isLoading(solana)) {
- *   return <ActivityIndicator />;
- * }
+ *   // Handle loading states
+ *   if (solana.status === 'creating' || solana.status === 'connecting') {
+ *     return <ActivityIndicator />;
+ *   }
  *
- * if (isConnected(solana)) {
- *   // TypeScript knows provider and activeWallet are available
- *   const signed = await solana.provider.signTransaction(transaction);
- *   const publicKey = solana.provider.publicKey;
- * }
+ *   // Create first wallet
+ *   if (solana.status === 'disconnected' && solana.wallets.length === 0) {
+ *     return (
+ *       <Button
+ *         onPress={() => solana.create({ recoveryPassword: 'optional' })}
+ *         title="Create Solana Wallet"
+ *       />
+ *     );
+ *   }
+ *
+ *   // Activate existing wallet
+ *   if (solana.status === 'disconnected' && solana.wallets.length > 0) {
+ *     return (
+ *       <Button
+ *         onPress={() => solana.setActive({
+ *           address: solana.wallets[0].address,
+ *           recoveryPassword: 'optional'
+ *         })}
+ *         title="Connect Solana Wallet"
+ *       />
+ *     );
+ *   }
+ *
+ *   // Use connected wallet
+ *   if (solana.status === 'connected') {
+ *     const signTransaction = async () => {
+ *       const transaction = new Transaction();
+ *       // ... add instructions to transaction
+ *
+ *       const signed = await solana.provider.signTransaction(transaction);
+ *       console.log('Signed transaction:', signed);
+ *     };
  *
- * // Create wallet if none exist
- * if (solana.status === 'disconnected' && solana.wallets.length === 0) {
- *   await solana.create({ recoveryMethod: 'automatic' });
+ *     const signMessage = async () => {
+ *       const message = 'Hello Solana!';
+ *       const signature = await solana.provider.signMessage(message);
+ *       console.log('Message signature:', signature);
+ *     };
+ *
+ *     return (
+ *       <View>
+ *         <Text>Connected: {solana.activeWallet.address}</Text>
+ *         <Button onPress={signTransaction} title="Sign Transaction" />
+ *         <Button onPress={signMessage} title="Sign Message" />
+ *       </View>
+ *     );
+ *   }
+ *
+ *   return null;
  * }
  * ```
  */
@@ -102,18 +166,18 @@ export function useEmbeddedSolanaWallet(options = {}) {
             // Extract the message bytes from the transaction
             // For @solana/kit compiledTransaction, the messageBytes property contains what needs to be signed
             let messageBytes;
-            if (transaction.messageBytes) {
+            if (transaction instanceof Uint8Array) {
+                // Raw bytes
+                messageBytes = transaction;
+            }
+            else if ('messageBytes' in transaction) {
                 // @solana/kit compiled transaction
                 messageBytes = transaction.messageBytes;
             }
-            else if (transaction.serializeMessage) {
+            else if ('serializeMessage' in transaction) {
                 // @solana/web3.js Transaction
                 messageBytes = transaction.serializeMessage();
             }
-            else if (transaction instanceof Uint8Array) {
-                // Raw bytes
-                messageBytes = transaction;
-            }
             else {
                 throw new OpenfortError('Unsupported transaction format. Expected @solana/kit compiled transaction, @solana/web3.js Transaction, or Uint8Array', OpenfortErrorType.WALLET_ERROR);
             }
@@ -125,13 +189,12 @@ export function useEmbeddedSolanaWallet(options = {}) {
                 data: Array.from(messageBytes),
             };
             // Sign the message bytes (hashMessage: false for Solana - Ed25519 signs raw bytes)
-            // Note: We cast to any because the iframe will deserialize the Buffer format correctly,
+            // Note: We cast to unknown because the iframe will deserialize the Buffer format correctly,
             // but TypeScript doesn't know about this serialization detail
             const signatureBase58 = await client.embeddedWallet.signMessage(bufferFormatMessage, {
                 hashMessage: false,
             });
             // Return the signature in the expected format
-            // Different libraries expect different return formats, so we return a flexible object
             return {
                 signature: signatureBase58,
                 publicKey: account.address,

package/dist/types/core/provider.d.ts

@@ -103,13 +103,22 @@ export interface OpenfortProviderProps {
     verbose?: boolean;
 }
 /**
- * Provider component that initialises the Openfort SDK and exposes its state via {@link OpenfortContext}
+ * Root provider component that initializes the Openfort SDK and makes it available throughout your app.
  *
- * This component must wrap your React Native app to provide Openfort functionality to all child components.
- * It initializes the SDK with the provided configuration and manages authentication state.
+ * This component must wrap your React Native application to enable Openfort functionality.
+ * It initializes the SDK, manages authentication state, handles embedded wallet connections,
+ * and provides context to all child components through {@link OpenfortContext}.
  *
- * @param props - Provider configuration including the publishable key and optional overrides
- * @returns A React element that provides the Openfort context to its children
+ * **Key Features:**
+ * - Initializes Openfort client with platform-specific configuration
+ * - Manages user authentication state and session persistence
+ * - Polls embedded wallet state for real-time status updates
+ * - Provides hidden WebView for embedded wallet communication
+ * - Supports multiple blockchain networks via supportedChains
+ * - Integrates Shield for secure embedded wallet management
+ *
+ * @param props - Provider configuration, see {@link OpenfortProviderProps}
+ * @returns React element that provides Openfort context to all children
  *
  * @example
  * ```tsx
@@ -123,7 +132,12 @@ export interface OpenfortProviderProps {
  *       supportedChains={[polygon, polygonMumbai]}
  *       walletConfig={{
  *         shieldPublishableKey: "shield_pk_...",
- *         getEncryptionSession: () => fetchEncryptionSession(),
+ *         getEncryptionSession: async () => {
+ *           // Fetch session from your backend
+ *           const response = await fetch('/api/encryption-session');
+ *           return response.text();
+ *         },
+ *         recoveryMethod: 'automatic',
  *       }}
  *       verbose={true}
  *     >

package/dist/types/hooks/auth/useEmailAuth.d.ts

@@ -45,12 +45,23 @@ export type UseEmailHookOptions = {
 /**
  * Hook for email and password authentication.
  *
- * This hook provides email/password authentication flows including sign-in, sign-up, and
- * account linking. Password reset and verification helpers are exposed but currently stubbed
- * (TODOs) until the SDK wiring is complete.
+ * This hook provides comprehensive email/password authentication flows including sign-in,
+ * sign-up, account linking, password reset, and email verification functionality.
  *
- * @param hookOptions - Optional configuration with callback functions and email verification settings.
- * @returns Email authentication state and methods with flow status indicators.
+ * @param hookOptions - Optional configuration with callback functions and email verification settings
+ * @returns Email authentication state and methods with flow status indicators including:
+ *   - `signInEmail` - Sign in with email and password
+ *   - `signUpEmail` - Create new account with email and password
+ *   - `linkEmail` - Link email/password to existing authenticated account
+ *   - `requestResetPassword` - Request password reset email
+ *   - `resetPassword` - Complete password reset with token from email
+ *   - `verifyEmail` - Verify email address with verification code
+ *   - `reset` - Reset flow state to initial
+ *   - `isLoading` - Whether an operation is in progress
+ *   - `isError` - Whether the last operation failed
+ *   - `isSuccess` - Whether the last operation succeeded
+ *   - `requiresEmailVerification` - Whether email verification is pending
+ *   - `error` - Error from the last failed operation
  *
  * @example
  * ```tsx
@@ -59,12 +70,14 @@ export type UseEmailHookOptions = {
  *   onError: ({ error }) => console.error('Email auth failed:', error?.message),
  * });
  *
+ * // Sign up a new user
  * await signUpEmail({ email: 'user@example.com', password: 'securePassword123' });
  *
  * if (requiresEmailVerification) {
  *   console.log('Check email for verification code');
  * }
  *
+ * // Sign in existing user
  * await signInEmail({ email: 'user@example.com', password: 'securePassword123' });
  * ```
  */