@human-protocol/sdk 5.2.0 → 6.0.0

package/src/statistics.ts

@@ -30,51 +30,21 @@ import {
 } from './utils';
 
 /**
- * ## Introduction
+ * Utility class for statistics-related queries.
  *
- * This client enables obtaining statistical information from the subgraph.
- *
- * Unlike other SDK clients, `StatisticsClient` does not require `signer` or `provider` to be provided.
- * We just need to create a client object using relevant network data.
- *
- * ```ts
- * constructor(network: NetworkData)
- * ```
- *
- * ## Installation
- *
- * ### npm
- * ```bash
- * npm install @human-protocol/sdk
- * ```
- *
- * ### yarn
- * ```bash
- * yarn install @human-protocol/sdk
- * ```
- *
- * ## Code example
+ * Unlike other SDK clients, `StatisticsUtils` does not require `signer` or `provider` to be provided.
+ * We just need to pass the network data to each static method.
  *
+ * @example
  * ```ts
- * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+ * import { StatisticsUtils, ChainId, NETWORKS } from '@human-protocol/sdk';
  *
- * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
+ * const networkData = NETWORKS[ChainId.POLYGON_AMOY];
+ * const escrowStats = await StatisticsUtils.getEscrowStatistics(networkData);
+ * console.log('Total escrows:', escrowStats.totalEscrows);
  * ```
  */
