@openfort/react-native 0.1.8 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/dist/components/AuthBoundary.js +7 -8
  2. package/dist/components/index.js +3 -6
  3. package/dist/constants/config.js +2 -2
  4. package/dist/core/client.js +31 -10
  5. package/dist/core/context.js +41 -4
  6. package/dist/core/provider.js +35 -4
  7. package/dist/core/storage.js +17 -7
  8. package/dist/hooks/auth/index.js +1 -1
  9. package/dist/hooks/auth/useCreateWalletPostAuth.js +9 -1
  10. package/dist/hooks/auth/useEmailAuth.js +26 -0
  11. package/dist/hooks/auth/useGuestAuth.js +21 -0
  12. package/dist/hooks/auth/useOAuth.js +15 -21
  13. package/dist/hooks/auth/useSignOut.js +32 -0
  14. package/dist/hooks/auth/useWalletAuth.js +25 -0
  15. package/dist/hooks/core/index.js +1 -1
  16. package/dist/hooks/core/useOpenfort.js +24 -27
  17. package/dist/hooks/core/useOpenfortClient.js +8 -13
  18. package/dist/hooks/core/useUser.js +28 -0
  19. package/dist/hooks/index.js +7 -6
  20. package/dist/hooks/wallet/index.js +1 -1
  21. package/dist/hooks/wallet/useWallet.js +27 -0
  22. package/dist/hooks/wallet/useWallets.js +44 -27
  23. package/dist/index.js +5 -6
  24. package/dist/lib/hookConsistency.js +42 -0
  25. package/dist/native/oauth.js +38 -1
  26. package/dist/native/storage.js +23 -8
  27. package/dist/types/components/AuthBoundary.d.ts +7 -8
  28. package/dist/types/components/index.d.ts +3 -6
  29. package/dist/types/constants/config.d.ts +2 -2
  30. package/dist/types/core/client.d.ts +22 -6
  31. package/dist/types/core/context.d.ts +56 -19
  32. package/dist/types/core/provider.d.ts +57 -30
  33. package/dist/types/core/storage.d.ts +7 -4
  34. package/dist/types/hooks/auth/index.d.ts +1 -1
  35. package/dist/types/hooks/auth/useCreateWalletPostAuth.d.ts +9 -0
  36. package/dist/types/hooks/auth/useEmailAuth.d.ts +26 -0
  37. package/dist/types/hooks/auth/useGuestAuth.d.ts +16 -18
  38. package/dist/types/hooks/auth/useOAuth.d.ts +15 -21
  39. package/dist/types/hooks/auth/useSignOut.d.ts +32 -0
  40. package/dist/types/hooks/auth/useWalletAuth.d.ts +25 -3
  41. package/dist/types/hooks/core/index.d.ts +1 -1
  42. package/dist/types/hooks/core/useOpenfort.d.ts +24 -24
  43. package/dist/types/hooks/core/useOpenfortClient.d.ts +8 -16
  44. package/dist/types/hooks/core/useUser.d.ts +28 -0
  45. package/dist/types/hooks/index.d.ts +7 -6
  46. package/dist/types/hooks/wallet/index.d.ts +1 -1
  47. package/dist/types/hooks/wallet/useWallet.d.ts +27 -0
  48. package/dist/types/hooks/wallet/useWallets.d.ts +24 -21
  49. package/dist/types/index.d.ts +5 -6
  50. package/dist/types/lib/hookConsistency.d.ts +42 -0
  51. package/dist/types/native/oauth.d.ts +38 -1
  52. package/dist/types/native/storage.d.ts +21 -9
  53. package/dist/types/predicates.js +20 -1
  54. package/dist/types/types/index.d.ts +8 -8
  55. package/dist/types/types/predicates.d.ts +55 -1
  56. package/package.json +2 -2
@@ -1,5 +1,33 @@
1
1
  import { EmbeddedState } from "@openfort/openfort-js";
2
2
  import { useOpenfortContext } from "../../core";
