@openfort/react-native 0.1.9 → 0.1.10

package/dist/hooks/core/useUser.js

@@ -1,5 +1,33 @@
 import { EmbeddedState } from "@openfort/openfort-js";
 import { useOpenfortContext } from "../../core";
+/**
+ * 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 function useUser() {
     const { user, embeddedState, getAccessToken } = useOpenfortContext();
     return {

package/dist/hooks/index.js

@@ -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
  */
 // Re-export all core hooks
 export * from './core';

package/dist/hooks/wallet/index.js

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

package/dist/hooks/wallet/useWallet.js

@@ -1,4 +1,31 @@
 import { useWallets } from "./useWallets";
+/**
+ * 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 function useWallet() {
     const { activeWallet } = useWallets();
     return activeWallet;

package/dist/hooks/wallet/useWallets.js

@@ -1,6 +1,3 @@
-/**
- * Hook for embedded Ethereum wallet functionality
- */
 import { AccountTypeEnum, ChainTypeEnum, EmbeddedState, RecoveryMethod } from '@openfort/openfort-js';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useOpenfortContext } from '../../core/context';
@@ -17,31 +14,36 @@ const mapWalletStatus = (status) => {
     };
 };
 /**
- * Hook for interacting with embedded Ethereum wallets
+ * Hook for interacting with embedded wallets
  *
- * This hook manages embedded Ethereum wallets based on the user's state from the provider.
- * Wallet state is determined by polling in the provider, not by local state management.
+ * This hook manages embedded wallets based on the user's state from the provider. Wallet state is determined by
+ * polling in the provider, not by local state management. It provides wallet creation, recovery, and management capabilities.
  *
- * @param props - Optional configuration with callback functions
- * @returns Current embedded Ethereum wallet state with actions
+ * @param hookOptions - Optional configuration with callback functions and chain ID settings
+ * @returns Current embedded wallet state with actions and wallet collection
  *
  * @example
  * ```tsx
- * const ethereumWallet = useEmbeddedEthereumWallet({
- *   onCreateWalletSuccess: (provider) => console.log('Ethereum wallet created:', provider),
- *   onCreateWalletError: (error) => console.error('Ethereum wallet creation failed:', error),
+ * const { wallets, activeWallet, createWallet, setActiveWallet, isCreating } = useWallets({
+ *   onSuccess: ({ wallet }) => console.log('Wallet operation successful:', wallet?.address),
+ *   onError: ({ error }) => console.error('Wallet operation failed:', error?.message),
+ *   chainId: 1, // Ethereum mainnet
  * });
  *
- * // Check wallet status and create if needed
- * if (ethereumWallet.status === 'disconnected') {
- *   await ethereumWallet.create(); // Uses default chain
- *   // Or with specific chain: await ethereumWallet.create({ chainId: 1 });
+ * // Create a new wallet if none exist
+ * if (wallets.length === 0 && !isCreating) {
+ *   await createWallet({ chainId: 1 });
+ * }
+ *
+ * // Use existing wallets
+ * if (wallets.length > 0 && !activeWallet) {
+ *   await setActiveWallet({ address: wallets[0].address });
  * }
  *
- * // Use connected wallets
- * if (ethereumWallet.status === 'connected' && ethereumWallet.wallets.length > 0) {
- *   const provider = await ethereumWallet.wallets[0].getProvider();
- *   // Use provider for Ethereum transactions
+ * // Access active wallet
+ * if (activeWallet) {
+ *   const provider = await activeWallet.getProvider();
+ *   // Use provider for transactions
  * }
  * ```
  */

package/dist/index.js

@@ -1,12 +1,11 @@
 /**
- * Openfort React Native SDK
+ * @packageDocumentation
  *
- * A comprehensive React Native SDK for integrating with the Openfort platform.
- * This SDK provides authentication, embedded wallets, session management, and UI components
- * for building decentralized applications on React Native.
+ * Entry point for the Openfort React Native SDK.
  *
- * @author Openfort
- * @version 0.1.8
+ * This package re-exports the core SDK functionality, hooks, components and native helpers
+ * required to integrate Openfort authentication and embedded wallets into React Native and
+ * Expo applications.
  */
 // Re-export commonly used types from @openfort/openfort-js
 export { OpenfortError, RecoveryMethod, Openfort as OpenfortClient, OpenfortConfiguration, ShieldConfiguration, EmbeddedState, } from '@openfort/openfort-js';

