Skip to content

Commit e65b358

Browse files
VGabriel45VGabriel45
authored
docs: tsdoc for indexer hooks (#375)
* docs: tsdoc for indexer hooks * docs: added link to docs
1 parent 34d6339 commit e65b358

File tree

3 files changed

+165
-2
lines changed

3 files changed

+165
-2
lines changed

‎packages/hooks/src/hooks/Indexer/useGetTransactionHistory.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ const getTransactionHistory = async (
7979
* It can filter transactions by contract address and token ID, making it useful for both
8080
* general account history and specific asset history views.
8181
*
82-
* Go to {@link https://docs.sequence.xyz/sdk/web/hooks/useGetTransactionHistory} for more detailed documentation.
82+
* @see {@link https://docs.sequence.xyz/sdk/web/hooks/useGetTransactionHistory} for more detailed documentation.
8383
*
8484
* @param args - Configuration object for the transaction history query {@link GetTransactionHistoryArgs}
8585
*

‎packages/hooks/src/hooks/Indexer/useGetTransactionHistorySummary.ts‎

Lines changed: 66 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,72 @@ const getTransactionHistorySummary = async (
4747
}
4848

4949
/**
50-
* @description Gets the exhaustive transaction history for a given accountAddress and list of chainIds
50+
* A hook that retrieves a comprehensive transaction history summary across multiple chains for a given account address.
51+
* The transactions are ordered by timestamp (newest first) and include detailed transfer information.
52+
*
53+
* Implementation details:
54+
* - Uses Promise.all with an array of indexer clients to fetch transactions from all specified chains in parallel
55+
* - Flattens and sorts the combined results by timestamp
56+
* - Normalizes all addresses in transfer objects using viem's getAddress
57+
*
58+
* @param getTransactionHistorySummaryArgs - Configuration object for the transaction history query
59+
* @param getTransactionHistorySummaryArgs.accountAddress - The account address to fetch transactions for
60+
* @param getTransactionHistorySummaryArgs.chainIds - Array of chain IDs to fetch transactions from. Each chain ID will be queried in parallel.
61+
* @param options - Optional configuration for the hook behavior
62+
* @param options.disabled - If true, disables the query
63+
* @param options.retry - If true (default), retries failed requests
64+
*
65+
* @returns A React Query result object containing:
66+
* - data: Array of Transaction objects combined from all specified chains, each containing:
67+
* - txnHash: Transaction hash
68+
* - chainId: Chain ID where transaction occurred
69+
* - timestamp: Transaction timestamp
70+
* - transfers: Array of transfer objects with normalized addresses
71+
* - blockNumber: Block number where transaction was mined
72+
* - blockHash: Hash of the block
73+
* - metaTxnID: Optional meta transaction ID
74+
* - Other standard React Query properties (isLoading, isError, etc.)
75+
*
76+
* @see {@link https://docs.sequence.xyz/sdk/web/hooks/useGetTransactionHistorySummary} for more detailed documentation.
77+
*
78+
* @example
79+
* ```tsx
80+
* import { useGetTransactionHistorySummary } from '@0xsequence/hooks'
81+
* import { useAccount } from 'wagmi'
82+
*
83+
* // Basic usage in a component
84+
* const TransactionHistory = () => {
85+
* const { address: accountAddress } = useAccount()
86+
* const {
87+
* data: transactionHistory = [],
88+
* isPending: isPendingTransactionHistory
89+
* } = useGetTransactionHistorySummary({
90+
* accountAddress: accountAddress || '',
91+
* chainIds: [1, 137]
92+
* })
93+
*
94+
* return (
95+
* <div>
96+
* {transactionHistory.map(tx => (
97+
* <div key={tx.txnHash}>
98+
* Transaction: {tx.txnHash}
99+
* Chain: {tx.chainId}
100+
* Time: {tx.timestamp}
101+
* </div>
102+
* ))}
103+
* </div>
104+
* )
105+
* }
106+
* ```
107+
*
108+
* @remarks
109+
* - The hook uses the Sequence Indexer service to fetch transaction data
110+
* - Creates a separate indexer client for each chain ID and fetches from all in parallel
111+
* - Transactions from all chains are combined and sorted by timestamp (newest first)
112+
* - All addresses in transfer objects are normalized using viem's getAddress
113+
* - The query is enabled only when chainIds array is not empty and accountAddress is provided
114+
* - The query result is cached for 30 seconds (staleTime)
115+
* - The query automatically refetches when the component is mounted
51116
*/
52117
export const useGetTransactionHistorySummary = (
53118
getTransactionHistorySummaryArgs: GetTransactionHistorySummaryArgs,

‎packages/hooks/src/hooks/Indexer/useIndexerClient.ts‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,56 @@ import { envString } from '../../utils/envstring'
66
import { useConfig } from '../useConfig'
77
import { useNetwork } from '../useNetwork'
88

9+
/**
10+
* Hook that creates and manages a Sequence Indexer client for a specific chain.
11+
*
12+
* This hook maintains a cached indexer client for the specified chain ID,
13+
* initializing it with the appropriate indexer URL based on the network
14+
* and environment configuration.
15+
*
16+
* Implementation details:
17+
* - Creates a new SequenceIndexer instance for the specified chain ID if it doesn't exist
18+
* - Caches the client in a Map to avoid recreating it unnecessarily
19+
* - Uses projectAccessKey for authentication
20+
* - Constructs appropriate indexer URL based on network and environment
21+
*
22+
* @param chainId - The chain ID to create an indexer client for
23+
* @returns A SequenceIndexer instance for the specified chain
24+
*
25+
* @throws Error if an indexer client cannot be created for the specified chain ID
26+
*
27+
* @example
28+
* ```typescript
29+
* const TokenBalanceChecker = () => {
30+
* const chainId = useChainId()
31+
* const indexerClient = useIndexerClient(chainId)
32+
* const { address } = useAccount()
33+
*
34+
* const checkBalance = async () => {
35+
* // Get native token balance
36+
* const nativeBalance = await indexerClient.getNativeTokenBalance({
37+
* accountAddress: address
38+
* })
39+
*
40+
* // Get token balances
41+
* const tokenBalances = await indexerClient.getTokenBalancesSummary({
42+
* filter: {
43+
* accountAddresses: [address],
44+
* contractStatus: ContractVerificationStatus.ALL,
45+
* omitNativeBalances: true
46+
* }
47+
* })
48+
* }
49+
* }
50+
* ```
51+
*
52+
* @remarks
53+
* - The client is memoized based on projectAccessKey to prevent recreation
54+
* - The client is initialized only once per chain ID
55+
* - The environment configuration determines the indexer URL for the network
56+
* - Throws an error if the chain ID is not supported or client creation fails
57+
* - Used internally by useIndexerClients to manage multiple chain clients
58+
*/
959
export const useIndexerClient = (chainId: ChainId) => {
1060
const { env, projectAccessKey, jwt } = useConfig()
1161

@@ -29,6 +79,54 @@ export const useIndexerClient = (chainId: ChainId) => {
2979
return indexerClient
3080
}
3181

82+
/**
83+
* Hook that creates and manages Sequence Indexer clients for multiple chains.
84+
*
85+
* This hook maintains a map of indexer clients, one for each specified chain ID.
86+
* Each client is initialized with the appropriate indexer URL based on the network
87+
* and environment configuration.
88+
*
89+
* Implementation details:
90+
* - Creates a new SequenceIndexer instance for each unique chain ID
91+
* - Caches clients in a Map to avoid recreating them unnecessarily
92+
* - Uses projectAccessKey for authentication
93+
* - Constructs appropriate indexer URLs based on network and environment
94+
*
95+
* @param chainIds - Array of chain IDs to create indexer clients for
96+
* @returns A Map where keys are chain IDs and values are the corresponding SequenceIndexer instances
97+
*
98+
* @throws Error if an indexer client cannot be created for any of the specified chain IDs
99+
*
100+
* @see {@link https://docs.sequence.xyz/sdk/web/hooks/useIndexerClients} for more detailed documentation.
101+
*
102+
* @example
103+
* ```typescript
104+
* const TransactionFetcher = () => {
105+
* // Get indexer clients for Ethereum mainnet and Polygon
106+
* const indexerClients = useIndexerClients([1, 137])
107+
*
108+
* // Use the clients to fetch data
109+
* const fetchData = async () => {
110+
* // Get Ethereum client
111+
* const ethClient = indexerClients.get(1)
112+
* // Get Polygon client
113+
* const polygonClient = indexerClients.get(137)
114+
*
115+
* // Make parallel requests
116+
* const [ethData, polygonData] = await Promise.all([
117+
* ethClient.getTransactionHistory(...),
118+
* polygonClient.getTransactionHistory(...)
119+
* ])
120+
* }
121+
* }
122+
* ```
123+
*
124+
* @remarks
125+
* - The clients are memoized based on projectAccessKey to prevent recreation
126+
* - Each client is initialized only once per chain ID
127+
* - The environment configuration determines the indexer URL for each network
128+
* - Throws an error if a chain ID is not supported or client creation fails
129+
*/
32130
export const useIndexerClients = (chainIds: number[]) => {
33131
const { env, projectAccessKey, jwt } = useConfig()
34132

0 commit comments

Comments
 (0)