3
+ /**
4
+ * Hook for accessing current user state and authentication status
5
+ *
6
+ * This hook provides access to the current user's information and authentication state.
7
+ * It automatically updates when the user signs in, signs out, or their profile changes.
8
+ *
9
+ * @returns Current user data, authentication status, and access token getter
10
+ *
11
+ * @example
12
+ * ```tsx
13
+ * const { user, isAuthenticated, getAccessToken } = useUser();
14
+ *
15
+ * // Check if user is authenticated
16
+ * if (isAuthenticated && user) {
17
+ * console.log('Authenticated user:', user.id);
18
+ * console.log('User email:', user.email);
19
+ *
20
+ * // Get access token for API calls
21
+ * const token = await getAccessToken();
22
+ * console.log('Access token available:', !!token);
23
+ * } else {
24
+ * console.log('User not authenticated');
25
+ * }
26
+ *
27
+ * // Use in conditional rendering
28
+ * return isAuthenticated ? <Dashboard user={user} /> : <LoginForm />;
29
+ * ```
30
+ */
3
31
  export function useUser() {
4
32
  const { user, embeddedState, getAccessToken } = useOpenfortContext();
5
33
  return {
@@ -1,11 +1,12 @@
1
1
  /**
2
- * Openfort React Native SDK Hooks
2
+ * Openfort React Native SDK hooks.
3
3
  *
4
- * This module provides a comprehensive set of React hooks for integrating
5
- * with the Openfort platform in React Native applications.
6
- *
7
- * The hooks are organized into the following categories:
8
- * - Core: Core SDK functionality hooks
4
+ * This barrel re-exports all hook collections that ship with the SDK so consumers can
5
+ * import from `@openfort/react-native/hooks`. The hooks are organised into the
6
+ * following sub-modules:
7
+ * - Core: Lifecycle/state helpers (e.g. `useOpenfort`)
8
+ * - Auth: Authentication helpers (email, OAuth, SIWE, guest)
9
+ * - Wallet: Embedded wallet management utilities
9
10
  */
10
11
  // Re-export all core hooks
11
12
  export * from './core';
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Wallet hooks index
2
+ * Wallet hooks index.
3
3
  *
4
4
  * This module re-exports all wallet-related hooks for convenient importing.
5
5
  */
@@ -1,4 +1,31 @@
1
1
  import { useWallets } from "./useWallets";
2
+ /**
3
+ * Hook for accessing the currently active embedded wallet
4
+ *
5
+ * This hook provides access to the currently active embedded wallet from the wallet collection.
6
+ * It automatically updates when the active wallet changes through other wallet operations.
7
+ *
8
+ * @returns The active embedded wallet when available, otherwise `null`
9
+ *
10
+ * @example
11
+ * ```tsx
12
+ * const activeWallet = useWallet();
13
+ *
14
+ * // Check if wallet is available
15
+ * if (activeWallet) {
16
+ * console.log('Active wallet address:', activeWallet.address);
17
+ *
18
+ * // Get provider for transactions
19
+ * const provider = await activeWallet.getProvider();
20
+ *
21
+ * // Use wallet for operations
22
+ * console.log('Wallet chain type:', activeWallet.chainType);
23
+ * console.log('Is connecting:', activeWallet.isConnecting);
24
+ * } else {
25
+ * console.log('No active wallet available');
26
+ * }
27
+ * ```
28
+ */
2
29
  export function useWallet() {
3
30
  const { activeWallet } = useWallets();
4
31
  return activeWallet;
@@ -1,6 +1,3 @@
1
- /**
2
- * Hook for embedded Ethereum wallet functionality
3
- */
4
1
  import { AccountTypeEnum, ChainTypeEnum, EmbeddedState, RecoveryMethod } from '@openfort/openfort-js';
5
2
  import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
6
3
  import { useOpenfortContext } from '../../core/context';
@@ -17,31 +14,36 @@ const mapWalletStatus = (status) => {
17
14
  };
18
15
  };
19
16
  /**
20
- * Hook for interacting with embedded Ethereum wallets
17
+ * Hook for interacting with embedded wallets
21
18
  *
22
- * This hook manages embedded Ethereum wallets based on the user's state from the provider.
23
- * Wallet state is determined by polling in the provider, not by local state management.
19
+ * This hook manages embedded wallets based on the user's state from the provider. Wallet state is determined by
20
+ * polling in the provider, not by local state management. It provides wallet creation, recovery, and management capabilities.
24
21
  *
25
- * @param props - Optional configuration with callback functions
26
- * @returns Current embedded Ethereum wallet state with actions
22
+ * @param hookOptions - Optional configuration with callback functions and chain ID settings
23
+ * @returns Current embedded wallet state with actions and wallet collection
27
24
  *
28
25
  * @example
29
26
  * ```tsx
30
- * const ethereumWallet = useEmbeddedEthereumWallet({
31
- * onCreateWalletSuccess: (provider) => console.log('Ethereum wallet created:', provider),
32
- * onCreateWalletError: (error) => console.error('Ethereum wallet creation failed:', error),
27
+ * const { wallets, activeWallet, createWallet, setActiveWallet, isCreating } = useWallets({
28
+ * onSuccess: ({ wallet }) => console.log('Wallet operation successful:', wallet?.address),
29
+ * onError: ({ error }) => console.error('Wallet operation failed:', error?.message),
30
+ * chainId: 1, // Ethereum mainnet
33
31
  * });
34
32
  *
35
- * // Check wallet status and create if needed
36
- * if (ethereumWallet.status === 'disconnected') {
37
- * await ethereumWallet.create(); // Uses default chain
38
- * // Or with specific chain: await ethereumWallet.create({ chainId: 1 });
33
+ * // Create a new wallet if none exist
34
+ * if (wallets.length === 0 && !isCreating) {
35
+ * await createWallet({ chainId: 1 });
36
+ * }
37
+ *
38
+ * // Use existing wallets
39
+ * if (wallets.length > 0 && !activeWallet) {
40
+ * await setActiveWallet({ address: wallets[0].address });
39
41
  * }
40
42
  *
41
- * // Use connected wallets
42
- * if (ethereumWallet.status === 'connected' && ethereumWallet.wallets.length > 0) {
43
- * const provider = await ethereumWallet.wallets[0].getProvider();
44
- * // Use provider for Ethereum transactions
43
+ * // Access active wallet
44
+ * if (activeWallet) {
45
+ * const provider = await activeWallet.getProvider();
46
+ * // Use provider for transactions
45
47
  * }
46
48
  * ```
47
49
  */
@@ -67,7 +69,7 @@ export function useWallets(hookOptions = {}) {
67
69
  isActive: true,
68
70
  isConnecting: false,
69
71
  getProvider: async () => {
70
- return await client.embeddedWallet.getEthereumProvider({ announceProvider: false });
72
+ return await getEthereumProvider();
71
73
  },
72
74
  };
73
75
  }, [activeWalletId, embeddedAccounts, client.embeddedWallet]);
