@openfort/react-native 0.1.9 → 0.1.11

package/dist/components/AuthBoundary.js

@@ -1,15 +1,14 @@
 import React from 'react';
 import { useOpenfort } from '../hooks/core/useOpenfort';
 /**
- * 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/components/index.js

@@ -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/constants/config.js

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

package/dist/core/client.js

@@ -4,16 +4,25 @@ import { applicationId } from 'expo-application';
 import { SecureStorageAdapter, createNormalizedStorage } from './storage';
 import { logger } from '../lib/logger';
 /**
- * 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 function createOpenfortClient({ baseConfiguration, overrides, shieldConfiguration, }) {
     const nativeAppId = getNativeApplicationId();
@@ -43,8 +52,11 @@ export function createOpenfortClient({ baseConfiguration, overrides, shieldConfi
     });
 }
 /**
- * Gets the native application identifier from Expo
- * Throws an error if the identifier cannot be determined
+ * Resolves the native application identifier from the Expo runtime.
+ *
+ * @returns The native bundle identifier reported by Expo.
+ * @throws {Error} Thrown when the identifier cannot be determined, typically because the
+ * `expo-application` package is not installed or the native bundle identifier is missing.
  */
 function getNativeApplicationId() {
     if (typeof applicationId !== 'string') {
@@ -53,12 +65,18 @@ function getNativeApplicationId() {
     return applicationId;
 }
 /**
- * Default Openfort client instance - should only be used internally
- * Applications should create their own client instances using createOpenfortClient
+ * Default {@link OpenfortClient} instance used when an application does not supply its own.
+ *
+ * Applications should generally manage their own instance via {@link createOpenfortClient}
+ * instead of relying on this singleton.
  */
 let defaultClient = null;
 /**
- * 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 function getDefaultClient(options) {
@@ -71,7 +89,10 @@ export function getDefaultClient(options) {
     return defaultClient;
 }
 /**
- * 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 function setDefaultClient(client) {

package/dist/core/context.js

@@ -1,11 +1,29 @@
 import React from 'react';
 /**
- * React context for sharing Openfort SDK state throughout the component tree
+ * React context for sharing Openfort SDK state throughout the component tree.
  */
 export const OpenfortContext = React.createContext(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 function useOpenfortContext() {
     const context = React.useContext(OpenfortContext);
@@ -17,13 +35,32 @@ export function useOpenfortContext() {
 }
 /**
  * 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 function useOpenfortContextSafe() {
     return React.useContext(OpenfortContext);
 }
 /**
- * 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 function isOpenfortContextValue(value) {
     return (typeof value === 'object' &&

package/dist/core/provider.js

@@ -5,8 +5,12 @@ import { createOpenfortClient, setDefaultClient } from './client';
 import { EmbeddedWalletWebView, WebViewUtils } from '../native';
 import { logger, getEmbeddedStateName } from '../lib/logger';
 /**
- * Starts polling the embedded wallet state and calls onChange only when the
- * state actually changes. Returns a cleanup function to stop polling.
+ * Starts polling the embedded wallet state and invokes the callback when transitions occur.
+ *
+ * @param client - The Openfort client to query for embedded wallet state.
+ * @param onChange - Callback invoked whenever the state changes.
+ * @param intervalMs - Polling interval in milliseconds. Defaults to 1000ms.
+ * @returns A function that stops polling when called.
  */
 function startEmbeddedStatePolling(client, onChange, intervalMs = 1000) {
     let lastState = null;
@@ -34,8 +38,35 @@ function startEmbeddedStatePolling(client, onChange, intervalMs = 1000) {
     };
 }
 /**
- * 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 const OpenfortProvider = ({ children, publishableKey, customAuth, supportedChains, walletConfig, overrides, thirdPartyAuth, verbose = false, }) => {
     // Prevent multiple OpenfortProvider instances

package/dist/core/storage.js

@@ -16,8 +16,9 @@ var StorageKeys;
     StorageKeys["PKCE_VERIFIER"] = "openfort.pkce_verifier";
 })(StorageKeys || (StorageKeys = {}));
 /**
- * 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 const SecureStorageAdapter = {
     async get(key) {
@@ -77,15 +78,19 @@ export const SecureStorageAdapter = {
     },
 };
 /**
- * Normalizes storage keys by replacing colons with hyphens
- * to ensure compatibility with expo-secure-store
+ * Normalises an Openfort storage key for use with Expo Secure Store.
+ *
+ * @param key - The key provided by the Openfort SDK.
+ * @returns A key that is safe to use with Expo Secure Store.
  */
 function normalizeKey(key) {
     return key.replaceAll(':', '-');
 }
 /**
- * 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 function createNormalizedStorage(customStorage) {
     const baseStorage = customStorage || SecureStorageAdapter;
@@ -119,7 +124,12 @@ export function createNormalizedStorage(customStorage) {
     };
 }
 /**
- * Converts an unknown key (likely from the Openfort SDK) to our StorageKeys enum
+ * Converts a key provided by the Openfort SDK to the local {@link StorageKeys} enum.
+ *
+ * @param key - Value provided by the Openfort SDK. Can be a string or an enum-like
+ * object.
+ * @returns The matching {@link StorageKeys} value.
+ * @throws {Error} When the key cannot be mapped to one of the known storage keys.
  */
 function keyToStorageKeys(key) {
     if (typeof key === 'string') {

package/dist/hooks/auth/index.js

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

package/dist/hooks/auth/useCreateWalletPostAuth.js

@@ -1,5 +1,13 @@
 import { useCallback } from "react";
-// this hook is used to create a wallet after the user has authenticated
+/**
+ * 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 const useCreateWalletPostAuth = () => {
     // This would connect to the wallet and set it as active
     // eslint-disable-next-line no-empty-pattern

package/dist/hooks/auth/useEmailAuth.js

@@ -11,6 +11,32 @@ const mapStatus = (status) => {
         error: "error" in status ? status.error : null,
     };
 };
+/**
+ * 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 const useEmailAuth = (hookOptions = {}) => {
     const { client, setPasswordState, _internal, passwordState } = useOpenfortContext();
     const signInEmail = useCallback(async (options) => {

package/dist/hooks/auth/useGuestAuth.js

@@ -3,6 +3,27 @@ import { useOpenfortContext } from '../../core/context';
 import { onError, onSuccess } from '../../lib/hookConsistency';
 import { mapStatus } from '../../types/baseFlowState';
 import { OpenfortError, OpenfortErrorType } from '../../types/openfortError';
+/**
+ * Hook for creating guest accounts.
+ *
+ * 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 hookOptions - Configuration options including success and error callbacks.
+ * @returns Current guest authentication helpers with flow status indicators.
+ *
+ * @example
+ * ```tsx
+ * const { signUpGuest, isLoading } = useGuestAuth({
+ *   onSuccess: ({ user }) => console.log('Guest account created:', user),
+ *   onError: ({ error }) => console.error('Failed to create guest account:', error),
+ * });
+ *
+ * if (!isLoading) {
+ *   await signUpGuest();
+ * }
+ * ```
+ */
 export const useGuestAuth = (hookOptions = {}) => {
     const { client, _internal } = useOpenfortContext();
     const { refreshUserState: updateUser } = _internal;

package/dist/hooks/auth/useOAuth.js

@@ -1,6 +1,3 @@
-/**
- * Hook for OAuth-based login functionality
- */
 import { OAuthProvider } from '@openfort/openfort-js';
 import { useCallback } from 'react';
 import { useOpenfortContext } from '../../core/context';
@@ -9,33 +6,30 @@ import { mapOAuthStatus } from "../../types/oauth";
 import { OpenfortError, OpenfortErrorType } from '../../types/openfortError';
 import { onError, onSuccess } from '../../lib/hookConsistency';
 /**
- * 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 const useOAuth = (hookOptions = {}) => {

package/dist/hooks/auth/useSignOut.js

@@ -4,6 +4,38 @@ import { onError, onSuccess } from "../../lib/hookConsistency";
 import { mapStatus } from "../../types/baseFlowState";
 import { OpenfortError, OpenfortErrorType } from "../../types/openfortError";
 import { useOpenfortClient } from "../core";
+/**
+ * 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 function useSignOut(hookOptions = {}) {
     const client = useOpenfortClient();
     const { _internal, user } = useOpenfortContext();

package/dist/hooks/auth/useWalletAuth.js

@@ -13,6 +13,31 @@ const mapStatus = (status) => {
         isSubmittingSignature: status.status === 'submitting-signature',
     };
 };
+/**
+ * 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 function useWalletAuth(hookOptions) {
     const { client, siweState, setSiweState, _internal } = useOpenfortContext();
     const generateSiweMessage = useCallback(async (args) => {

package/dist/hooks/core/index.js

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

package/dist/hooks/core/useOpenfort.js

@@ -1,41 +1,38 @@
-/**
- * Core Openfort hook for accessing SDK state and methods
- */
 import { useOpenfortContext } from '../../core/context';
 /**
- * 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>;
+ *   }
+ *
+ *   if (!user) {
+ *     return <Text>Please sign in</Text>;
+ *   }
  *
- * // User is authenticated
- * return (
- *   <div>
- *     <h1>Welcome, {user.id}!</h1>
- *     <button onClick={logout}>Logout</button>
- *   </div>
- * );
+ *   return (
+ *     <View>
+ *       <Text>{`Welcome, ${user.id}`}</Text>
+ *       <Button title="Log out" onPress={() => void logout()} />
+ *     </View>
+ *   );
+ * }
  * ```
  */
 export function useOpenfort() {

package/dist/hooks/core/useOpenfortClient.js

@@ -1,26 +1,21 @@
 import { useOpenfortContext } from '../../core/context';
 /**
- * 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();
+ * // Invoke a raw SDK method
+ * const token = await client.getAccessToken();
  *
- * // Access client configuration
- * console.log('App ID:', client.config.appId);
- *
- * // Check client status
- * if (client.isInitialized) {
- *   // Perform operations that require initialization
- * }
+ * // Access nested services
+ * await client.auth.logout();
  * ```
  */
 export function useOpenfortClient() {