-export class StatisticsClient {
-  public networkData: NetworkData;
-  public subgraphUrl: string;
-
-  /**
-   * **StatisticsClient constructor**
-   *
-   * @param {NetworkData} networkData - The network information required to connect to the Statistics contract
-   */
-  constructor(networkData: NetworkData) {
-    this.networkData = networkData;
-    this.subgraphUrl = getSubgraphUrl(networkData);
-  }
-
+export class StatisticsUtils {
   /**
    * This function returns the statistical data of escrows.
    *
@@ -106,29 +76,36 @@ export class StatisticsClient {
    * };
    * ```
    *
-   * @param {IStatisticsFilter} filter Statistics params with duration data
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IEscrowStatistics>} Escrow statistics data.
-   *
-   * **Code example**
+   * @param networkData - The network information required to connect to the subgraph
+   * @param filter - Statistics params with duration data
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Escrow statistics data.
    *
+   * @example
    * ```ts
-   * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
-   *
-   * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
-   *
-   * const escrowStatistics = await statisticsClient.getEscrowStatistics();
-   * const escrowStatisticsApril = await statisticsClient.getEscrowStatistics({
-   *    from: new Date('2021-04-01'),
-   *    to: new Date('2021-04-30'),
-   * });
+   * import { StatisticsUtils, ChainId, NETWORKS } from '@human-protocol/sdk';
+   *
+   * const networkData = NETWORKS[ChainId.POLYGON_AMOY];
+   * const escrowStats = await StatisticsUtils.getEscrowStatistics(networkData);
+   * console.log('Total escrows:', escrowStats.totalEscrows);
+   *
+   * const escrowStatsApril = await StatisticsUtils.getEscrowStatistics(
+   *   networkData,
+   *   {
+   *     from: new Date('2021-04-01'),
+   *     to: new Date('2021-04-30'),
+   *   }
+   * );
+   * console.log('April escrows:', escrowStatsApril.totalEscrows);
    * ```
    */
-  async getEscrowStatistics(
+  static async getEscrowStatistics(
+    networkData: NetworkData,
     filter: IStatisticsFilter = {},
     options?: SubgraphOptions
   ): Promise<IEscrowStatistics> {
     try {
+      const subgraphUrl = getSubgraphUrl(networkData);
       const first =
         filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
       const skip = filter.skip || 0;
@@ -136,12 +113,12 @@ export class StatisticsClient {
 
       const { escrowStatistics } = await customGqlFetch<{
         escrowStatistics: EscrowStatisticsData;
-      }>(this.subgraphUrl, GET_ESCROW_STATISTICS_QUERY, options);
+      }>(subgraphUrl, GET_ESCROW_STATISTICS_QUERY, options);
 
       const { eventDayDatas } = await customGqlFetch<{
         eventDayDatas: EventDayData[];
       }>(
-        this.subgraphUrl,
+        subgraphUrl,
         GET_EVENT_DAY_DATA_QUERY(filter),
         {
           from: filter.from ? getUnixTimestamp(filter.from) : undefined,
@@ -197,29 +174,36 @@ export class StatisticsClient {
    * };
    * ```
    *
-   * @param {IStatisticsFilter} filter Statistics params with duration data
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IWorkerStatistics>} Worker statistics data.
-   *
-   * **Code example**
+   * @param networkData - The network information required to connect to the subgraph
+   * @param filter - Statistics params with duration data
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Worker statistics data.
    *
+   * @example
    * ```ts
-   * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
-   *
-   * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
-   *
-   * const workerStatistics = await statisticsClient.getWorkerStatistics();
-   * const workerStatisticsApril = await statisticsClient.getWorkerStatistics({
-   *    from: new Date('2021-04-01'),
-   *    to: new Date('2021-04-30'),
-   * });
+   * import { StatisticsUtils, ChainId, NETWORKS } from '@human-protocol/sdk';
+   *
+   * const networkData = NETWORKS[ChainId.POLYGON_AMOY];
+   * const workerStats = await StatisticsUtils.getWorkerStatistics(networkData);
+   * console.log('Daily workers data:', workerStats.dailyWorkersData);
+   *
+   * const workerStatsApril = await StatisticsUtils.getWorkerStatistics(
+   *   networkData,
+   *   {
+   *     from: new Date('2021-04-01'),
+   *     to: new Date('2021-04-30'),
+   *   }
+   * );
+   * console.log('April workers:', workerStatsApril.dailyWorkersData.length);
    * ```
    */
-  async getWorkerStatistics(
+  static async getWorkerStatistics(
+    networkData: NetworkData,
     filter: IStatisticsFilter = {},
     options?: SubgraphOptions
   ): Promise<IWorkerStatistics> {
     try {
+      const subgraphUrl = getSubgraphUrl(networkData);
       const first =
         filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
       const skip = filter.skip || 0;
@@ -228,7 +212,7 @@ export class StatisticsClient {
       const { eventDayDatas } = await customGqlFetch<{
         eventDayDatas: EventDayData[];
       }>(
-        this.subgraphUrl,
+        subgraphUrl,
         GET_EVENT_DAY_DATA_QUERY(filter),
         {
           from: filter.from ? getUnixTimestamp(filter.from) : undefined,
@@ -279,50 +263,43 @@ export class StatisticsClient {
    * };
    * ```
    *
-   * @param {IStatisticsFilter} filter Statistics params with duration data
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IPaymentStatistics>} Payment statistics data.
-   *
-   * **Code example**
+   * @param networkData - The network information required to connect to the subgraph
+   * @param filter - Statistics params with duration data
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Payment statistics data.
    *
+   * @example
    * ```ts
-   * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
-   *
-   * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
+   * import { StatisticsUtils, ChainId, NETWORKS } from '@human-protocol/sdk';
    *
+   * const networkData = NETWORKS[ChainId.POLYGON_AMOY];
+   * const paymentStats = await StatisticsUtils.getPaymentStatistics(networkData);
    * console.log(
    *   'Payment statistics:',
-   *   (await statisticsClient.getPaymentStatistics()).dailyPaymentsData.map(
-   *     (p) => ({
-   *       ...p,
-   *       totalAmountPaid: p.totalAmountPaid.toString(),
-   *       averageAmountPerJob: p.averageAmountPerJob.toString(),
-   *       averageAmountPerWorker: p.averageAmountPerWorker.toString(),
-   *     })
-   *   )
-   * );
-   *
-   * console.log(
-   *   'Payment statistics from 5/8 - 6/8:',
-   *   (
-   *     await statisticsClient.getPaymentStatistics({
-   *       from: new Date(2023, 4, 8),
-   *       to: new Date(2023, 5, 8),
-   *     })
-   *   ).dailyPaymentsData.map((p) => ({
+   *   paymentStats.dailyPaymentsData.map((p) => ({
    *     ...p,
    *     totalAmountPaid: p.totalAmountPaid.toString(),
-   *     averageAmountPerJob: p.averageAmountPerJob.toString(),
    *     averageAmountPerWorker: p.averageAmountPerWorker.toString(),
    *   }))
    * );
+   *
+   * const paymentStatsRange = await StatisticsUtils.getPaymentStatistics(
+   *   networkData,
+   *   {
+   *     from: new Date(2023, 4, 8),
+   *     to: new Date(2023, 5, 8),
+   *   }
+   * );
+   * console.log('Payment statistics from 5/8 - 6/8:', paymentStatsRange.dailyPaymentsData.length);
    * ```
    */
-  async getPaymentStatistics(
+  static async getPaymentStatistics(
+    networkData: NetworkData,
     filter: IStatisticsFilter = {},
     options?: SubgraphOptions
   ): Promise<IPaymentStatistics> {
     try {
+      const subgraphUrl = getSubgraphUrl(networkData);
       const first =
         filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
       const skip = filter.skip || 0;
@@ -331,7 +308,7 @@ export class StatisticsClient {
       const { eventDayDatas } = await customGqlFetch<{
         eventDayDatas: EventDayData[];
       }>(
-        this.subgraphUrl,
+        subgraphUrl,
         GET_EVENT_DAY_DATA_QUERY(filter),
         {
           from: filter.from ? getUnixTimestamp(filter.from) : undefined,
@@ -371,29 +348,31 @@ export class StatisticsClient {
    * };
    * ```
    *
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IHMTStatistics>} HMToken statistics data.
-   *
-   * **Code example**
+   * @param networkData - The network information required to connect to the subgraph
+   * @param options - Optional configuration for subgraph requests.
+   * @returns HMToken statistics data.
    *
+   * @example
    * ```ts
-   * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
-   *
-   * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
-   *
-   * const hmtStatistics = await statisticsClient.getHMTStatistics();
+   * import { StatisticsUtils, ChainId, NETWORKS } from '@human-protocol/sdk';
    *
+   * const networkData = NETWORKS[ChainId.POLYGON_AMOY];
+   * const hmtStats = await StatisticsUtils.getHMTStatistics(networkData);
    * console.log('HMT statistics:', {
-   *   ...hmtStatistics,
-   *   totalTransferAmount: hmtStatistics.totalTransferAmount.toString(),
+   *   ...hmtStats,
+   *   totalTransferAmount: hmtStats.totalTransferAmount.toString(),
    * });
    * ```
    */
-  async getHMTStatistics(options?: SubgraphOptions): Promise<IHMTStatistics> {
+  static async getHMTStatistics(
+    networkData: NetworkData,
+    options?: SubgraphOptions
+  ): Promise<IHMTStatistics> {
     try {
+      const subgraphUrl = getSubgraphUrl(networkData);
       const { hmtokenStatistics } = await customGqlFetch<{
         hmtokenStatistics: HMTStatisticsData;
-      }>(this.subgraphUrl, GET_HMTOKEN_STATISTICS_QUERY, options);
+      }>(subgraphUrl, GET_HMTOKEN_STATISTICS_QUERY, options);
 
       return {
         totalTransferAmount: BigInt(hmtokenStatistics.totalValueTransfered),
@@ -408,39 +387,37 @@ export class StatisticsClient {
   /**
    * This function returns the holders of the HMToken with optional filters and ordering.
    *
-   * **Input parameters**
-   *
-   * @param {IHMTHoldersParams} params HMT Holders params with filters and ordering
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IHMTHolder[]>} List of HMToken holders.
-   *
-   * **Code example**
+   * @param networkData - The network information required to connect to the subgraph
+   * @param params - HMT Holders params with filters and ordering
+   * @param options - Optional configuration for subgraph requests.
+   * @returns List of HMToken holders.
    *
+   * @example
    * ```ts
-   * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
-   *
-   * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
+   * import { StatisticsUtils, ChainId, NETWORKS } from '@human-protocol/sdk';
    *
-   * const hmtHolders = await statisticsClient.getHMTHolders({
+   * const networkData = NETWORKS[ChainId.POLYGON_AMOY];
+   * const hmtHolders = await StatisticsUtils.getHMTHolders(networkData, {
    *   orderDirection: 'asc',
    * });
-   *
    * console.log('HMT holders:', hmtHolders.map((h) => ({
    *   ...h,
    *   balance: h.balance.toString(),
    * })));
    * ```
    */
-  async getHMTHolders(
+  static async getHMTHolders(
+    networkData: NetworkData,
     params: IHMTHoldersParams = {},
     options?: SubgraphOptions
   ): Promise<IHMTHolder[]> {
     try {
+      const subgraphUrl = getSubgraphUrl(networkData);
       const { address, orderDirection } = params;
       const query = GET_HOLDERS_QUERY(address);
 
       const { holders } = await customGqlFetch<{ holders: HMTHolderData[] }>(
-        this.subgraphUrl,
+        subgraphUrl,
         query,
         {
           address,
@@ -484,34 +461,36 @@ export class StatisticsClient {
    * }
    * ```
    *
-   * @param {IStatisticsFilter} filter Statistics params with duration data
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IDailyHMT[]>} Daily HMToken statistics data.
-   *
-   * **Code example**
+   * @param networkData - The network information required to connect to the subgraph
+   * @param filter - Statistics params with duration data
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Daily HMToken statistics data.
    *
+   * @example
    * ```ts
-   * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
-   *
-   * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_AMOY]);
-   *
-   * const dailyHMTStats = await statisticsClient.getHMTStatistics();
+   * import { StatisticsUtils, ChainId, NETWORKS } from '@human-protocol/sdk';
    *
+   * const networkData = NETWORKS[ChainId.POLYGON_AMOY];
+   * const dailyHMTStats = await StatisticsUtils.getHMTDailyData(networkData);
    * console.log('Daily HMT statistics:', dailyHMTStats);
    *
-   * const hmtStatisticsRange = await statisticsClient.getHMTStatistics({
-   *   from: new Date(2023, 4, 8),
-   *   to: new Date(2023, 5, 8),
-   * });
-   *
-   * console.log('HMT statistics from 5/8 - 6/8:', hmtStatisticsRange);
+   * const hmtStatsRange = await StatisticsUtils.getHMTDailyData(
+   *   networkData,
+   *   {
+   *     from: new Date(2023, 4, 8),
+   *     to: new Date(2023, 5, 8),
+   *   }
+   * );
+   * console.log('HMT statistics from 5/8 - 6/8:', hmtStatsRange.length);
    * ```
    */
-  async getHMTDailyData(
+  static async getHMTDailyData(
+    networkData: NetworkData,
     filter: IStatisticsFilter = {},
     options?: SubgraphOptions
   ): Promise<IDailyHMT[]> {
     try {
+      const subgraphUrl = getSubgraphUrl(networkData);
       const first =
         filter.first !== undefined ? Math.min(filter.first, 1000) : 10;
       const skip = filter.skip || 0;
@@ -520,7 +499,7 @@ export class StatisticsClient {
       const { eventDayDatas } = await customGqlFetch<{
         eventDayDatas: EventDayData[];
       }>(
-        this.subgraphUrl,
+        subgraphUrl,
         GET_EVENT_DAY_DATA_QUERY(filter),
         {
           from: filter.from ? getUnixTimestamp(filter.from) : undefined,

package/src/transaction.ts

@@ -19,6 +19,20 @@ import {
 } from './interfaces';
 import { getSubgraphUrl, getUnixTimestamp, customGqlFetch } from './utils';
 
+/**
+ * Utility class for transaction-related queries.
+ *
+ * @example
+ * ```ts
+ * import { TransactionUtils, ChainId } from '@human-protocol/sdk';
+ *
+ * const transaction = await TransactionUtils.getTransaction(
+ *   ChainId.POLYGON_AMOY,
+ *   '0x62dD51230A30401C455c8398d06F85e4EaB6309f'
+ * );
+ * console.log('Transaction:', transaction);
+ * ```
+ */
 export class TransactionUtils {
   /**
    * This function returns the transaction data for the given hash.
@@ -51,17 +65,22 @@ export class TransactionUtils {
    * };
    * ```
    *
-   * @param {ChainId} chainId The chain ID.
-   * @param {string} hash The transaction hash.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<ITransaction | null>} - Returns the transaction details or null if not found.
-   *
-   * **Code example**
+   * @param chainId - The chain ID.
+   * @param hash - The transaction hash.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Returns the transaction details or null if not found.
+   * @throws ErrorInvalidHashProvided If the hash is invalid
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
    *
+   * @example
    * ```ts
    * import { TransactionUtils, ChainId } from '@human-protocol/sdk';
    *
-   * const transaction = await TransactionUtils.getTransaction(ChainId.POLYGON, '0x62dD51230A30401C455c8398d06F85e4EaB6309f');
+   * const transaction = await TransactionUtils.getTransaction(
+   *   ChainId.POLYGON_AMOY,
+   *   '0x62dD51230A30401C455c8398d06F85e4EaB6309f'
+   * );
+   * console.log('Transaction:', transaction);
    * ```
    */
   public static async getTransaction(
@@ -116,7 +135,7 @@ export class TransactionUtils {
    *   skip?: number; // (Optional) Number of transactions to skip. Default is 0.
    *   orderDirection?: OrderDirection; // (Optional) Order of the results. Default is DESC.
    * }
-   *
+   * ```
    *
    * ```ts
    * type InternalTransaction = {
@@ -146,17 +165,18 @@ export class TransactionUtils {
    * };
    * ```
    *
-   * @param {ITransactionsFilter} filter Filter for the transactions.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<ITransaction[]>} Returns an array with all the transaction details.
-   *
-   * **Code example**
+   * @param filter - Filter for the transactions.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Returns an array with all the transaction details.
+   * @throws ErrorCannotUseDateAndBlockSimultaneously If both date and block filters are used
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
    *
+   * @example
    * ```ts
    * import { TransactionUtils, ChainId, OrderDirection } from '@human-protocol/sdk';
    *
-   * const filter: ITransactionsFilter = {
-   *   chainId: ChainId.POLYGON,
+   * const filter = {
+   *   chainId: ChainId.POLYGON_AMOY,
    *   startDate: new Date('2022-01-01'),
    *   endDate: new Date('2022-12-31'),
    *   first: 10,
@@ -164,6 +184,7 @@ export class TransactionUtils {
    *   orderDirection: OrderDirection.DESC,
    * };
    * const transactions = await TransactionUtils.getTransactions(filter);
+   * console.log('Transactions:', transactions.length);
    * ```
    */
   public static async getTransactions(

package/src/types.ts

@@ -36,63 +36,6 @@ export enum EscrowStatus {
   ToCancel,
 }
 
-/**
- * AWS/GCP cloud storage access data
- * @readonly
- * @deprecated StorageClient is deprecated. Use Minio.Client directly.
- */
-export type StorageCredentials = {
-  /**
-   * Access Key
-   */
-  accessKey: string;
-  /**
-   * Secret Key
-   */
-  secretKey: string;
-};
-
-/**
- * @deprecated StorageClient is deprecated. Use Minio.Client directly.
- */
-export type StorageParams = {
-  /**
-   * Request endPoint
-   */
-  endPoint: string;
-  /**
-   * Enable secure (HTTPS) access. Default value set to false
-   */
-  useSSL: boolean;
-  /**
-   * Region
-   */
-  region?: string;
-  /**
-   * TCP/IP port number. Default value set to 80 for HTTP and 443 for HTTPs
-   */
-  port?: number;
-};
-
-/**
- * Upload file data
- * @readonly
- */
-export type UploadFile = {
-  /**
-   * Uploaded object key
-   */
-  key: string;
-  /**
-   * Uploaded object URL
-   */
-  url: string;
-  /**
-   * Hash of uploaded object key
-   */
-  hash: string;
-};
-
 /**
  * Network data
  */

package/src/utils.ts

@@ -21,10 +21,16 @@ import { NetworkData } from './types';
 import { SubgraphOptions } from './interfaces';
 
 /**
- * **Handle and throw the error.*
+ * Handles and throws appropriate error types based on the Ethereum error.
  *
- * @param {any} e
- * @returns
+ * @param e - The error to handle
+ * @throws {InvalidArgumentError} If the error is an invalid argument error
+ * @throws {ContractExecutionError} If the error is a contract execution error
+ * @throws {TransactionReplaced} If the transaction was replaced
+ * @throws {ReplacementUnderpriced} If the replacement transaction was underpriced
+ * @throws {NumericFault} If there's a numeric fault
+ * @throws {NonceExpired} If the nonce has expired
+ * @throws {EthereumError} For any other Ethereum-related error
  */
 export const throwError = (e: any) => {
   if (ethers.isError(e, 'INVALID_ARGUMENT')) {
@@ -45,10 +51,10 @@ export const throwError = (e: any) => {
 };
 
 /**
- * **URL validation.*
+ * Validates if a string is a valid URL.
  *
- * @param {string} url
- * @returns
+ * @param url - The URL string to validate
+ * @returns True if the URL is valid, false otherwise
  */
 export const isValidUrl = (url: string): boolean => {
   return isURL(url, {
@@ -59,10 +65,10 @@ export const isValidUrl = (url: string): boolean => {
 };
 
 /**
- * **Check if a string is a valid JSON.*
+ * Checks if a string is valid JSON.
  *
- * @param {string} input
- * @returns {boolean}
+ * @param input - The string to check
+ * @returns True if the string is valid JSON, false otherwise
  */
 export const isValidJson = (input: string): boolean => {
   try {
@@ -74,10 +80,10 @@ export const isValidJson = (input: string): boolean => {
 };
 
 /**
- * **Get the subgraph URL.*
+ * Gets the subgraph URL for the given network, using API key if available.
  *
- * @param {NetworkData} networkData
- * @returns
+ * @param networkData - The network data containing subgraph URLs
+ * @returns The subgraph URL with API key if available
  */
 export const getSubgraphUrl = (networkData: NetworkData) => {
   let subgraphUrl = networkData.subgraphUrl;
@@ -95,10 +101,10 @@ export const getSubgraphUrl = (networkData: NetworkData) => {
 };
 
 /**
- * **Convert a date to Unix timestamp (seconds since epoch).*
+ * Converts a Date object to Unix timestamp (seconds since epoch).
  *
- * @param {Date} date
- * @returns {number}
+ * @param date - The date to convert
+ * @returns Unix timestamp in seconds
  */
 export const getUnixTimestamp = (date: Date): number => {
   return Math.floor(date.getTime() / 1000);
@@ -127,8 +133,16 @@ const buildIndexerUrl = (baseUrl: string, indexerId?: string): string => {
 };
 
 /**
- * Execute a GraphQL request with automatic retry logic for bad indexer errors.
- * Only retries if options is provided.
+ * Executes a GraphQL request with automatic retry logic for bad indexer errors.
+ * Only retries if options is provided with maxRetries and baseDelay.
+ *
+ * @param url - The GraphQL endpoint URL
+ * @param query - The GraphQL query to execute
+ * @param variables - Variables for the GraphQL query (optional)
+ * @param options - Optional configuration for subgraph requests including retry logic
+ * @returns The response data from the GraphQL query
+ * @throws ErrorRetryParametersMissing If only one of maxRetries or baseDelay is provided
+ * @throws ErrorRoutingRequestsToIndexerRequiresApiKey If indexerId is provided without API key
  */
 export const customGqlFetch = async <T = any>(
   url: string,