package/dist/lib/hookConsistency.js

@@ -1,3 +1,22 @@
+/**
+ * Handles successful hook operation callbacks
+ *
+ * This utility function invokes success and settled callbacks from hook options,
+ * ensuring consistent callback execution across all hooks in the SDK.
+ *
+ * @param params - Object containing hook options and success data
+ * @returns The success data that was passed in
+ *
+ * @example
+ * ```tsx
+ * const result = await someAsyncOperation();
+ * return onSuccess({
+ *   hookOptions,
+ *   options,
+ *   data: { user: result.user },
+ * });
+ * ```
+ */
 export const onSuccess = ({ hookOptions, options, data, }) => {
     hookOptions?.onSuccess?.(data);
     hookOptions?.onSettled?.(data, null);
@@ -5,6 +24,29 @@ export const onSuccess = ({ hookOptions, options, data, }) => {
     options?.onSettled?.(data, null);
     return data;
 };
+/**
+ * Handles failed hook operation callbacks
+ *
+ * This utility function invokes error and settled callbacks from hook options,
+ * and optionally throws the error if throwOnError is configured.
+ *
+ * @param params - Object containing hook options and error information
+ * @returns Object containing the error, or throws if throwOnError is enabled
+ *
+ * @example
+ * ```tsx
+ * try {
+ *   await someAsyncOperation();
+ * } catch (e) {
+ *   const error = new OpenfortError('Operation failed', OpenfortErrorType.GENERIC);
+ *   return onError({
+ *     hookOptions,
+ *     options,
+ *     error,
+ *   });
+ * }
+ * ```
+ */
 export const onError = ({ hookOptions, options, error, }) => {
     hookOptions?.onError?.(error);
     hookOptions?.onSettled?.(null, error);

package/dist/native/oauth.js

@@ -90,7 +90,25 @@ export async function isAppleSignInAvailable() {
     }
 }
 /**
- * Parses OAuth parameters from a URL
+ * Parses OAuth parameters from a redirect URL
+ *
+ * This function extracts OAuth authentication parameters from a callback URL after
+ * a successful or failed OAuth flow. It safely handles URL parsing errors.
+ *
+ * @param url - The OAuth redirect URL containing query parameters
+ * @returns Object containing parsed OAuth parameters including tokens and error information
+ *
+ * @example
+ * ```tsx
+ * const redirectUrl = 'myapp://oauth/callback?access_token=abc123&player_id=player_123';
+ * const result = parseOAuthUrl(redirectUrl);
+ *
+ * if (result.access_token && result.player_id) {
+ *   console.log('OAuth successful:', result.player_id);
+ * } else if (result.error) {
+ *   console.error('OAuth failed:', result.errorDescription);
+ * }
+ * ```
  */
 export function parseOAuthUrl(url) {
     try {
@@ -111,6 +129,25 @@ export function parseOAuthUrl(url) {
 }
 /**
  * Creates a redirect URI for OAuth flows
+ *
+ * This function generates a deep link URL that OAuth providers can redirect back to
+ * after authentication. The URL follows the app's custom URL scheme.
+ *
+ * @param path - The path component for the redirect URI, defaults to '/'
+ * @returns A complete redirect URI that can be used in OAuth flows
+ *
+ * @example
+ * ```tsx
+ * // Create default OAuth callback URI
+ * const callbackUri = createOAuthRedirectUri('/oauth/callback');
+ * console.log(callbackUri); // 'myapp://oauth/callback'
+ *
+ * // Use in OAuth configuration
+ * const oauthConfig = {
+ *   redirectUri: createOAuthRedirectUri('/auth/success'),
+ *   provider: 'google',
+ * };
+ * ```
  */
 export function createOAuthRedirectUri(path = '/') {
     return Linking.createURL(path);

package/dist/native/storage.js

@@ -3,7 +3,10 @@ import * as SecureStore from 'expo-secure-store';
 import { Platform } from 'react-native';
 import { logger } from '../lib/logger';
 /**
- * Checks if a message is a secure storage related message
+ * Checks if the provided value is a secure storage related message.
+ *
+ * @param message - Incoming message payload.
+ * @returns `true` when the payload matches the {@link SecureStorageMessage} structure.
  */
 export function isSecureStorageMessage(message) {
     if (typeof message !== 'object' ||
@@ -20,7 +23,11 @@ export function isSecureStorageMessage(message) {
     return message.event.startsWith('app:secure-storage:');
 }
 /**
- * Handles secure storage operations from WebView messages
+ * Handles secure storage operations initiated from WebView messages.
+ *
+ * @param message - Parsed WebView message describing the desired storage action.
+ * @returns The response payload that should be sent back to the WebView.
+ * @throws {Error} When the message event is unknown.
  */
 export async function handleSecureStorageMessage(message) {
     logger.info('Handling secure storage message', message);
@@ -131,23 +138,26 @@ export async function handleSecureStorageMessage(message) {
     }
 }
 /**
- * Normalizes storage keys for compatibility with secure storage
+ * Normalises storage keys for compatibility with Expo Secure Store.
+ *
+ * @param key - Original storage key.
+ * @returns The normalised key string.
  */
 function normalizeKey(key) {
     return key.replaceAll(':', '-');
 }
 /**
- * Native storage utilities for platform-specific operations
+ * Native storage utilities for platform-specific operations.
  */
 export const NativeStorageUtils = {
     /**
-     * Checks if secure storage is available on the current platform
+     * Checks if secure storage is available on the current platform.
      */
     isAvailable() {
         return Platform.OS === 'ios' || Platform.OS === 'android';
     },
     /**
-     * Gets the platform-specific storage options
+     * Gets the platform-specific storage options.
      */
     getStorageOptions() {
         return {
@@ -155,7 +165,10 @@ export const NativeStorageUtils = {
         };
     },
     /**
-     * Safely checks if a key exists in secure storage
+     * Safely checks if a key exists in secure storage.
+     *
+     * @param key - Storage key to look up.
+     * @returns `true` if the key is present, otherwise `false`.
      */
     async keyExists(key) {
         try {
@@ -167,7 +180,9 @@ export const NativeStorageUtils = {
         }
     },
     /**
-     * Gets all available storage information
+     * Gets diagnostic information about the native storage capabilities.
+     *
+     * @returns Platform availability information and keychain accessibility value.
      */
     async getStorageInfo() {
         return {

package/dist/types/components/AuthBoundary.d.ts

@@ -22,15 +22,14 @@ export interface AuthBoundaryProps {
     children: React.ReactNode;
 }
 /**
- * Authentication boundary component that conditionally renders content based on
- * the user's authentication status and SDK readiness.
+ * Authentication boundary component that renders content based on authentication state.
  *
- * This component simplifies protecting routes and content based on authentication state.
- * It handles three main states:
- * 1. Loading - SDK is initializing
- * 2. Error - SDK encountered an initialization error
- * 3. Unauthenticated - User is not logged in
- * 4. Authenticated - User is logged in and SDK is ready
+ * This component simplifies protecting routes and content based on authentication state and
+ * handles four distinct scenarios:
+ * 1. **Loading** – the SDK is still initialising.
+ * 2. **Error** – the SDK encountered an initialisation error.
+ * 3. **Unauthenticated** – the user is not logged in.
+ * 4. **Authenticated** – the user is logged in and the SDK is ready.
  *
  * @example
  * ```tsx

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

@@ -1,10 +1,7 @@
 /**
- * Openfort React Native SDK Components
+ * Openfort React Native SDK components.
  *
- * This module provides React components and hooks for building user interfaces
- * that integrate with the Openfort platform in React Native applications.
- *
- * The components are organized into the following categories:
- * - Authentication boundaries and guards
+ * This barrel currently exposes the authentication boundary component used to gate
+ * access to protected UI based on SDK readiness and user state.
  */
 export { AuthBoundary } from './AuthBoundary';

package/dist/types/constants/config.d.ts

@@ -1,9 +1,9 @@
 /**
- * SDK package information
+ * Static metadata describing the React Native SDK package.
  */
 export declare const SDK_INFO: {
     readonly name: "@openfort/react-native";
-    readonly version: "0.1.8";
+    readonly version: "0.1.9";
     readonly description: "React Native client for Openfort";
     readonly homepage: "https://openfort.io/docs";
 };

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

@@ -1,24 +1,40 @@
 import { Openfort as OpenfortClient, OpenfortSDKConfiguration } from '@openfort/openfort-js';
 /**
- * Creates an instance of the Openfort client configured for Expo/React Native
+ * Creates an {@link OpenfortClient} configured for Expo and React Native environments.
  *
- * @param options Configuration options for the Openfort client
- * @returns Configured Openfort client instance
+ * The helper ensures Expo-specific utilities like secure storage and the crypto digest
+ * implementation are wired into the underlying Openfort SDK.
+ *
+ * @param options - {@link OpenfortSDKConfiguration} containing the base configuration,
+ * overrides, and optional Shield configuration.
+ * @returns A fully configured {@link OpenfortClient} instance ready for React Native apps.
  *
  * @example
+ * ```ts
  * const client = createOpenfortClient({
+ *   baseConfiguration: new OpenfortConfiguration({ publishableKey }),
+ *   overrides: { logLevel: 'debug' },
+ *   shieldConfiguration: new ShieldConfiguration({ shieldPublishableKey })
  * });
  *
- * const token = await client.getAccessToken();
+ * const accessToken = await client.getAccessToken();
+ * ```
  */
 export declare function createOpenfortClient({ baseConfiguration, overrides, shieldConfiguration, }: OpenfortSDKConfiguration): OpenfortClient;
 /**
- * Gets or creates the default Openfort client instance
+ * Retrieves the lazily initialised default {@link OpenfortClient} instance.
+ *
+ * @param options - Optional configuration used to create the client when it does not yet exist.
+ * @returns The cached {@link OpenfortClient} instance.
+ * @throws {Error} When the client has not been initialised and no configuration was provided.
  * @internal
  */
 export declare function getDefaultClient(options?: OpenfortSDKConfiguration): OpenfortClient;
 /**
- * Sets the default Openfort client instance
+ * Overrides the global default {@link OpenfortClient} instance that will be returned by
+ * {@link getDefaultClient}.
+ *
+ * @param client - The client instance to set as the default.
  * @internal
  */
 export declare function setDefaultClient(client: OpenfortClient): void;

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

@@ -3,59 +3,96 @@ import type { Openfort as OpenfortClient, EmbeddedState } from '@openfort/openfo
 import { OAuthFlowState, PasswordFlowState, RecoveryFlowState, SiweFlowState } from '../types';
 import type { Chain, EmbeddedWalletConfiguration } from './provider';
 /**
- * Core Openfort context interface containing all SDK state and methods
+ * Core Openfort context interface describing the state and methods exposed through {@link OpenfortContext}.
  */
 export interface OpenfortContextValue {
-    /** The Openfort client instance */
+    /** The Openfort client instance. */
     client: OpenfortClient;
-    /** The current authenticated user, or null when unauthenticated */
+    /** The current authenticated user, or null when unauthenticated. */
     user: import('@openfort/openfort-js').AuthPlayerResponse | null;
-    /** Whether the SDK has initialized and is ready for use */
+    /** Whether the SDK has initialized and is ready for use. */
     isReady: boolean;
-    /** Any error encountered during SDK initialization */
+    /** Any error encountered during SDK initialization. */
     error: Error | null;
-    /** Supported chains configuration */
+    /** Supported chains configuration. */
     supportedChains?: [Chain, ...Chain[]];
-    /** Embedded wallet configuration for Shield integration */
+    /** Embedded wallet configuration for Shield integration. */
     walletConfig?: EmbeddedWalletConfiguration;
-    /** Current embedded wallet state */
+    /** Current embedded wallet state. */
     embeddedState: EmbeddedState;
-    /** Password (email/SMS) authentication flow state */
+    /** Password (email/SMS) authentication flow state. */
     passwordState: PasswordFlowState;
-    /** OAuth authentication flow state */
+    /** OAuth authentication flow state. */
     oAuthState: OAuthFlowState;
-    /** Sign-in with Ethereum flow state */
+    /** Sign-in with Ethereum flow state. */
     siweState: SiweFlowState;
-    /** Recovery flow state */
+    /** Recovery flow state. */
     recoveryFlowState: RecoveryFlowState;
     setPasswordState: React.Dispatch<React.SetStateAction<PasswordFlowState>>;
     setOAuthState: React.Dispatch<React.SetStateAction<OAuthFlowState>>;
     setSiweState: React.Dispatch<React.SetStateAction<SiweFlowState>>;
     setRecoveryFlowState: React.Dispatch<React.SetStateAction<RecoveryFlowState>>;
-    /** Logs the current user out and clears any stored tokens */
+    /** Logs the current user out and clears any stored tokens. */
     logout: () => Promise<void>;
-    /** Gets the current authenticated user's access token */
+    /** Gets the current authenticated user's access token. */
     getAccessToken: () => Promise<string | null>;
-    /** @internal Refreshes user state after authentication changes */
+    /** @internal Refreshes user state after authentication changes. */
     _internal: {
         refreshUserState: (user?: import('@openfort/openfort-js').AuthPlayerResponse) => Promise<import('@openfort/openfort-js').AuthPlayerResponse | null>;
     };
 }
 /**
- * React context for sharing Openfort SDK state throughout the component tree
+ * React context for sharing Openfort SDK state throughout the component tree.
  */
 export declare const OpenfortContext: React.Context<OpenfortContextValue | null>;
 /**
  * Hook to access the Openfort context
- * Throws an error if used outside of a OpenfortProvider
+ *
+ * This hook provides access to the Openfort SDK context including client instance,
+ * user state, and authentication methods. Must be used within an OpenfortProvider.
+ *
+ * @returns The {@link OpenfortContextValue} from the nearest provider
+ * @throws {Error} When used outside an {@link OpenfortProvider}
+ *
+ * @example
+ * ```tsx
+ * const { client, user, isReady, logout } = useOpenfortContext();
+ *
+ * // Check if SDK is ready
+ * if (isReady && user) {
+ *   console.log('User authenticated:', user.id);
+ *
+ *   // Access client methods
+ *   const token = await client.getAccessToken();
+ * }
+ * ```
  */
 export declare function useOpenfortContext(): OpenfortContextValue;
 /**
  * Hook to safely access the Openfort context
- * Returns null if used outside of a OpenfortProvider
+ *
+ * This hook provides safe access to the Openfort SDK context without throwing errors.
+ * Returns null when used outside of an OpenfortProvider instead of throwing.
+ *
+ * @returns The {@link OpenfortContextValue} when available, otherwise `null`
+ *
+ * @example
+ * ```tsx
+ * const context = useOpenfortContextSafe();
+ *
+ * if (context) {
+ *   const { user, isReady } = context;
+ *   console.log('Context available:', { user: !!user, isReady });
+ * } else {
+ *   console.log('No Openfort context found');
+ * }
+ * ```
  */
 export declare function useOpenfortContextSafe(): OpenfortContextValue | null;
 /**
- * Type guard to check if a value is a valid OpenfortContextValue
+ * Runtime type guard that checks whether a value satisfies {@link OpenfortContextValue}.
+ *
+ * @param value - Value to check.
+ * @returns `true` when the value matches the {@link OpenfortContextValue} shape.
  */
 export declare function isOpenfortContextValue(value: unknown): value is OpenfortContextValue;