@openfort/react-native 0.1.9 → 0.1.10

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

@@ -1,7 +1,7 @@
 import React from 'react';
 import { SDKOverrides, AccountTypeEnum, ThirdPartyAuthConfiguration } from '@openfort/openfort-js';
 /**
- * Custom auth configuration
+ * Shape for configuring custom authentication synchronisation behaviour.
  */
 interface CustomAuthConfig {
     enabled: boolean;
@@ -10,9 +10,9 @@ interface CustomAuthConfig {
 }
 type PolicyConfig = string | Record<number, string>;
 export type CommonEmbeddedWalletConfiguration = {
-    /** Publishable key for the Shield API */
+    /** Publishable key for the Shield API. */
     shieldPublishableKey: string;
-    /** Policy ID (pol_...) for the embedded signer */
+    /** Policy ID (pol_...) for the embedded signer. */
     ethereumProviderPolicyId?: PolicyConfig;
     accountType?: AccountTypeEnum;
     debug?: boolean;
@@ -27,16 +27,13 @@ export type EncryptionSession = {
     getEncryptionSession?: never;
 };
 /**
- * Configuration for automatic recovery.
- * - An encryption session is required.
+ * Configuration for enabling embedded wallet recovery flows.
  *
- * Configuration for password-based recovery.
- * - An encryption session, OR
- * - A `shieldEncryptionKey` without an encryption session.
- *
- * Encryption session can be created using either:
- * - `createEncryptedSessionEndpoint` as a string, OR
- * - `getEncryptionSession.` as a function that returns a promise.
+ * Automatic recovery requires an encryption session, while password-based recovery may either use
+ * an encryption session or a Shield encryption key. Provide a
+ * {@link EncryptionSession.getEncryptionSession | getEncryptionSession} callback to surface the
+ * session identifier. TODO: add support for `createEncryptedSessionEndpoint` once the native
+ * hooks implement that pathway.
  */
 export type EmbeddedWalletConfiguration = CommonEmbeddedWalletConfiguration & EncryptionSession;
 /**
@@ -49,7 +46,7 @@ type RpcUrls = {
 };
 type NativeCurrency = {
     name: string;
-    /** 2-6 characters long */
+    /** 2-6 characters long. */
     symbol: string;
     decimals: number;
 };
@@ -57,62 +54,91 @@ type BlockExplorer = {
     name: string;
     url: string;
 };
-/** A subset of WAGMI's chain type
+/**
+ * A subset of WAGMI's chain type.
+ *
  * https://github.com/wagmi-dev/references/blob/6aea7ee9c65cfac24f33173ab3c98176b8366f05/packages/chains/src/types.ts#L8
  */
 export type Chain = {
-    /** Id in number form */
+    /** Chain identifier in number form. */
     id: number;
-    /** Human readable name */
+    /** Human readable name. */
     name: string;
-    /** Internal network name */
+    /** Internal network name. */
     network?: string;
-    /** Currency used by chain */
+    /** Currency used by chain. */
     nativeCurrency: NativeCurrency;
-    /** Collection of block explorers */
+    /** Collection of block explorers. */
     blockExplorers?: {
         [key: string]: BlockExplorer;
         default: BlockExplorer;
     };
-    /** Collection of RPC endpoints */
+    /** Collection of RPC endpoints. */
     rpcUrls: {
         [key: string]: RpcUrls;
         default: RpcUrls;
     };
-    /** Flag for test networks */
+    /** Flag for test networks. */
     testnet?: boolean;
 };
 /**
- * Props for the OpenfortProvider component
+ * Props for the {@link OpenfortProvider} component.
  */
 export interface OpenfortProviderProps {
     children: React.ReactNode;
     customAuth?: CustomAuthConfig;
     /**
-     * Openfort application ID (can be found in openfort developer dashboard)
+     * Openfort application ID (can be found in the Openfort developer dashboard).
      */
     publishableKey: string;
     supportedChains?: [Chain, ...Chain[]];
     /**
-     * Embedded signer configuration for Shield integration
+     * Embedded signer configuration for Shield integration.
      */
     walletConfig?: EmbeddedWalletConfiguration;
     /**
-     * SDK overrides configuration for advanced customization
+     * SDK overrides configuration for advanced customization.
      */
     overrides?: SDKOverrides;
     /**
-     * Third party auth configuration for integrating with external auth providers
+     * Third party auth configuration for integrating with external auth providers.
      */
     thirdPartyAuth?: ThirdPartyAuthConfiguration;
     /**
-     * Enable verbose logging for debugging purposes
+     * Enable verbose logging for debugging purposes.
      */
     verbose?: boolean;
 }
 /**
- * Main provider component that wraps the entire application and provides
- * Openfort SDK functionality through React context
+ * Provider component that initialises the Openfort SDK and exposes its state via {@link OpenfortContext}
+ *
+ * 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.
+ *
+ * @param props - Provider configuration including the publishable key and optional overrides
+ * @returns A React element that provides the Openfort context to its children
+ *
+ * @example
+ * ```tsx
+ * import { OpenfortProvider } from '@openfort/react-native';
+ * import { polygon, polygonMumbai } from 'viem/chains';
+ *
+ * function App() {
+ *   return (
+ *     <OpenfortProvider
+ *       publishableKey="pk_test_..."
+ *       supportedChains={[polygon, polygonMumbai]}
+ *       walletConfig={{
+ *         shieldPublishableKey: "shield_pk_...",
+ *         getEncryptionSession: () => fetchEncryptionSession(),
+ *       }}
+ *       verbose={true}
+ *     >
+ *       <YourAppContent />
+ *     </OpenfortProvider>
+ *   );
+ * }
+ * ```
  */
 export declare const OpenfortProvider: ({ children, publishableKey, customAuth, supportedChains, walletConfig, overrides, thirdPartyAuth, verbose, }: OpenfortProviderProps) => React.JSX.Element;
 export {};

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

@@ -23,13 +23,16 @@ interface OpenfortStorage {
     }>;
 }
 /**
- * Storage adapter using `expo-secure-store` intended for
- * use with `Openfort` class from `@openfort/openfort-js`.
+ * Storage adapter backed by {@link SecureStore} that matches the {@link Storage} interface expected by `@openfort/openfort-js`.
+ *
+ * The adapter normalises the keys provided by the Openfort SDK so they can be safely persisted via Expo Secure Store.
  */
 export declare const SecureStorageAdapter: OpenfortStorage;
 /**
- * Creates a type-safe storage adapter that bridges between the Openfort SDK's
- * expected Storage interface and our React Native implementation
+ * Creates a type-safe storage adapter that bridges the Openfort SDK storage API with the React Native implementation.
+ *
+ * @param customStorage - Optional custom storage implementation. When omitted the {@link SecureStorageAdapter} is used.
+ * @returns An object that satisfies the {@link Storage} interface expected by `@openfort/openfort-js`.
  */
 export declare function createNormalizedStorage(customStorage?: OpenfortStorage): Storage;
 export {};

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