@@ -152,7 +154,7 @@ export function useWallets(hookOptions = {}) {
152
154
  isActive: true,
153
155
  isConnecting: false,
154
156
  getProvider: async () => {
155
- return await client.embeddedWallet.getEthereumProvider({ announceProvider: false });
157
+ return await getEthereumProvider();
156
158
  },
157
159
  };
158
160
  recoverPromiseRef.current = null;
@@ -201,6 +203,24 @@ export function useWallets(hookOptions = {}) {
201
203
  useEffect(() => {
202
204
  fetchEmbeddedWallets();
203
205
  }, [fetchEmbeddedWallets]);
206
+ const getEthereumProvider = useCallback(async () => {
207
+ const resolvePolicy = () => {
208
+ const ethereumProviderPolicyId = walletConfig?.ethereumProviderPolicyId;
209
+ if (!ethereumProviderPolicyId)
210
+ return undefined;
211
+ if (typeof ethereumProviderPolicyId === "string") {
212
+ return ethereumProviderPolicyId;
213
+ }
214
+ if (!hookOptions.chainId)
215
+ return undefined;
216
+ const policy = ethereumProviderPolicyId[hookOptions.chainId];
217
+ if (!policy) {
218
+ return undefined;
219
+ }
220
+ return policy;
221
+ };
222
+ return await client.embeddedWallet.getEthereumProvider({ announceProvider: false, policy: resolvePolicy() });
223
+ }, [client.embeddedWallet]);
204
224
  useEffect(() => {
205
225
  (async () => {
206
226
  try {
@@ -228,7 +248,7 @@ export function useWallets(hookOptions = {}) {
228
248
  isActive: activeWalletId === account.id,
229
249
  isConnecting: status.status === "connecting" && status.address === account.address,
230
250
  getProvider: async () => {
231
- return await client.embeddedWallet.getEthereumProvider({ announceProvider: false });
251
+ return await getEthereumProvider();
232
252
  },
233
253
  }))), [embeddedAccounts, activeWalletId, status.status === "connecting", client.embeddedWallet]);
234
254
  const create = useCallback(async (options) => {
@@ -279,10 +299,7 @@ export function useWallets(hookOptions = {}) {
279
299
  });
280
300
  logger.info('Embedded wallet configured with shield authentication');
281
301
  // Get the Ethereum provider
282
- const provider = await client.embeddedWallet.getEthereumProvider({
283
- announceProvider: false,
284
- ...(options?.policyId && { policy: options.policyId }),
285
- });
302
+ const provider = await getEthereumProvider();
286
303
  // Refetch the list of wallets to ensure the state is up to date
287
304
  await fetchEmbeddedWallets();
288
305
  setActiveWalletId(embeddedAccount.id);
@@ -343,7 +360,7 @@ export function useWallets(hookOptions = {}) {
343
360
  isActive: true,
344
361
  isConnecting: false,
345
362
  getProvider: async () => {
346
- return await client.embeddedWallet.getEthereumProvider({ announceProvider: false });
363
+ return await getEthereumProvider();
347
364
  }
348
365
  }
349
366
  }
package/dist/index.js CHANGED
@@ -1,12 +1,11 @@
1
1
  /**
2
- * Openfort React Native SDK
2
+ * @packageDocumentation
3
3
  *
4
- * A comprehensive React Native SDK for integrating with the Openfort platform.
5
- * This SDK provides authentication, embedded wallets, session management, and UI components
6
- * for building decentralized applications on React Native.
4
+ * Entry point for the Openfort React Native SDK.
7
5
  *
8
- * @author Openfort
9
- * @version 0.1.8
6
+ * This package re-exports the core SDK functionality, hooks, components and native helpers
7
+ * required to integrate Openfort authentication and embedded wallets into React Native and
8
+ * Expo applications.
10
9
  */
11
10
  // Re-export commonly used types from @openfort/openfort-js
12
11
  export { OpenfortError, RecoveryMethod, Openfort as OpenfortClient, OpenfortConfiguration, ShieldConfiguration, EmbeddedState, } from '@openfort/openfort-js';
@@ -1,3 +1,22 @@
1
+ /**
2
+ * Handles successful hook operation callbacks
3
+ *
4
+ * This utility function invokes success and settled callbacks from hook options,
5
+ * ensuring consistent callback execution across all hooks in the SDK.
6
+ *
7
+ * @param params - Object containing hook options and success data
8
+ * @returns The success data that was passed in
9
+ *
10
+ * @example
11
+ * ```tsx
12
+ * const result = await someAsyncOperation();
13
+ * return onSuccess({
14
+ * hookOptions,
15
+ * options,
16
+ * data: { user: result.user },
17
+ * });
18
+ * ```
19
+ */
1
20
  export const onSuccess = ({ hookOptions, options, data, }) => {
2
21
  hookOptions?.onSuccess?.(data);
3
22
  hookOptions?.onSettled?.(data, null);
@@ -5,6 +24,29 @@ export const onSuccess = ({ hookOptions, options, data, }) => {
5
24
  options?.onSettled?.(data, null);
6
25
  return data;
7
26
  };
27
+ /**
28
+ * Handles failed hook operation callbacks
29
+ *
30
+ * This utility function invokes error and settled callbacks from hook options,
31
+ * and optionally throws the error if throwOnError is configured.
32
+ *
33
+ * @param params - Object containing hook options and error information
34
+ * @returns Object containing the error, or throws if throwOnError is enabled
35
+ *
36
+ * @example
37
+ * ```tsx
38
+ * try {
39
+ * await someAsyncOperation();
40
+ * } catch (e) {
41
+ * const error = new OpenfortError('Operation failed', OpenfortErrorType.GENERIC);
42
+ * return onError({
43
+ * hookOptions,
44
+ * options,
45
+ * error,
46
+ * });
47
+ * }
48
+ * ```
49
+ */
8
50
  export const onError = ({ hookOptions, options, error, }) => {
9
51
  hookOptions?.onError?.(error);
10
52
  hookOptions?.onSettled?.(null, error);
@@ -90,7 +90,25 @@ export async function isAppleSignInAvailable() {
90
90
  }
91
91
  }
92
92
  /**
93
- * Parses OAuth parameters from a URL
93
+ * Parses OAuth parameters from a redirect URL
94
+ *
95
+ * This function extracts OAuth authentication parameters from a callback URL after
96
+ * a successful or failed OAuth flow. It safely handles URL parsing errors.
97
+ *
98
+ * @param url - The OAuth redirect URL containing query parameters
99
+ * @returns Object containing parsed OAuth parameters including tokens and error information
100
+ *
101
+ * @example
102
+ * ```tsx
103
+ * const redirectUrl = 'myapp://oauth/callback?access_token=abc123&player_id=player_123';
104
+ * const result = parseOAuthUrl(redirectUrl);
105
+ *
106
+ * if (result.access_token && result.player_id) {
107
+ * console.log('OAuth successful:', result.player_id);
108
+ * } else if (result.error) {
109
+ * console.error('OAuth failed:', result.errorDescription);
110
+ * }
111
+ * ```
94
112
  */
95
113
  export function parseOAuthUrl(url) {
96
114
  try {
@@ -111,6 +129,25 @@ export function parseOAuthUrl(url) {
111
129
  }
112
130
  /**
113
131
  * Creates a redirect URI for OAuth flows
132
+ *
133
+ * This function generates a deep link URL that OAuth providers can redirect back to
134
+ * after authentication. The URL follows the app's custom URL scheme.
135
+ *
136
+ * @param path - The path component for the redirect URI, defaults to '/'
137
+ * @returns A complete redirect URI that can be used in OAuth flows
138
+ *
139
+ * @example
140
+ * ```tsx
141
+ * // Create default OAuth callback URI
142
+ * const callbackUri = createOAuthRedirectUri('/oauth/callback');
143
+ * console.log(callbackUri); // 'myapp://oauth/callback'
144
+ *
145
+ * // Use in OAuth configuration
146
+ * const oauthConfig = {
147
+ * redirectUri: createOAuthRedirectUri('/auth/success'),
148
+ * provider: 'google',
149
+ * };
150
+ * ```
114
151
  */
115
152
  export function createOAuthRedirectUri(path = '/') {
116
153
  return Linking.createURL(path);
@@ -3,7 +3,10 @@ import * as SecureStore from 'expo-secure-store';
3
3
  import { Platform } from 'react-native';
4
4
  import { logger } from '../lib/logger';
5
5
  /**
6
- * Checks if a message is a secure storage related message
6
+ * Checks if the provided value is a secure storage related message.
7
+ *
8
+ * @param message - Incoming message payload.
9
+ * @returns `true` when the payload matches the {@link SecureStorageMessage} structure.
7
10
  */
8
11
  export function isSecureStorageMessage(message) {
9
12
  if (typeof message !== 'object' ||
@@ -20,7 +23,11 @@ export function isSecureStorageMessage(message) {
20
23
  return message.event.startsWith('app:secure-storage:');
21
24
  }
22
25
  /**
23
- * Handles secure storage operations from WebView messages
26
+ * Handles secure storage operations initiated from WebView messages.
27
+ *
28
+ * @param message - Parsed WebView message describing the desired storage action.
29
+ * @returns The response payload that should be sent back to the WebView.
30
+ * @throws {Error} When the message event is unknown.
24
31
  */
25
32
  export async function handleSecureStorageMessage(message) {
26
33
  logger.info('Handling secure storage message', message);
@@ -131,23 +138,26 @@ export async function handleSecureStorageMessage(message) {
131
138
  }
132
139
  }
133
140
  /**
134
- * Normalizes storage keys for compatibility with secure storage
141
+ * Normalises storage keys for compatibility with Expo Secure Store.
142
+ *
143
+ * @param key - Original storage key.
144
+ * @returns The normalised key string.
135
145
  */
136
146
  function normalizeKey(key) {
137
147
  return key.replaceAll(':', '-');
138
148
  }
139
149
  /**
140
- * Native storage utilities for platform-specific operations
150
+ * Native storage utilities for platform-specific operations.
141
151
  */
142
152
  export const NativeStorageUtils = {
143
153
  /**
144
- * Checks if secure storage is available on the current platform
154
+ * Checks if secure storage is available on the current platform.
145
155
  */
146
156
  isAvailable() {
147
157
  return Platform.OS === 'ios' || Platform.OS === 'android';
148
158
  },
149
159
  /**
150
- * Gets the platform-specific storage options
160
+ * Gets the platform-specific storage options.
151
161
  */
152
162
  getStorageOptions() {
153
163
  return {
@@ -155,7 +165,10 @@ export const NativeStorageUtils = {
155
165
  };
156
166
  },
157
167
  /**
158
- * Safely checks if a key exists in secure storage
168
+ * Safely checks if a key exists in secure storage.
169
+ *
170
+ * @param key - Storage key to look up.
171
+ * @returns `true` if the key is present, otherwise `false`.
159
172
  */
160
173
  async keyExists(key) {
161
174
  try {
@@ -167,7 +180,9 @@ export const NativeStorageUtils = {
167
180
  }
168
181
  },
169
182
  /**
170
- * Gets all available storage information
183
+ * Gets diagnostic information about the native storage capabilities.
184
+ *
185
+ * @returns Platform availability information and keychain accessibility value.
171
186
  */
172
187
  async getStorageInfo() {
173
188
  return {
@@ -22,15 +22,14 @@ export interface AuthBoundaryProps {
22
22
  children: React.ReactNode;
23
23
  }
24
24
  /**
25
- * Authentication boundary component that conditionally renders content based on
26
- * the user's authentication status and SDK readiness.
25
+ * Authentication boundary component that renders content based on authentication state.
27
26
  *
28
- * This component simplifies protecting routes and content based on authentication state.
29
- * It handles three main states:
30
- * 1. Loading - SDK is initializing
31
- * 2. Error - SDK encountered an initialization error
32
- * 3. Unauthenticated - User is not logged in
33
- * 4. Authenticated - User is logged in and SDK is ready
27
+ * This component simplifies protecting routes and content based on authentication state and
28
+ * handles four distinct scenarios:
29
+ * 1. **Loading** the SDK is still initialising.
30
+ * 2. **Error** the SDK encountered an initialisation error.
31
+ * 3. **Unauthenticated** the user is not logged in.
32
+ * 4. **Authenticated** the user is logged in and the SDK is ready.
34
33
  *
35
34
  * @example
36
35
  * ```tsx
@@ -1,10 +1,7 @@
1
1
  /**
2
- * Openfort React Native SDK Components
2
+ * Openfort React Native SDK components.
3
3
  *
4
- * This module provides React components and hooks for building user interfaces
5
- * that integrate with the Openfort platform in React Native applications.
6
- *
7
- * The components are organized into the following categories:
8
- * - Authentication boundaries and guards
4
+ * This barrel currently exposes the authentication boundary component used to gate
5
+ * access to protected UI based on SDK readiness and user state.
9
6
  */
10
7
  export { AuthBoundary } from './AuthBoundary';
@@ -1,9 +1,9 @@
1
1
  /**
2
- * SDK package information
2
+ * Static metadata describing the React Native SDK package.
3
3
  */
4
4
  export declare const SDK_INFO: {
5
5
  readonly name: "@openfort/react-native";
6
- readonly version: "0.1.8";
6
+ readonly version: "0.1.9";
7
7
  readonly description: "React Native client for Openfort";
8
8
  readonly homepage: "https://openfort.io/docs";
9
9
  };
@@ -1,24 +1,40 @@
1
1
  import { Openfort as OpenfortClient, OpenfortSDKConfiguration } from '@openfort/openfort-js';
2
2
  /**
3
- * Creates an instance of the Openfort client configured for Expo/React Native
3
+ * Creates an {@link OpenfortClient} configured for Expo and React Native environments.
4
4
  *
5
- * @param options Configuration options for the Openfort client
6
- * @returns Configured Openfort client instance
5
+ * The helper ensures Expo-specific utilities like secure storage and the crypto digest
6
+ * implementation are wired into the underlying Openfort SDK.
7
+ *
8
+ * @param options - {@link OpenfortSDKConfiguration} containing the base configuration,
9
+ * overrides, and optional Shield configuration.
10
+ * @returns A fully configured {@link OpenfortClient} instance ready for React Native apps.
7
11
  *
8
12
  * @example
13
+ * ```ts
9
14
  * const client = createOpenfortClient({
15
+ * baseConfiguration: new OpenfortConfiguration({ publishableKey }),
16
+ * overrides: { logLevel: 'debug' },
17
+ * shieldConfiguration: new ShieldConfiguration({ shieldPublishableKey })
10
18
  * });
11
19
  *
12
- * const token = await client.getAccessToken();
20
+ * const accessToken = await client.getAccessToken();
21
+ * ```
13
22
  */
14
23
  export declare function createOpenfortClient({ baseConfiguration, overrides, shieldConfiguration, }: OpenfortSDKConfiguration): OpenfortClient;
15
24
  /**
16
- * Gets or creates the default Openfort client instance
25
+ * Retrieves the lazily initialised default {@link OpenfortClient} instance.
26
+ *
27
+ * @param options - Optional configuration used to create the client when it does not yet exist.
28
+ * @returns The cached {@link OpenfortClient} instance.
29
+ * @throws {Error} When the client has not been initialised and no configuration was provided.
17
30
  * @internal
18
31
  */
19
32
  export declare function getDefaultClient(options?: OpenfortSDKConfiguration): OpenfortClient;
20
33
  /**
21
- * Sets the default Openfort client instance
34
+ * Overrides the global default {@link OpenfortClient} instance that will be returned by
35
+ * {@link getDefaultClient}.
36
+ *
37
+ * @param client - The client instance to set as the default.
22
38
  * @internal
23
39
  */
24
40
  export declare function setDefaultClient(client: OpenfortClient): void;
@@ -3,59 +3,96 @@ import type { Openfort as OpenfortClient, EmbeddedState } from '@openfort/openfo
3
3
  import { OAuthFlowState, PasswordFlowState, RecoveryFlowState, SiweFlowState } from '../types';
4
4
  import type { Chain, EmbeddedWalletConfiguration } from './provider';
5
5
  /**
6
- * Core Openfort context interface containing all SDK state and methods
6
+ * Core Openfort context interface describing the state and methods exposed through {@link OpenfortContext}.
7
7
  */
8
8
  export interface OpenfortContextValue {
9
- /** The Openfort client instance */
9
+ /** The Openfort client instance. */
10
10
  client: OpenfortClient;
11
- /** The current authenticated user, or null when unauthenticated */
11
+ /** The current authenticated user, or null when unauthenticated. */
12
12
  user: import('@openfort/openfort-js').AuthPlayerResponse | null;
13
- /** Whether the SDK has initialized and is ready for use */
13
+ /** Whether the SDK has initialized and is ready for use. */
14
14
  isReady: boolean;
15
- /** Any error encountered during SDK initialization */
15
+ /** Any error encountered during SDK initialization. */
16
16
  error: Error | null;
17
- /** Supported chains configuration */
17
+ /** Supported chains configuration. */
18
18
  supportedChains?: [Chain, ...Chain[]];
19
- /** Embedded wallet configuration for Shield integration */
19
+ /** Embedded wallet configuration for Shield integration. */
20
20
  walletConfig?: EmbeddedWalletConfiguration;
21
- /** Current embedded wallet state */
21
+ /** Current embedded wallet state. */
22
22
  embeddedState: EmbeddedState;
23
- /** Password (email/SMS) authentication flow state */
23
+ /** Password (email/SMS) authentication flow state. */
24
24
  passwordState: PasswordFlowState;
25
- /** OAuth authentication flow state */
25
+ /** OAuth authentication flow state. */
26
26
  oAuthState: OAuthFlowState;
27
- /** Sign-in with Ethereum flow state */
27
+ /** Sign-in with Ethereum flow state. */
28
28
  siweState: SiweFlowState;
29
- /** Recovery flow state */
29
+ /** Recovery flow state. */
30
30
  recoveryFlowState: RecoveryFlowState;
31
31
  setPasswordState: React.Dispatch<React.SetStateAction<PasswordFlowState>>;
32
32
  setOAuthState: React.Dispatch<React.SetStateAction<OAuthFlowState>>;
33
33
  setSiweState: React.Dispatch<React.SetStateAction<SiweFlowState>>;
34
34
  setRecoveryFlowState: React.Dispatch<React.SetStateAction<RecoveryFlowState>>;
35
- /** Logs the current user out and clears any stored tokens */
35
+ /** Logs the current user out and clears any stored tokens. */
36
36
  logout: () => Promise<void>;
37
- /** Gets the current authenticated user's access token */
37
+ /** Gets the current authenticated user's access token. */
38
38
  getAccessToken: () => Promise<string | null>;
39
- /** @internal Refreshes user state after authentication changes */
39
+ /** @internal Refreshes user state after authentication changes. */
40
40
  _internal: {
41
41
  refreshUserState: (user?: import('@openfort/openfort-js').AuthPlayerResponse) => Promise<import('@openfort/openfort-js').AuthPlayerResponse | null>;
42
42
  };
43
43
  }
44
44
  /**
45
- * React context for sharing Openfort SDK state throughout the component tree
45
+ * React context for sharing Openfort SDK state throughout the component tree.
46
46
  */
47
47
  export declare const OpenfortContext: React.Context<OpenfortContextValue | null>;
48
48
  /**
49
49
  * Hook to access the Openfort context
50
- * Throws an error if used outside of a OpenfortProvider
50
+ *
51
+ * This hook provides access to the Openfort SDK context including client instance,
52
+ * user state, and authentication methods. Must be used within an OpenfortProvider.
53
+ *
54
+ * @returns The {@link OpenfortContextValue} from the nearest provider
55
+ * @throws {Error} When used outside an {@link OpenfortProvider}
56
+ *
57
+ * @example
58
+ * ```tsx
59
+ * const { client, user, isReady, logout } = useOpenfortContext();
60
+ *
61
+ * // Check if SDK is ready
62
+ * if (isReady && user) {
63
+ * console.log('User authenticated:', user.id);
64
+ *
65
+ * // Access client methods
66
+ * const token = await client.getAccessToken();
67
+ * }
68
+ * ```
51
69
  */
52
70
  export declare function useOpenfortContext(): OpenfortContextValue;
53
71
  /**
54
72
  * Hook to safely access the Openfort context
55
- * Returns null if used outside of a OpenfortProvider
73
+ *
74
+ * This hook provides safe access to the Openfort SDK context without throwing errors.
75
+ * Returns null when used outside of an OpenfortProvider instead of throwing.
76
+ *
77
+ * @returns The {@link OpenfortContextValue} when available, otherwise `null`
78
+ *
79
+ * @example
80
+ * ```tsx
81
+ * const context = useOpenfortContextSafe();
82
+ *
83
+ * if (context) {
84
+ * const { user, isReady } = context;
85
+ * console.log('Context available:', { user: !!user, isReady });
86
+ * } else {
87
+ * console.log('No Openfort context found');
88
+ * }
89
+ * ```
56
90
  */
57
91
  export declare function useOpenfortContextSafe(): OpenfortContextValue | null;
58
92
  /**
59
- * Type guard to check if a value is a valid OpenfortContextValue
93
+ * Runtime type guard that checks whether a value satisfies {@link OpenfortContextValue}.
94
+ *
95
+ * @param value - Value to check.
96
+ * @returns `true` when the value matches the {@link OpenfortContextValue} shape.
60
97
  */
61
98
  export declare function isOpenfortContextValue(value: unknown): value is OpenfortContextValue;