connect hooks tsdoc (#367)

Author: VGabriel45

packages/connect/src/hooks/useChain.ts

@@ -1,7 +1,34 @@
 import { useChainId, useChains } from 'wagmi'
+import { Chain } from 'wagmi/chains'
 
-// Returns chain config for current chain or chain by id
-export const useChain = (chainId?: number) => {
+/**
+ * Hook for retrieving chain configuration information from wagmi's chain configurations
+ *
+ * This hook provides functionality to:
+ * - Get the configuration for the currently connected chain
+ * - Get the configuration for a specific chain by ID
+ * - Access chain-specific details like name, network configuration, RPC URLs, and block explorers
+ *
+ * The hook is commonly used in conjunction with other Sequence hooks to access chain-specific
+ * information when working with transactions, indexer clients, or network-specific features.
+ *
+ * @see {@link https://docs.sequence.xyz/sdk/web/hooks/useChain} for more detailed documentation.
+ *
+ * @param chainId - Optional chain ID to get configuration for a specific chain. If not provided, returns the current chain's configuration.
+ * @returns Chain configuration object for the specified or current chain, or undefined if not found
+ *
+ * @example
+ * ```tsx
+ * // Get current chain configuration
+ * const currentChain = useChain();
+ * console.log('Current chain name:', currentChain?.name);
+ *
+ * // Get configuration for a specific chain
+ * const ethereumChain = useChain(1); // Ethereum Mainnet
+ * console.log('Ethereum chain details:', ethereumChain);
+ * ```
+ */
+export const useChain = (chainId?: number): Chain | undefined => {
   const chains = useChains()
   const currentChainId = useChainId()
 

packages/connect/src/hooks/useCheckWaasFeeOptions.ts

@@ -3,6 +3,47 @@
 import { FeeOption, Transaction } from '@0xsequence/waas'
 import { useConnections } from 'wagmi'
 
+/**
+ * Hook for checking transaction fee options in Sequence WaaS (Wallet as a Service)
+ *
+ * This hook provides functionality to:
+ * - Check if a transaction will be sponsored
+ * - Get available fee options for unsponsored transactions
+ * - Retrieve fee quotes for transactions
+ *
+ * The hook is commonly used in conjunction with `useWaasFeeOptions` to handle fee payments
+ * for unsponsored transactions. It's particularly useful in
+ * wallet interfaces and transaction confirmation flows.
+ *
+ * @see {@link https://docs.sequence.xyz/sdk/web/hooks/useCheckWaasFeeOptions} for more detailed documentation.
+ *
+ * @returns A function that accepts transaction details and returns fee information
+ * @returns.feeQuote - The fee quote for the transaction if available
+ * @returns.feeOptions - Available fee payment options if the transaction is not sponsored
+ * @returns.isSponsored - Whether the transaction is sponsored (true) or requires fee payment (false)
+ *
+ * @example
+ * ```tsx
+ * import { useCheckWaasFeeOptions } from '@0xsequence/connect'
+ *
+ * const YourComponent = () => {
+ *   const checkFeeOptions = useCheckWaasFeeOptions()
+ *
+ *   const handleTransaction = async () => {
+ *     const { isSponsored, feeOptions, feeQuote } = await checkFeeOptions({
+ *       transactions: [transaction],
+ *       chainId: 1 // Ethereum Mainnet
+ *     })
+ *
+ *     if (!isSponsored && feeOptions) {
+ *       // Handle fee options for unsponsored transaction
+ *       console.log('Available fee options:', feeOptions)
+ *       console.log('Fee quote:', feeQuote)
+ *     }
+ *   }
+ * }
+ * ```
+ */
 export function useCheckWaasFeeOptions(): (params: { transactions: Transaction[]; chainId: number }) => Promise<{
   feeQuote: string | undefined
   feeOptions: FeeOption[] | undefined

packages/connect/src/hooks/useDirectEcosystemConnect.ts

@@ -2,6 +2,38 @@ import { useConnect } from 'wagmi'
 
 import { EcosystemConnector } from '../connectors/ecosystem/ecosystemWallet'
 
+/**
+ * Hook to directly connect to an ecosystem wallet with email
+ *
+ * @returns A function that triggers the ecosystem wallet connection
+ * @throws {Error} If the ecosystem wallet connector is not found among available connectors
+ *
+ * The returned function accepts:
+ * - `auxData` (optional) - Additional data to pass to the ecosystem connector during connection
+ *
+ * @example
+ * ```tsx
+ * const triggerConnect = useDirectEcosystemConnect()
+ *
+ * // Connect without auxiliary data
+ * await triggerConnect()
+ *
+ * // Connect with auxiliary data
+ * await triggerConnect({
+ *   someKey: 'someValue',
+ *   anotherKey: 123
+ * })
+ *
+ * // Handle connection errors
+ * try {
+ *   await triggerConnect()
+ * } catch (error) {
+ *   if (error.message === 'Ecosystem wallet connector not found') {
+ *     console.error('Ecosystem wallet is not configured')
+ *   }
+ * }
+ * ```
+ */
 export const useDirectEcosystemConnect = () => {
   const { connectors, connect } = useConnect()
 

packages/connect/src/hooks/useOpenConnectModal.ts

@@ -17,7 +17,7 @@ type UseOpenConnectModalReturnType = {
  * This hook provides a method to open and close the connect modal, and access its current open state.
  * The Connect modal provides various wallet connection options including Sequence wallet and external wallets.
  *
- * Go to {@link https://docs.sequence.xyz/sdk/web/hooks/useOpenConnectModal} for more detailed documentation.
+ * @see {@link https://docs.sequence.xyz/sdk/web/hooks/useOpenConnectModal} for more detailed documentation.
  *
  * @returns An object containing function to control the Connect modal and its state {@link UseOpenConnectModalReturnType}
  *

packages/connect/src/hooks/useProjectAccessKey.ts

@@ -1,5 +1,22 @@
 import { useConnectConfigContext } from '../contexts/ConnectConfig.js'
 
+/**
+ * Hook to access the project access key from the Sequence Connect configuration.
+ *
+ * The project access key is a required configuration parameter used to authenticate and
+ * identify your application with Sequence services. It is used across various SDK features
+ * including marketplace integration and wallet connections.
+ *
+ * @see {@link https://docs.sequence.xyz/sdk/web/hooks/useProjectAccessKey} for more detailed documentation.
+ *
+ * @returns {string} The project access key configured for the application
+ *
+ * @example
+ * ```tsx
+ * const projectAccessKey = useProjectAccessKey()
+ * const marketplaceClient = new MarketplaceIndexer(apiUrl, projectAccessKey)
+ * ```
+ */
 export const useProjectAccessKey = () => {
   const { projectAccessKey } = useConnectConfigContext()
 

packages/connect/src/hooks/useSignInEmail.ts

@@ -5,6 +5,26 @@ import { useConfig, useAccount } from 'wagmi'
 
 import { LocalStorageKey } from '../constants/localStorage'
 
+/**
+ * Hook to retrieve the email address associated with the currently connected wallet.
+ *
+ * This hook monitors the connection status and retrieves the stored email address when a wallet
+ * is connected. It works with both WaaS (Wallet-as-a-Service) and universal wallet types.
+ * The email is cleared when the wallet is disconnected.
+ *
+ * @see {@link https://docs.sequence.xyz/sdk/web/hooks/useSignInEmail} for more detailed documentation.
+ *
+ * @returns {string | null} The email address of the connected wallet user, or null if not connected
+ * or no email is associated
+ *
+ * @example
+ * ```tsx
+ * const email = useSignInEmail()
+ * if (email) {
+ *   console.log('Connected user email:', email)
+ * }
+ * ```
+ */
 export const useSignInEmail = () => {
   const { storage } = useConfig()
   const { isConnected } = useAccount()

packages/connect/src/hooks/useTheme.ts

@@ -1,5 +1,31 @@
 import { useThemeContext } from '../contexts/Theme'
 
+/**
+ * Hook to access and modify the theme and modal position settings.
+ *
+ * This hook provides access to the current theme (light/dark) and modal position settings,
+ * along with functions to update these values. The modal position can be set to various
+ * predefined positions on the screen.
+ *
+ * @see {@link https://docs.sequence.xyz/sdk/web/hooks/useTheme} for more detailed documentation.
+ *
+ * @returns {Object} An object containing:
+ * - `theme` - The current theme setting
+ * - `setTheme` - Function to update the theme
+ * - `position` - The current modal position ('center', 'top-right', 'bottom-left', etc.)
+ * - `setPosition` - Function to update the modal position
+ *
+ * @example
+ * ```tsx
+ * const { theme, setTheme, position, setPosition } = useTheme()
+ *
+ * // Change theme
+ * setTheme('dark')
+ *
+ * // Update modal position
+ * setPosition('top-right')
+ * ```
+ */
 export const useTheme = () => {
   const { setTheme, theme, position, setPosition } = useThemeContext()
 

packages/connect/src/hooks/useWaasConfirmationHandler.ts

@@ -13,6 +13,45 @@ export type WaasRequestConfirmation = {
   chainId?: number
 }
 
+/**
+ * Hook to handle transaction and message signing confirmations for WaaS (Wallet-as-a-Service) connections.
+ *
+ * This hook sets up confirmation handlers for signing transactions and messages when using a WaaS connector.
+ * It manages the state of pending confirmations and provides functions to confirm or reject signing requests.
+ *
+ * @param waasConnector - The WaaS connector instance to handle confirmations for (optional)
+ *
+ * @returns A tuple containing:
+ * - [0] {@link WaasRequestConfirmation} | undefined - The current pending request confirmation info or undefined if none
+ * - [1] `(id: string) => void` - Function to confirm a pending request by ID
+ * - [2] `(id: string) => void` - Function to reject a pending request by ID
+ *
+ * The {@link WaasRequestConfirmation} object contains:
+ * - `id` - Unique identifier for the request
+ * - `type` - Either 'signTransaction' or 'signMessage'
+ * - `message?` - Optional message to sign (for signMessage requests)
+ * - `txs?` - Optional array of transactions (for signTransaction requests)
+ * - `chainId?` - Optional chain ID for the request
+ *
+ * @example
+ * ```tsx
+ * const [
+ *   pendingRequestConfirmation,
+ *   confirmPendingRequest,
+ *   rejectPendingRequest
+ * ] = useWaasConfirmationHandler(waasConnector)
+ *
+ * // When user confirms the request
+ * if (pendingRequestConfirmation) {
+ *   confirmPendingRequest(pendingRequestConfirmation.id)
+ * }
+ *
+ * // When user rejects the request
+ * if (pendingRequestConfirmation) {
+ *   rejectPendingRequest(pendingRequestConfirmation.id)
+ * }
+ * ```
+ */
 export function useWaasConfirmationHandler(
   waasConnector?: any
 ): [WaasRequestConfirmation | undefined, (id: string) => void, (id: string) => void] {

packages/connect/src/hooks/useWaasEmailAuth.ts

@@ -15,6 +15,52 @@ interface SuccessResultV2 {
   signInResponse: SignInResponse
 }
 
+/**
+ * Hook to handle email-based authentication flow for WaaS (Wallet-as-a-Service).
+ *
+ * This hook manages the complete email authentication process, including:
+ * - Initiating email authentication
+ * - Handling verification code submission
+ * - Managing loading and error states
+ * - Supporting both v1 (idToken) and v2 (SignInResponse) authentication formats
+ *
+ * @param {ExtendedConnector} [params.connector] - The WaaS connector to use for authentication.
+ *        Optional because the user might not have selected a connector yet.
+ * @param {Function} params.onSuccess - Callback function called when authentication succeeds.
+ *        Receives either a v1 result (with idToken) or v2 result (with SignInResponse).
+ *
+ * @returns {Object} An object containing:
+ * - `inProgress` - Whether authentication is currently in progress
+ * - `loading` - Whether a specific authentication operation is loading
+ * - `error` - Any error that occurred during authentication
+ * - `initiateAuth` - Function to start the email authentication process
+ * - `sendChallengeAnswer` - Function to submit the verification code
+ * - `cancel` - Function to cancel the authentication process
+ * - `resetError` - Function to clear any error state
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   inProgress,
+ *   loading,
+ *   error,
+ *   initiateAuth,
+ *   sendChallengeAnswer,
+ *   resetError
+ * } = useEmailAuth({
+ *   connector: emailConnector,
+ *   onSuccess: async (result) => {
+ *     if ('signInResponse' in result) {
+ *       // Handle v2 authentication
+ *       await storage.setItem('email', result.signInResponse.email)
+ *     } else {
+ *       // Handle v1 authentication
+ *       await storage.setItem('idToken', result.idToken)
+ *     }
+ *   }
+ * })
+ * ```
+ */
 export function useEmailAuth({
   connector,
   onSuccess

packages/connect/src/hooks/useWaasEmailConflict.ts

@@ -2,11 +2,23 @@ import { IdentityType, EmailConflictInfo, SequenceWaaS } from '@0xsequence/waas'
 import { useEffect, useRef, useState } from 'react'
 import { useConnect } from 'wagmi'
 
+/**
+ * Represents formatted email conflict information returned by the hook.
+ * This is a user-friendly version of the EmailConflictInfo from the WaaS service.
+ */
 export type FormattedEmailConflictInfo = {
+  /** The email address that caused the conflict */
   email: string
+  /** User-friendly description of the account type (e.g., 'Google login', 'Email login') */
   type: string
 }
 
+/**
+ * Helper function to convert raw account type information into user-friendly text.
+ *
+ * @param info - The raw email conflict information from WaaS
+ * @returns A user-friendly string describing the account type
+ */
 const accountTypeText = (info: EmailConflictInfo | null) => {
   if (!info) {
     return 'Unknown account type'
@@ -34,6 +46,39 @@ const accountTypeText = (info: EmailConflictInfo | null) => {
   return info.type
 }
 
+/**
+ * Hook to handle email conflict detection and resolution for WaaS (Wallet-as-a-Service) authentication.
+ *
+ * This hook monitors all WaaS connectors for email conflicts that occur during sign-in attempts.
+ * A conflict happens when a user tries to sign up with an email that's already associated with
+ * a different authentication method (e.g., trying to use Google sign-in when the email was
+ * previously used with Apple sign-in).
+ *
+ * @returns An object containing:
+ * - `toggleEmailConflictModal` - Function to manually show/hide the conflict modal
+ * - `isEmailConflictOpen` - Whether the conflict modal is currently open
+ * - `emailConflictInfo` - Formatted information about the conflict (email and account type)
+ * - `forceCreate` - Function to force create a new account despite the conflict
+ *
+ * @example
+ * ```tsx
+ * const {
+ *   isEmailConflictOpen,
+ *   emailConflictInfo,
+ *   toggleEmailConflictModal
+ * } = useEmailConflict()
+ *
+ * // When a conflict is detected
+ * if (isEmailConflictOpen && emailConflictInfo) {
+ *   console.log(
+ *     `Email ${emailConflictInfo.email} is already used with ${emailConflictInfo.type}`
+ *   )
+ * }
+ *
+ * // Close the conflict modal
+ * toggleEmailConflictModal(false)
+ * ```
+ */
 export const useEmailConflict = () => {
   const { connectors } = useConnect()
   const forceCreateFuncRef = useRef<((forceCreate: boolean) => Promise<void>) | null>(null)