@@ -1,5 +1,5 @@
 /**
- * Authentication hooks index
+ * Authentication hooks index.
  *
  * This module re-exports all authentication-related hooks for convenient importing.
  */

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

@@ -1,4 +1,13 @@
 export type CreateWalletPostAuthOptions = {};
+/**
+ * Hook for creating wallets after user authentication.
+ *
+ * TODO: the implementation is currently a placeholder that always returns an
+ * undefined wallet. Once the post-auth wallet flow is wired up, this helper will
+ * attempt to provision or connect an embedded wallet automatically.
+ *
+ * @returns Object containing wallet creation utilities (placeholder for now).
+ */
 export declare const useCreateWalletPostAuth: () => {
     tryUseWallet: ({}: CreateWalletPostAuthOptions) => Promise<{
         wallet: undefined;

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

@@ -43,6 +43,32 @@ export type EmailVerificationResult = {
 export type UseEmailHookOptions = {
     emailVerificationRedirectTo?: string;
 } & OpenfortHookOptions<EmailAuthResult | EmailVerificationResult> & CreateWalletPostAuthOptions;
+/**
+ * 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.
+ *
+ * @param hookOptions - Optional configuration with callback functions and email verification settings.
+ * @returns Email authentication state and methods with flow status indicators.
+ *
+ * @example
+ * ```tsx
+ * const { signInEmail, signUpEmail, linkEmail, isLoading, requiresEmailVerification } = useEmailAuth({
+ *   onSuccess: ({ user }) => console.log('Email auth successful:', user?.id),
+ *   onError: ({ error }) => console.error('Email auth failed:', error?.message),
+ * });
+ *
+ * await signUpEmail({ email: 'user@example.com', password: 'securePassword123' });
+ *
+ * if (requiresEmailVerification) {
+ *   console.log('Check email for verification code');
+ * }
+ *
+ * await signInEmail({ email: 'user@example.com', password: 'securePassword123' });
+ * ```
+ */
 export declare const useEmailAuth: (hookOptions?: UseEmailHookOptions) => {
     isLoading: boolean;
     isError: boolean;

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

@@ -1,35 +1,33 @@
-/**
- * Hook for creating guest accounts
- */
 import type { AuthPlayerResponse as OpenfortUser } from '@openfort/openfort-js';
 import { OpenfortHookOptions } from '../../types/hookOption';
 import { OpenfortError } from '../../types/openfortError';
 import { CreateWalletPostAuthOptions } from './useCreateWalletPostAuth';
+export type GuestHookResult = {
+    error?: OpenfortError;
+    user?: OpenfortUser;
+};
+export type GuestHookOptions = OpenfortHookOptions<GuestHookResult> & CreateWalletPostAuthOptions;
 /**
- * Hook for creating guest accounts
+ * Hook for creating guest accounts.
  *
- * Guest accounts allow users to access certain features without full authentication.
- * These accounts can later be upgraded to full accounts by linking authentication methods.
+ * Guest accounts allow users to access certain features without full authentication and can later be upgraded to full accounts
+ * by linking additional authentication methods.
  *
- * @param opts - Configuration options including success/error callbacks
- * @returns Object with create function
+ * @param hookOptions - Configuration options including success and error callbacks.
+ * @returns Current guest authentication helpers with flow status indicators.
  *
  * @example
  * ```tsx
- * const { create } = useGuestAuth({
- *   onSuccess: (user) => console.log('Guest account created:', user),
- *   onError: (error) => console.error('Failed to create guest account:', error),
+ * const { signUpGuest, isLoading } = useGuestAuth({
+ *   onSuccess: ({ user }) => console.log('Guest account created:', user),
+ *   onError: ({ error }) => console.error('Failed to create guest account:', error),
  * });
  *
- * // Create a guest account
- * const guestUser = await create();
+ * if (!isLoading) {
+ *   await signUpGuest();
+ * }
  * ```
  */
-export type GuestHookResult = {
-    error?: OpenfortError;
-    user?: OpenfortUser;
-};
-export type GuestHookOptions = OpenfortHookOptions<GuestHookResult> & CreateWalletPostAuthOptions;
 export declare const useGuestAuth: (hookOptions?: GuestHookOptions) => {
     isLoading: boolean;
     isError: boolean;

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

@@ -1,6 +1,3 @@
-/**
- * Hook for OAuth-based login functionality
- */
 import { OAuthProvider, type AuthPlayerResponse as OpenfortUser } from '@openfort/openfort-js';
 import { OpenfortHookOptions } from '../../types/hookOption';
 import { CreateWalletPostAuthOptions } from './useCreateWalletPostAuth';
@@ -22,33 +19,30 @@ export type AuthHookOptions = {
     redirectTo?: string;
 } & OpenfortHookOptions<StoreCredentialsResult | InitOAuthReturnType> & CreateWalletPostAuthOptions;
 /**
- * Hook for OAuth-based authentication with supported providers
+ * Hook for OAuth-based authentication with supported providers.
  *
- * This hook provides OAuth authentication flow for various providers (Google, Apple, Discord, etc.).
- * It opens the provider's web authentication page and handles the OAuth flow automatically.
+ * 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.
  *
- * @param opts - Configuration options including success/error callbacks
- * @returns Object with login function and current OAuth flow state
+ * @param hookOptions - Configuration options including success and error callbacks.
+ * @returns OAuth helpers and derived flow state flags.
  *
  * @example
  * ```tsx
- * const { login, state } = useLoginWithOAuth({
- *   onSuccess: (user) => console.log('OAuth login successful:', user),
- *   onError: (error) => console.error('OAuth login failed:', error),
+ * const { initOAuth, linkOauth, isLoading, isError, error } = useOAuth({
+ *   onSuccess: ({ user }) => console.log('OAuth completed for', user?.id),
  * });
  *
- * // Login with Google
- * const user = await login({ provider: 'google' });
+ * // Start a login flow
+ * await initOAuth({ provider: OAuthProvider.GOOGLE });
  *
- * // Login with Apple (using legacy web flow on iOS if needed)
- * const user = await login({
- *   provider: 'apple',
- *   isLegacyAppleIosBehaviorEnabled: true
- * });
+ * // Later, link another provider for the signed-in user
+ * await linkOauth({ provider: OAuthProvider.DISCORD });
  *
- * // Other supported providers
- * await login({ provider: 'discord' });
- * await login({ provider: 'twitter' });
+ * if (isError) {
+ *   console.warn('Latest OAuth attempt failed', error);
+ * }
  * ```
  */
 export declare const useOAuth: (hookOptions?: AuthHookOptions) => {

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

@@ -1,5 +1,37 @@
 import { OpenfortHookOptions } from "../../types/hookOption";
 import { OpenfortError } from "../../types/openfortError";
+/**
+ * Hook for user sign out functionality
+ *
+ * This hook provides secure sign out capabilities that clear user authentication state
+ * and refresh the application context to reflect the unauthenticated state.
+ *
+ * @param hookOptions - Optional configuration with callback functions for handling success and error events
+ * @returns Sign out method with loading and error state indicators
+ *
+ * @example
+ * ```tsx
+ * const { signOut, isLoading, isError, error } = useSignOut({
+ *   onSuccess: () => console.log('Successfully signed out'),
+ *   onError: ({ error }) => console.error('Sign out failed:', error?.message),
+ * });
+ *
+ * // Sign out the current user
+ * if (!isLoading) {
+ *   await signOut();
+ * }
+ *
+ * // Handle loading states
+ * if (isLoading) {
+ *   console.log('Signing out...');
+ * }
+ *
+ * // Handle errors
+ * if (isError && error) {
+ *   console.error('Sign out error:', error.message);
+ * }
+ * ```
+ */
 export declare function useSignOut(hookOptions?: OpenfortHookOptions): {
     signOut: (options?: OpenfortHookOptions) => Promise<{} | undefined>;
     isLoading: boolean;

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

@@ -1,6 +1,3 @@
-/**
- * Hook for linking Ethereum accounts using SIWE to existing users
- */
 import { AuthPlayerResponse as OpenfortUser } from '@openfort/openfort-js';
 import { OpenfortHookOptions } from '../../types/hookOption';
 import { OpenfortError } from '../../types/openfortError';
@@ -33,6 +30,31 @@ type GenerateSiweMessageResult = {
     error?: OpenfortError;
     message?: string;
 };
+/**
+ * Hook for handling Sign-In With Ethereum (SIWE) 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`).
+ *
+ * @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.
+ *
+ * @example
+ * ```tsx
+ * const { generateSiweMessage, signInWithSiwe, linkSiwe, isAwaitingSignature } = useWalletAuth({
+ *   onSuccess: ({ user }) => console.log('SIWE flow completed for', user?.id),
+ * });
+ *
+ * const { message } = await generateSiweMessage({
+ *   wallet: connectedWallet.address,
+ *   from: { domain: 'app.openfort.io', uri: 'https://app.openfort.io' },
+ * });
+ *
+ * const signature = await connectedWallet.signMessage(message);
+ * await signInWithSiwe({ walletAddress: connectedWallet.address, signature, messageOverride: message });
+ * ```
+ */
 export declare function useWalletAuth(hookOptions?: WalletHookOptions): {
     isLoading: boolean;
     isError: boolean;

package/dist/types/hooks/core/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Core hooks index
+ * Core hooks index.
  *
  * This module re-exports all core SDK hooks for convenient importing.
  */

package/dist/types/hooks/core/useOpenfort.d.ts

@@ -1,38 +1,38 @@
 import { UseOpenfort } from '../../types';
 /**
- * Hook that exposes the core state of the Openfort SDK
+ * Hook that exposes the core state of the Openfort SDK.
  *
- * This hook provides access to the current authenticated user object,
- * SDK initialization status, and core authentication methods.
+ * This hook provides access to the current authenticated user object, SDK initialization status, and core authentication methods.
  *
- * @returns The Openfort SDK's core state and methods
+ * @returns The Openfort SDK's core state and methods.
  *
  * @example
  * ```tsx
- * const { user, isReady, error, logout, getAccessToken } = useOpenfort();
+ * import { ActivityIndicator, Button, Text, View } from 'react-native';
+ * import { useOpenfort } from '@openfort/react-native/hooks';
  *
- * // Check if SDK is ready
- * if (!isReady) {
- *   return <LoadingSpinner />;
- * }
+ * export function HomeScreen() {
+ *   const { user, isReady, error, logout } = useOpenfort();
  *
- * // Handle initialization errors
- * if (error) {
- *   return <ErrorDisplay error={error} />;
- * }
+ *   if (!isReady) {
+ *     return <ActivityIndicator size="large" />;
+ *   }
  *
- * // Check authentication status
- * if (!user) {
- *   return <LoginScreen />;
- * }
+ *   if (error) {
+ *     return <Text>{`Failed to initialise: ${error.message}`}</Text>;
+ *   }
  *
- * // User is authenticated
- * return (
- *   <div>
- *     <h1>Welcome, {user.id}!</h1>
- *     <button onClick={logout}>Logout</button>
- *   </div>
- * );
+ *   if (!user) {
+ *     return <Text>Please sign in</Text>;
+ *   }
+ *
+ *   return (
+ *     <View>
+ *       <Text>{`Welcome, ${user.id}`}</Text>
+ *       <Button title="Log out" onPress={() => void logout()} />
+ *     </View>
+ *   );
+ * }
  * ```
  */
 export declare function useOpenfort(): UseOpenfort;

package/dist/types/hooks/core/useOpenfortClient.d.ts

@@ -1,29 +1,21 @@
-/**
- * Hook for accessing the Openfort client instance
- */
 import type { Openfort as OpenfortClient } from '@openfort/openfort-js';
 /**
- * Hook for accessing the Openfort client instance directly
+ * Hook for accessing the Openfort client instance directly.
  *
- * This hook provides access to the underlying Openfort client for advanced use cases
- * where you need direct access to the client methods.
+ * This hook exposes the underlying {@link OpenfortClient} so that advanced consumer code can access low-level methods that are
+ * not surfaced through the convenience hooks.
  *
- * @returns The Openfort client instance
+ * @returns The current {@link OpenfortClient} instance from context.
  *
  * @example
  * ```tsx
  * const client = useOpenfortClient();
  *
- * // Use client methods directly
- * const customResult = await client.auth.customMethod();
- *
- * // Access client configuration
- * console.log('App ID:', client.config.appId);
+ * // Invoke a raw SDK method
+ * const token = await client.getAccessToken();
  *
- * // Check client status
- * if (client.isInitialized) {
- *   // Perform operations that require initialization
- * }
+ * // Access nested services
+ * await client.auth.logout();
  * ```
  */
 export declare function useOpenfortClient(): OpenfortClient;

package/dist/types/hooks/core/useUser.d.ts

@@ -1,3 +1,31 @@
+/**
+ * Hook for accessing current user state and authentication status
+ *
+ * This hook provides access to the current user's information and authentication state.
+ * It automatically updates when the user signs in, signs out, or their profile changes.
+ *
+ * @returns Current user data, authentication status, and access token getter
+ *
+ * @example
+ * ```tsx
+ * const { user, isAuthenticated, getAccessToken } = useUser();
+ *
+ * // Check if user is authenticated
+ * if (isAuthenticated && user) {
+ *   console.log('Authenticated user:', user.id);
+ *   console.log('User email:', user.email);
+ *
+ *   // Get access token for API calls
+ *   const token = await getAccessToken();
+ *   console.log('Access token available:', !!token);
+ * } else {
+ *   console.log('User not authenticated');
+ * }
+ *
+ * // Use in conditional rendering
+ * return isAuthenticated ? <Dashboard user={user} /> : <LoginForm />;
+ * ```
+ */
 export declare function useUser(): {
     user: import("@openfort/openfort-js").AuthPlayerResponse | null;
     isAuthenticated: boolean;

package/dist/types/hooks/index.d.ts

@@ -1,11 +1,12 @@
 /**
- * Openfort React Native SDK Hooks
+ * Openfort React Native SDK hooks.
  *
- * This module provides a comprehensive set of React hooks for integrating
- * with the Openfort platform in React Native applications.
- *
- * The hooks are organized into the following categories:
- * - Core: Core SDK functionality hooks
+ * This barrel re-exports all hook collections that ship with the SDK so consumers can
+ * import from `@openfort/react-native/hooks`. The hooks are organised into the
+ * following sub-modules:
+ * - Core: Lifecycle/state helpers (e.g. `useOpenfort`)
+ * - Auth: Authentication helpers (email, OAuth, SIWE, guest)
+ * - Wallet: Embedded wallet management utilities
  */
 export * from './core';
 export * from './auth';

package/dist/types/hooks/wallet/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Wallet hooks index
+ * Wallet hooks index.
  *
  * This module re-exports all wallet-related hooks for convenient importing.
  */

package/dist/types/hooks/wallet/useWallet.d.ts

@@ -1 +1,28 @@
+/**
+ * Hook for accessing the currently active embedded wallet
+ *
+ * This hook provides access to the currently active embedded wallet from the wallet collection.
+ * It automatically updates when the active wallet changes through other wallet operations.
+ *
+ * @returns The active embedded wallet when available, otherwise `null`
+ *
+ * @example
+ * ```tsx
+ * const activeWallet = useWallet();
+ *
+ * // Check if wallet is available
+ * if (activeWallet) {
+ *   console.log('Active wallet address:', activeWallet.address);
+ *
+ *   // Get provider for transactions
+ *   const provider = await activeWallet.getProvider();
+ *
+ *   // Use wallet for operations
+ *   console.log('Wallet chain type:', activeWallet.chainType);
+ *   console.log('Is connecting:', activeWallet.isConnecting);
+ * } else {
+ *   console.log('No active wallet available');
+ * }
+ * ```
+ */
 export declare function useWallet(): import("../..").UserWallet | null;