@human-protocol/sdk 5.2.0 → 6.1.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(
@@ -110,13 +129,13 @@ export class TransactionUtils {
    *   token?: string; // (Optional) The token address to filter transactions.
    *   startDate?: Date; // (Optional) The start date to filter transactions (inclusive).
    *   endDate?: Date; // (Optional) The end date to filter transactions (inclusive).
-   *   startBlock?: number; // (Optional) The start block number to filter transactions (inclusive).
-   *   endBlock?: number; // (Optional) The end block number to filter transactions (inclusive).
+   *   startBlock?: bigint | number; // (Optional) The start block to filter transactions (inclusive).
+   *   endBlock?: bigint | number; // (Optional) The end block to filter transactions (inclusive).
    *   first?: number; // (Optional) Number of transactions per page. Default is 10.
    *   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(
@@ -199,8 +220,8 @@ export class TransactionUtils {
           ? getUnixTimestamp(filter?.startDate)
           : undefined,
         endDate: filter.endDate ? getUnixTimestamp(filter.endDate) : undefined,
-        startBlock: filter.startBlock ? filter.startBlock : undefined,
-        endBlock: filter.endBlock ? filter.endBlock : undefined,
+        startBlock: filter.startBlock ? Number(filter.startBlock) : undefined,
+        endBlock: filter.endBlock ? Number(filter.endBlock) : undefined,
         method: filter.method ? filter.method : undefined,
         escrow: filter.escrow ? filter.escrow : undefined,
         token: filter.token ? filter.token : undefined,

package/src/types.ts

@@ -1,4 +1,4 @@
-import { TransactionLike } from 'ethers';
+import { Overrides, TransactionLike } from 'ethers';
 
 /**
  * Enum for escrow statuses.
@@ -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
  */
@@ -143,4 +86,19 @@ export type NetworkData = {
   oldFactoryAddress: string;
 };
 
+/**
+ * Options that configure how long to wait for transaction confirmations.
+ */
+export type WaitOptions = {
+  /** Number of block confirmations to wait for. */
+  confirmations?: number;
+  /** Milliseconds to wait before aborting `tx.wait()`. */
+  timeoutMs?: number;
+};
+
+/**
+ * Extends ethers overrides with `wait()` options that control confirmation count and timeout.
+ */
+export type TransactionOverrides = Overrides & WaitOptions;
+
 export type TransactionLikeWithNonce = TransactionLike & { nonce: number };