@openfort/react 0.0.12 → 0.0.14

package/build/hooks/openfort/auth/useOAuth.d.ts

@@ -23,6 +23,80 @@ export type StoreCredentialsOptions = {
 export type AuthHookOptions = {
     redirectTo?: string;
 } & OpenfortHookOptions<StoreCredentialsResult | InitOAuthReturnType> & CreateWalletPostAuthOptions;
+/**
+ * Hook for OAuth-based authentication operations
+ *
+ * This hook manages OAuth authentication flows including provider initialization,
+ * credential storage, and wallet connection after successful OAuth authentication.
+ * It supports multiple OAuth providers and handles the complete authentication lifecycle
+ * from provider selection to wallet setup.
+ *
+ * @param hookOptions - Optional configuration with callback functions and authentication options
+ * @returns Current OAuth authentication state and actions
+ *
+ * @example
+ * ```tsx
+ * const oauth = useOAuth({
+ *   onInitializeOAuthSuccess: (result) => console.log('OAuth initialized'),
+ *   onInitializeOAuthError: (error) => console.error('OAuth init failed:', error),
+ *   onStoreCredentialsSuccess: (result) => console.log('Authenticated:', result.user),
+ *   redirectTo: 'https://yourapp.com/auth/callback',
+ *   recoverWalletAutomatically: true,
+ * });
+ *
+ * // Initialize OAuth with a provider
+ * const handleGoogleAuth = async () => {
+ *   await oauth.initOAuth({
+ *     provider: OAuthProvider.GOOGLE,
+ *     redirectTo: 'https://yourapp.com/auth/callback',
+ *   });
+ * };
+ *
+ * const handleDiscordAuth = async () => {
+ *   await oauth.initOAuth({
+ *     provider: OAuthProvider.DISCORD,
+ *   });
+ * };
+ *
+ * // Store OAuth credentials (typically called from callback handler)
+ * const handleStoreCredentials = async () => {
+ *   await oauth.storeCredentials({
+ *     player: 'player-id-from-callback',
+ *     accessToken: 'access-token-from-callback',
+ *     refreshToken: 'refresh-token-from-callback',
+ *   });
+ * };
+ *
+ * // Link OAuth provider to existing authenticated account
+ * const handleLinkOAuth = async () => {
+ *   await oauth.linkOauth({
+ *     provider: OAuthProvider.GOOGLE,
+ *     redirectTo: 'https://yourapp.com/auth/callback',
+ *   });
+ * };
+ *
+ * // Check authentication state
+ * if (oauth.isLoading) {
+ *   console.log('Processing OAuth authentication...');
+ * } else if (oauth.isError) {
+ *   console.error('OAuth error:', oauth.error);
+ * } else if (oauth.isSuccess) {
+ *   console.log('OAuth authentication successful');
+ * }
+ *
+ * // Example usage in component with multiple providers
+ * return (
+ *   <div>
+ *     <button onClick={handleGoogleAuth} disabled={oauth.isLoading}>
+ *       Sign in with Google
+ *     </button>
+ *     <button onClick={handleDiscordAuth} disabled={oauth.isLoading}>
+ *       Sign in with Discord
+ *     </button>
+ *   </div>
+ * );
+ * ```
+ */
 export declare const useOAuth: (hookOptions?: AuthHookOptions) => {
     isLoading: boolean;
     isError: boolean;

package/build/hooks/openfort/auth/useSignOut.d.ts

@@ -1,4 +1,61 @@
 import { OpenfortError, OpenfortHookOptions } from '../../../types';
+/**
+ * Hook for user sign out operations
+ *
+ * This hook manages user logout functionality, clearing authentication state
+ * and disconnecting from all services. It provides a clean way to sign out users
+ * while handling any cleanup operations and providing loading/error states.
+ * The hook ensures complete logout by clearing all stored credentials and state.
+ *
+ * @param hookOptions - Optional configuration with callback functions
+ * @returns Current sign out state and actions
+ *
+ * @example
+ * ```tsx
+ * const signOutHook = useSignOut({
+ *   onSignOutSuccess: () => console.log('User signed out successfully'),
+ *   onSignOutError: (error) => console.error('Sign out failed:', error),
+ * });
+ *
+ * // Sign out user
+ * const handleSignOut = async () => {
+ *   try {
+ *     await signOutHook.signOut();
+ *     console.log('User has been signed out');
+ *     // Redirect to login page or update UI
+ *   } catch (error) {
+ *     console.error('Sign out failed:', error);
+ *   }
+ * };
+ *
+ * // Sign out with custom options
+ * const handleCustomSignOut = async () => {
+ *   await signOutHook.signOut({
+ *     onSuccess: () => console.log('Custom success handler'),
+ *     onError: (error) => console.error('Custom error handler:', error),
+ *   });
+ * };
+ *
+ * // Check sign out state
+ * if (signOutHook.isLoading) {
+ *   console.log('Signing out...');
+ * } else if (signOutHook.isError) {
+ *   console.error('Sign out error:', signOutHook.error);
+ * } else if (signOutHook.isSuccess) {
+ *   console.log('Sign out successful');
+ * }
+ *
+ * // Example usage in component
+ * return (
+ *   <button
+ *     onClick={handleSignOut}
+ *     disabled={signOutHook.isLoading}
+ *   >
+ *     {signOutHook.isLoading ? 'Signing out...' : 'Sign Out'}
+ *   </button>
+ * );
+ * ```
+ */
 export declare function useSignOut(hookOptions?: OpenfortHookOptions): {
     signOut: (options?: OpenfortHookOptions) => Promise<{}>;
     isLoading: boolean;

package/build/hooks/openfort/useStatus.d.ts

@@ -4,6 +4,48 @@ export declare enum OpenfortStatus {
     LOADING = 2,
     CONNECTED = 3
 }
+/**
+ * Hook for monitoring Openfort connection and authentication status
+ *
+ * This hook provides real-time status information about the user's connection to Openfort
+ * services and embedded wallet state. It tracks various states including loading, connected,
+ * disconnected, and authentication status based on embedded wallet configuration and connection.
+ *
+ * @returns Current connection and authentication status flags
+ *
+ * @example
+ * ```tsx
+ * const status = useStatus();
+ *
+ * // Check connection states
+ * if (status.isLoading) {
+ *   console.log('Initializing Openfort connection...');
+ * } else if (status.isConnecting) {
+ *   console.log('Connecting to wallet...');
+ * } else if (status.isConnected) {
+ *   console.log('Successfully connected to Openfort');
+ * } else if (status.isDisconnected) {
+ *   console.log('Not connected to Openfort');
+ * }
+ *
+ * // Check authentication state
+ * if (status.isAuthenticated) {
+ *   console.log('User is authenticated');
+ *   // Show authenticated UI
+ * } else {
+ *   console.log('User is not authenticated');
+ *   // Show login UI
+ * }
+ *
+ * // Conditional rendering based on status
+ * const renderContent = () => {
+ *   if (status.isLoading) return <LoadingSpinner />;
+ *   if (status.isConnecting) return <ConnectingIndicator />;
+ *   if (status.isConnected && status.isAuthenticated) return <AuthenticatedApp />;
+ *   return <LoginForm />;
+ * };
+ * ```
+ */
 export declare function useStatus(): {
     isLoading: boolean;
     isConnected: boolean;

package/build/hooks/openfort/useUI.d.ts

@@ -1,3 +1,66 @@
+/**
+ * Hook for controlling Openfort UI modal and navigation
+ *
+ * This hook provides programmatic control over the Openfort UI modal, including opening,
+ * closing, and navigating between different screens. It handles route validation and
+ * automatically selects appropriate screens based on user connection and authentication state.
+ * The hook ensures safe navigation by validating routes against user's current state.
+ *
+ * @returns UI control functions and modal state
+ *
+ * @example
+ * ```tsx
+ * const ui = useUI();
+ *
+ * // Check if modal is open
+ * if (ui.isOpen) {
+ *   console.log('Openfort modal is currently open');
+ * }
+ *
+ * // Open modal with default route (auto-determined by user state)
+ * const handleConnect = () => {
+ *   ui.open(); // Opens providers screen if not connected, profile if connected
+ * };
+ *
+ * // Close modal
+ * const handleClose = () => {
+ *   ui.close();
+ * };
+ *
+ * // Programmatically control modal state
+ * const toggleModal = () => {
+ *   ui.setIsOpen(!ui.isOpen);
+ * };
+ *
+ * // Open specific screens
+ * const handleProfileClick = () => {
+ *   ui.openProfile(); // Opens user profile screen (connected users only)
+ * };
+ *
+ * const handleProvidersClick = () => {
+ *   ui.openProviders(); // Opens authentication providers screen
+ * };
+ *
+ * const handleWalletsClick = () => {
+ *   ui.openWallets(); // Opens wallet connectors screen
+ * };
+ *
+ * const handleNetworkClick = () => {
+ *   ui.openSwitchNetworks(); // Opens network switching screen (connected users only)
+ * };
+ *
+ * // Example usage in component
+ * return (
+ *   <div>
+ *     <button onClick={handleConnect}>
+ *       {ui.isOpen ? 'Close' : 'Open'} Openfort
+ *     </button>
+ *     <button onClick={handleProfileClick}>Profile</button>
+ *     <button onClick={handleWalletsClick}>Wallets</button>
+ *   </div>
+ * );
+ * ```
+ */
 export declare function useUI(): {
     isOpen: boolean;
     open: () => void;

package/build/hooks/openfort/useUser.d.ts

@@ -1,3 +1,47 @@
+/**
+ * Hook for accessing current user information and authentication state
+ *
+ * This hook provides access to the current authenticated user's information and
+ * authentication status. It also offers methods to manage access tokens and validate
+ * user sessions. The hook automatically updates when authentication state changes.
+ *
+ * @returns Current user state and authentication utilities
+ *
+ * @example
+ * ```tsx
+ * const userHook = useUser();
+ *
+ * // Check if user is authenticated
+ * if (userHook.isAuthenticated && userHook.user) {
+ *   console.log('User is authenticated:', userHook.user);
+ *   console.log('User ID:', userHook.user.id);
+ *   console.log('User email:', userHook.user.email);
+ *   console.log('Linked accounts:', userHook.user.linkedAccounts);
+ * } else {
+ *   console.log('User is not authenticated');
+ * }
+ *
+ * // Get fresh access token
+ * const getToken = async () => {
+ *   try {
+ *     const token = await userHook.getAccessToken();
+ *     console.log('Access token:', token);
+ *   } catch (error) {
+ *     console.error('Failed to get access token:', error);
+ *   }
+ * };
+ *
+ * // Validate and refresh token if needed
+ * const refreshToken = async () => {
+ *   try {
+ *     await userHook.validateAndRefreshToken();
+ *     console.log('Token validated and refreshed');
+ *   } catch (error) {
+ *     console.error('Token validation failed:', error);
+ *   }
+ * };
+ * ```
+ */
 export declare function useUser(): {
     user: import("@openfort/openfort-js").AuthPlayerResponse | null;
     isAuthenticated: boolean;

package/build/hooks/openfort/useWallet.d.ts

@@ -1 +1,51 @@
+/**
+ * Hook for accessing the currently active wallet
+ *
+ * This hook provides access to the user's currently active/connected wallet.
+ * It's a simplified interface that returns just the active wallet from the
+ * useWallets hook, making it convenient when you only need the current wallet
+ * without all the wallet management functionality.
+ *
+ * @returns Currently active wallet or undefined if no wallet is connected
+ *
+ * @example
+ * ```tsx
+ * const activeWallet = useWallet();
+ *
+ * // Check if user has an active wallet
+ * if (activeWallet) {
+ *   console.log('Active wallet:', {
+ *     address: activeWallet.address,
+ *     type: activeWallet.connectorType,
+ *     id: activeWallet.id,
+ *   });
+ * } else {
+ *   console.log('No active wallet');
+ * }
+ *
+ * // Access wallet properties
+ * const walletAddress = activeWallet?.address;
+ * const walletType = activeWallet?.connectorType;
+ * const isEmbedded = activeWallet?.connectorType === 'embedded';
+ *
+ * // Example usage in component
+ * return (
+ *   <div>
+ *     {activeWallet ? (
+ *       <div>
+ *         <h3>Connected Wallet</h3>
+ *         <p>Address: {activeWallet.address}</p>
+ *         <p>Type: {activeWallet.connectorType}</p>
+ *         {activeWallet.isConnecting && <span>Connecting...</span>}
+ *       </div>
+ *     ) : (
+ *       <div>
+ *         <p>No wallet connected</p>
+ *         <button>Connect Wallet</button>
+ *       </div>
+ *     )}
+ *   </div>
+ * );
+ * ```
+ */
 export declare function useWallet(): import("./useWallets").UserWallet | undefined;

package/build/hooks/openfort/useWallets.d.ts

@@ -44,6 +44,62 @@ type SetRecoveryOptions = {
     newRecovery: RecoveryParams;
 } & OpenfortHookOptions<CreateWalletResult>;
 type WalletOptions = OpenfortHookOptions<SetActiveWalletResult | CreateWalletResult>;
+/**
+ * Hook for managing and interacting with user wallets
+ *
+ * This hook manages both embedded Openfort wallets and external wallets connected via Wagmi.
+ * It handles wallet creation, recovery, connection, and switching between different wallet types.
+ * The hook provides comprehensive wallet management functionality including creating embedded wallets,
+ * recovering existing ones, and managing wallet connections across multiple providers.
+ *
+ * @param hookOptions - Optional configuration with callback functions and wallet options
+ * @returns Current wallet state with management actions
+ *
+ * @example
+ * ```tsx
+ * const wallets = useWallets({
+ *   onCreateWalletSuccess: (result) => console.log('Wallet created:', result.wallet),
+ *   onCreateWalletError: (error) => console.error('Wallet creation failed:', error),
+ *   onSetActiveWalletSuccess: (result) => console.log('Wallet activated:', result.wallet),
+ * });
+ *
+ * // Check available wallets
+ * if (wallets.hasWallet) {
+ *   console.log('Available wallets:', wallets.wallets);
+ *   console.log('Active wallet:', wallets.activeWallet);
+ * }
+ *
+ * // Create a new embedded wallet with automatic recovery
+ * await wallets.createWallet({
+ *   recovery: { recoveryMethod: RecoveryMethod.AUTOMATIC },
+ *   accountType: AccountTypeEnum.SMART_ACCOUNT,
+ * });
+ *
+ * // Set active wallet by ID
+ * await wallets.setActiveWallet('embedded-wallet-id');
+ *
+ * // Set active wallet with custom recovery
+ * await wallets.setActiveWallet({
+ *   walletId: 'embedded-wallet-id',
+ *   recovery: { recoveryMethod: RecoveryMethod.PASSWORD, password: 'user-password' },
+ *   showUI: true,
+ * });
+ *
+ * // Set recovery method for existing wallet
+ * await wallets.setRecovery({
+ *   previousRecovery: { recoveryMethod: RecoveryMethod.AUTOMATIC },
+ *   newRecovery: { recoveryMethod: RecoveryMethod.PASSWORD, password: 'new-password' },
+ * });
+ *
+ * // Export private key from embedded wallet (requires authentication)
+ * try {
+ *   const privateKey = await wallets.exportPrivateKey();
+ *   console.log('Private key exported:', privateKey);
+ * } catch (error) {
+ *   console.error('Failed to export private key:', error);
+ * }
+ * ```
+ */
 export declare function useWallets(hookOptions?: WalletOptions): {
     exportPrivateKey: () => Promise<string>;
     error: OpenfortError | null | undefined;

package/build/hooks/useChainIsSupported.d.ts

@@ -1 +1,24 @@
-export declare function useChainIsSupported(chainId?: number): boolean | null;
+/**
+ * Hook for checking if a blockchain chain is supported.
+ *
+ * This hook verifies whether a specific blockchain chain ID is part of the
+ * configured Wagmi chains. Use it to validate chain compatibility before
+ * attempting operations or rendering chain-specific UI.
+ *
+ * @param chainId - The blockchain chain ID to check for support.
+ * @returns `true` when the chain is configured, `false` otherwise.
+ *
+ * @example
+ * ```tsx
+ * const ChainStatus: React.FC<{ chainId?: number }> = ({ chainId }) => {
+ *   const isSupported = useChainIsSupported(chainId);
+ *
+ *   return (
+ *     <span>
+ *       {chainId ?? 'Unknown chain'}: {isSupported ? 'Supported' : 'Unsupported'}
+ *     </span>
+ *   );
+ * };
+ * ```
+ */
+export declare function useChainIsSupported(chainId?: number): boolean;

package/build/hooks/useChains.d.ts

@@ -1,2 +1,41 @@
 import { Chain } from 'viem';
+/**
+ * Hook for accessing configured blockchain chains
+ *
+ * This hook provides access to all blockchain chains configured in the Wagmi config.
+ * It returns an array of chain objects containing network information such as
+ * chain ID, name, RPC URLs, and other blockchain-specific configuration.
+ *
+ * @returns Array of configured blockchain chains
+ *
+ * @example
+ * ```tsx
+ * const chains = useChains();
+ *
+ * // Display available chains
+ * console.log('Available chains:', chains.map(chain => ({
+ *   id: chain.id,
+ *   name: chain.name,
+ *   nativeCurrency: chain.nativeCurrency,
+ * })));
+ *
+ * // Check if specific chains are available
+ * const hasEthereum = chains.some(chain => chain.id === 1);
+ * const hasPolygon = chains.some(chain => chain.id === 137);
+ *
+ * // Example usage in component
+ * return (
+ *   <div>
+ *     <h3>Available Networks:</h3>
+ *     <ul>
+ *       {chains.map(chain => (
+ *         <li key={chain.id}>
+ *           {chain.name} (ID: {chain.id})
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   </div>
+ * );
+ * ```
+ */
 export declare function useChains(): Chain[];

package/build/hooks/useConnect.d.ts

@@ -1,6 +1,14 @@
 /**
- * This is a wrapper around wagmi's useConnect hook that adds some
- * additional functionality.
+ * Custom wrapper around {@link wagmiUseConnect} that adds Openfort specific logic.
+ *
+ * @param props - Optional configuration passed through to Wagmi's hook.
+ * @returns Connection helpers augmented with Openfort defaults and logging.
+ *
+ * @example
+ * ```ts
+ * const { connect, connectors } = useConnect();
+ * await connect({ connector: connectors[0] });
+ * ```
  */
 import { Connector, CreateConnectorFn, type UseConnectParameters } from 'wagmi';
 export declare function useConnect({ ...props }?: UseConnectParameters): {
@@ -27,11 +35,11 @@ export declare function useConnect({ ...props }?: UseConnectParameters): {
         connector: CreateConnectorFn | Connector;
         chainId?: number;
         mutation?: UseConnectParameters["mutation"];
-    }) => Promise<import("wagmi/query").ConnectData<import("wagmi").Config>>;
+    }) => Promise<import("wagmi/query").ConnectData<import("wagmi").Config, Connector, boolean>>;
     connectors: readonly Connector<CreateConnectorFn>[];
 } | {
     data: undefined;
-    variables: import("wagmi/query").ConnectVariables<import("wagmi").Config, Connector<CreateConnectorFn>>;
+    variables: import("wagmi/query").ConnectVariables<import("wagmi").Config, Connector<CreateConnectorFn>, boolean>;
     error: null;
     isError: false;
     isIdle: false;
@@ -53,11 +61,11 @@ export declare function useConnect({ ...props }?: UseConnectParameters): {
         connector: CreateConnectorFn | Connector;
         chainId?: number;
         mutation?: UseConnectParameters["mutation"];
-    }) => Promise<import("wagmi/query").ConnectData<import("wagmi").Config>>;
+    }) => Promise<import("wagmi/query").ConnectData<import("wagmi").Config, Connector, boolean>>;
     connectors: readonly Connector<CreateConnectorFn>[];
 } | {
     data: undefined;
-    variables: import("wagmi/query").ConnectVariables<import("wagmi").Config, Connector<CreateConnectorFn>>;
+    variables: import("wagmi/query").ConnectVariables<import("wagmi").Config, Connector<CreateConnectorFn>, boolean>;
     error: import("@wagmi/core").ConnectErrorType;
     isError: true;
     isIdle: false;
@@ -79,11 +87,11 @@ export declare function useConnect({ ...props }?: UseConnectParameters): {
         connector: CreateConnectorFn | Connector;
         chainId?: number;
         mutation?: UseConnectParameters["mutation"];
-    }) => Promise<import("wagmi/query").ConnectData<import("wagmi").Config>>;
+    }) => Promise<import("wagmi/query").ConnectData<import("wagmi").Config, Connector, boolean>>;
     connectors: readonly Connector<CreateConnectorFn>[];
 } | {
-    data: import("wagmi/query").ConnectData<import("wagmi").Config>;
-    variables: import("wagmi/query").ConnectVariables<import("wagmi").Config, Connector<CreateConnectorFn>>;
+    data: import("wagmi/query").ConnectData<import("wagmi").Config, Connector<CreateConnectorFn>, boolean>;
+    variables: import("wagmi/query").ConnectVariables<import("wagmi").Config, Connector<CreateConnectorFn>, boolean>;
     error: null;
     isError: false;
     isIdle: false;
@@ -105,6 +113,6 @@ export declare function useConnect({ ...props }?: UseConnectParameters): {
         connector: CreateConnectorFn | Connector;
         chainId?: number;
         mutation?: UseConnectParameters["mutation"];
-    }) => Promise<import("wagmi/query").ConnectData<import("wagmi").Config>>;
+    }) => Promise<import("wagmi/query").ConnectData<import("wagmi").Config, Connector, boolean>>;
     connectors: readonly Connector<CreateConnectorFn>[];
 };