@human-protocol/sdk 1.1.13 → 1.1.15

package/dist/statistics.d.ts

@@ -1,6 +1,43 @@
 import { EscrowStatistics, HMTStatistics, PaymentStatistics, WorkerStatistics } from './graphql';
 import { IStatisticsParams } from './interfaces';
 import { NetworkData } from './types';
+/**
+ * ## Introduction
+ *
+ * This client enables to obtain statistical information from the subgraph.
+ *
+ * Unlikely from the other SDK clients, `StatisticsClient` does not require `signer` or `provider` to be provided.
+ * We just need to create client object using relevant network data.
+ *
+ * ```ts
+ * constructor(network: NetworkData)
+ * ```
+ *
+ * A `Signer` or a `Provider` should be passed depending on the use case of this module:
+ *
+ * - **Signer**: when the user wants to use this model in order to send transactions caling the contract functions.
+ * - **Provider**: when the user wants to use this model in order to get information from the contracts or subgraph.
+ *
+ * ## Installation
+ *
+ * ### npm
+ * ```bash
+ * npm install @human-protocol/sdk
+ * ```
+ *
+ * ### yarn
+ * ```bash
+ * yarn install @human-protocol/sdk
+ * ```
+ *
+ * ## Code example
+ *
+ * ```ts
+ * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+ *
+ * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+ * ```
+ */
 export declare class StatisticsClient {
     network: NetworkData;
     /**
@@ -10,35 +47,248 @@ export declare class StatisticsClient {
      */
     constructor(network: NetworkData);
     /**
-     * Returns the escrow statistics data for the given date range
+     * This function returns the statistical data of escrows.
      *
-     * @param {IStatisticsParams} params - Filter parameters.
-     * @returns {Promise<EscrowStatistics>}
-     * @throws {Error} - An error object if an error occurred.
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * interface IStatisticsParams {
+     *   from?: Date;
+     *   to?: Date;
+     *   limit?: number;
+     * }
+     * ```
+     *
+     * ```ts
+     * type DailyEscrowsData = {
+     *   timestamp: Date;
+     *   escrowsTotal: number;
+     *   escrowsPending: number;
+     *   escrowsSolved: number;
+     *   escrowsPaid: number;
+     *   escrowsCancelled: number;
+     * };
+     *
+     * type EscrowStatistics = {
+     *   totalEscrows: number;
+     *   dailyEscrowsData: DailyEscrowsData[];
+     * };
+     * ```
+     *
+     *
+     * @param {IStatisticsParams} params Statistics params with duration data
+     * @returns {EscrowStatistics} Escrow statistics data.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+     *
+     * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+     *
+     * const escrowStatistics = await statisticsClient.getEscrowStatistics();
+     * const escrowStatisticsApril = await statisticsClient.getEscrowStatistics({
+     *    from: new Date('2021-04-01'),
+     *    to: new Date('2021-04-30'),
+     * });
+     * ```
      */
     getEscrowStatistics(params?: IStatisticsParams): Promise<EscrowStatistics>;
     /**
-     * Returns the worker statistics data for the given date range
+     * This function returns the statistical data of workers.
+     *
+     *
+     * **Input parameters**
      *
-     * @param {IStatisticsParams} params - Filter parameters.
-     * @returns {Promise<WorkerStatistics>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```ts
+     * interface IStatisticsParams {
+     *   from?: Date;
+     *   to?: Date;
+     *   limit?: number;
+     * }
+     * ```
+     *
+     * ```ts
+     * type DailyWorkerData = {
+     *   timestamp: Date;
+     *   activeWorkers: number;
+     * };
+     *
+     * type WorkerStatistics = {
+     *   dailyWorkersData: DailyWorkerData[];
+     * };
+     * ```
+     *
+     *
+     * @param {IStatisticsParams} params Statistics params with duration data
+     * @returns {WorkerStatistics} Worker statistics data.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+     *
+     * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+     *
+     * const workerStatistics = await statisticsClient.getWorkerStatistics();
+     * const workerStatisticsApril = await statisticsClient.getWorkerStatistics({
+     *    from: new Date('2021-04-01'),
+     *    to: new Date('2021-04-30'),
+     * });
+     * ```
      */
     getWorkerStatistics(params?: IStatisticsParams): Promise<WorkerStatistics>;
     /**
-     * Returns the payment statistics data for the given date range
+     * This function returns the statistical data of payments.
+     *
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * interface IStatisticsParams {
+     *   from?: Date;
+     *   to?: Date;
+     *   limit?: number;
+     * }
+     * ```
      *
-     * @param {IStatisticsParams} params - Filter parameters.
-     * @returns {Promise<PaymentStatistics>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```ts
+     * type DailyPaymentData = {
+     *   timestamp: Date;
+     *   totalAmountPaid: BigNumber;
+     *   totalCount: number;
+     *   averageAmountPerWorker: BigNumber;
+     * };
+     *
+     * type PaymentStatistics = {
+     *   dailyPaymentsData: DailyPaymentData[];
+     * };
+     * ```
+     *
+     *
+     * @param {IStatisticsParams} params Statistics params with duration data
+     * @returns {PaymentStatistics} Payment statistics data.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+     *
+     * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+     *
+     * 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) => ({
+     *     ...p,
+     *     totalAmountPaid: p.totalAmountPaid.toString(),
+     *     averageAmountPerJob: p.averageAmountPerJob.toString(),
+     *     averageAmountPerWorker: p.averageAmountPerWorker.toString(),
+     *   }))
+     * );
+     * ```
      */
     getPaymentStatistics(params?: IStatisticsParams): Promise<PaymentStatistics>;
     /**
-     * Returns the HMToken statistics data for the given date range
+     * This function returns the statistical data of HMToken.
+     *
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * interface IStatisticsParams {
+     *   from?: Date;
+     *   to?: Date;
+     *   limit?: number;
+     * }
+     * ```
+     *
+     * ```ts
+     * type HMTHolder = {
+     *   address: string;
+     *   balance: BigNumber;
+     * }
+     *
+     * type DailyHMTData = {
+     *   timestamp: Date;
+     *   totalTransactionAmount: BigNumber;
+     *   totalTransactionCount: number;
+     * };
+     *
+     * type HMTStatistics = {
+     *   totalTransferAmount: BigNumber;
+     *   totalTransferCount: BigNumber;
+     *   totalHolders: number;
+     *   holders: HMTHolder[];
+     *   dailyHMTData: DailyHMTData[];
+     * };
+     * ```
+     *
+     *
+     * @param {IStatisticsParams} params Statistics params with duration data
+     * @returns {HMTStatistics} HMToken statistics data.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+     *
+     * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+     *
+     * const hmtStatistics = await statisticsClient.getHMTStatistics();
+     *
+     * console.log('HMT statistics:', {
+     *   ...hmtStatistics,
+     *   totalTransferAmount: hmtStatistics.totalTransferAmount.toString(),
+     *   holders: hmtStatistics.holders.map((h) => ({
+     *     ...h,
+     *     balance: h.balance.toString(),
+     *   })),
+     *   dailyHMTData: hmtStatistics.dailyHMTData.map((d) => ({
+     *     ...d,
+     *     totalTransactionAmount: d.totalTransactionAmount.toString(),
+     *   })),
+     * });
+     *
+     * const hmtStatisticsRange = await statisticsClient.getHMTStatistics({
+     *   from: new Date(2023, 4, 8),
+     *   to: new Date(2023, 5, 8),
+     * });
      *
-     * @param {IStatisticsParams} params - Filter parameters.
-     * @returns {Promise<HMTStatistics>}
-     * @throws {Error} - An error object if an error occurred.
+     * console.log('HMT statistics from 5/8 - 6/8:', {
+     *   ...hmtStatisticsRange,
+     *   totalTransferAmount: hmtStatisticsRange.totalTransferAmount.toString(),
+     *   holders: hmtStatisticsRange.holders.map((h) => ({
+     *     ...h,
+     *     balance: h.balance.toString(),
+     *   })),
+     *   dailyHMTData: hmtStatisticsRange.dailyHMTData.map((d) => ({
+     *     ...d,
+     *     totalTransactionAmount: d.totalTransactionAmount.toString(),
+     *   })),
+     * });
+     * ```
      */
     getHMTStatistics(params?: IStatisticsParams): Promise<HMTStatistics>;
 }

package/dist/statistics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"statistics.d.ts","sourceRoot":"","sources":["../src/statistics.ts"],"names":[],"mappings":"AAIA,OAAO,EAKL,gBAAgB,EAGhB,aAAa,EAEb,iBAAiB,EACjB,gBAAgB,EAEjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC,qBAAa,gBAAgB;IACpB,OAAO,EAAE,WAAW,CAAC;IAE5B;;;;OAIG;gBACS,OAAO,EAAE,WAAW;IAIhC;;;;;;OAMG;IACG,mBAAmB,CACvB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,gBAAgB,CAAC;IA6B5B;;;;;;OAMG;IACG,mBAAmB,CACvB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,gBAAgB,CAAC;IAoB5B;;;;;;OAMG;IACG,oBAAoB,CACxB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC;IA2B7B;;;;;;OAMG;IACG,gBAAgB,CACpB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,aAAa,CAAC;CAuC1B"}
+{"version":3,"file":"statistics.d.ts","sourceRoot":"","sources":["../src/statistics.ts"],"names":[],"mappings":"AAIA,OAAO,EAKL,gBAAgB,EAGhB,aAAa,EAEb,iBAAiB,EACjB,gBAAgB,EAEjB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAGtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,gBAAgB;IACpB,OAAO,EAAE,WAAW,CAAC;IAE5B;;;;OAIG;gBACS,OAAO,EAAE,WAAW;IAIhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACG,mBAAmB,CACvB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,gBAAgB,CAAC;IA6B5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACG,mBAAmB,CACvB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,gBAAgB,CAAC;IAoB5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkEG;IACG,oBAAoB,CACxB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,iBAAiB,CAAC;IA2B7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgFG;IACG,gBAAgB,CACpB,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,aAAa,CAAC;CAuC1B"}

package/dist/statistics.js

@@ -9,6 +9,43 @@ const ethers_1 = require("ethers");
 const graphql_request_1 = __importDefault(require("graphql-request"));
 const graphql_1 = require("./graphql");
 const utils_1 = require("./utils");
+/**
+ * ## Introduction
+ *
+ * This client enables to obtain statistical information from the subgraph.
+ *
+ * Unlikely from the other SDK clients, `StatisticsClient` does not require `signer` or `provider` to be provided.
+ * We just need to create client object using relevant network data.
+ *
+ * ```ts
+ * constructor(network: NetworkData)
+ * ```
+ *
+ * A `Signer` or a `Provider` should be passed depending on the use case of this module:
+ *
+ * - **Signer**: when the user wants to use this model in order to send transactions caling the contract functions.
+ * - **Provider**: when the user wants to use this model in order to get information from the contracts or subgraph.
+ *
+ * ## Installation
+ *
+ * ### npm
+ * ```bash
+ * npm install @human-protocol/sdk
+ * ```
+ *
+ * ### yarn
+ * ```bash
+ * yarn install @human-protocol/sdk
+ * ```
+ *
+ * ## Code example
+ *
+ * ```ts
+ * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+ *
+ * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+ * ```
+ */
 class StatisticsClient {
     /**
      * **StatisticsClient constructor**
@@ -19,11 +56,53 @@ class StatisticsClient {
         this.network = network;
     }
     /**
-     * Returns the escrow statistics data for the given date range
+     * This function returns the statistical data of escrows.
      *
-     * @param {IStatisticsParams} params - Filter parameters.
-     * @returns {Promise<EscrowStatistics>}
-     * @throws {Error} - An error object if an error occurred.
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * interface IStatisticsParams {
+     *   from?: Date;
+     *   to?: Date;
+     *   limit?: number;
+     * }
+     * ```
+     *
+     * ```ts
+     * type DailyEscrowsData = {
+     *   timestamp: Date;
+     *   escrowsTotal: number;
+     *   escrowsPending: number;
+     *   escrowsSolved: number;
+     *   escrowsPaid: number;
+     *   escrowsCancelled: number;
+     * };
+     *
+     * type EscrowStatistics = {
+     *   totalEscrows: number;
+     *   dailyEscrowsData: DailyEscrowsData[];
+     * };
+     * ```
+     *
+     *
+     * @param {IStatisticsParams} params Statistics params with duration data
+     * @returns {EscrowStatistics} Escrow statistics data.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+     *
+     * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+     *
+     * const escrowStatistics = await statisticsClient.getEscrowStatistics();
+     * const escrowStatisticsApril = await statisticsClient.getEscrowStatistics({
+     *    from: new Date('2021-04-01'),
+     *    to: new Date('2021-04-30'),
+     * });
+     * ```
      */
     async getEscrowStatistics(params = {}) {
         try {
@@ -49,11 +128,48 @@ class StatisticsClient {
         }
     }
     /**
-     * Returns the worker statistics data for the given date range
+     * This function returns the statistical data of workers.
+     *
+     *
+     * **Input parameters**
      *
-     * @param {IStatisticsParams} params - Filter parameters.
-     * @returns {Promise<WorkerStatistics>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```ts
+     * interface IStatisticsParams {
+     *   from?: Date;
+     *   to?: Date;
+     *   limit?: number;
+     * }
+     * ```
+     *
+     * ```ts
+     * type DailyWorkerData = {
+     *   timestamp: Date;
+     *   activeWorkers: number;
+     * };
+     *
+     * type WorkerStatistics = {
+     *   dailyWorkersData: DailyWorkerData[];
+     * };
+     * ```
+     *
+     *
+     * @param {IStatisticsParams} params Statistics params with duration data
+     * @returns {WorkerStatistics} Worker statistics data.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+     *
+     * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+     *
+     * const workerStatistics = await statisticsClient.getWorkerStatistics();
+     * const workerStatisticsApril = await statisticsClient.getWorkerStatistics({
+     *    from: new Date('2021-04-01'),
+     *    to: new Date('2021-04-30'),
+     * });
+     * ```
      */
     async getWorkerStatistics(params = {}) {
         try {
@@ -73,11 +189,71 @@ class StatisticsClient {
         }
     }
     /**
-     * Returns the payment statistics data for the given date range
+     * This function returns the statistical data of payments.
+     *
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * interface IStatisticsParams {
+     *   from?: Date;
+     *   to?: Date;
+     *   limit?: number;
+     * }
+     * ```
      *
-     * @param {IStatisticsParams} params - Filter parameters.
-     * @returns {Promise<PaymentStatistics>}
-     * @throws {Error} - An error object if an error occurred.
+     * ```ts
+     * type DailyPaymentData = {
+     *   timestamp: Date;
+     *   totalAmountPaid: BigNumber;
+     *   totalCount: number;
+     *   averageAmountPerWorker: BigNumber;
+     * };
+     *
+     * type PaymentStatistics = {
+     *   dailyPaymentsData: DailyPaymentData[];
+     * };
+     * ```
+     *
+     *
+     * @param {IStatisticsParams} params Statistics params with duration data
+     * @returns {PaymentStatistics} Payment statistics data.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+     *
+     * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+     *
+     * 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) => ({
+     *     ...p,
+     *     totalAmountPaid: p.totalAmountPaid.toString(),
+     *     averageAmountPerJob: p.averageAmountPerJob.toString(),
+     *     averageAmountPerWorker: p.averageAmountPerWorker.toString(),
+     *   }))
+     * );
+     * ```
      */
     async getPaymentStatistics(params = {}) {
         try {
@@ -101,11 +277,85 @@ class StatisticsClient {
         }
     }
     /**
-     * Returns the HMToken statistics data for the given date range
+     * This function returns the statistical data of HMToken.
+     *
+     *
+     * **Input parameters**
+     *
+     * ```ts
+     * interface IStatisticsParams {
+     *   from?: Date;
+     *   to?: Date;
+     *   limit?: number;
+     * }
+     * ```
+     *
+     * ```ts
+     * type HMTHolder = {
+     *   address: string;
+     *   balance: BigNumber;
+     * }
+     *
+     * type DailyHMTData = {
+     *   timestamp: Date;
+     *   totalTransactionAmount: BigNumber;
+     *   totalTransactionCount: number;
+     * };
+     *
+     * type HMTStatistics = {
+     *   totalTransferAmount: BigNumber;
+     *   totalTransferCount: BigNumber;
+     *   totalHolders: number;
+     *   holders: HMTHolder[];
+     *   dailyHMTData: DailyHMTData[];
+     * };
+     * ```
+     *
+     *
+     * @param {IStatisticsParams} params Statistics params with duration data
+     * @returns {HMTStatistics} HMToken statistics data.
+     *
+     *
+     * **Code example**
+     *
+     * ```ts
+     * import { StatisticsClient, ChainId, NETWORKS } from '@human-protocol/sdk';
+     *
+     * const statisticsClient = new StatisticsClient(NETWORKS[ChainId.POLYGON_MUMBAI]);
+     *
+     * const hmtStatistics = await statisticsClient.getHMTStatistics();
+     *
+     * console.log('HMT statistics:', {
+     *   ...hmtStatistics,
+     *   totalTransferAmount: hmtStatistics.totalTransferAmount.toString(),
+     *   holders: hmtStatistics.holders.map((h) => ({
+     *     ...h,
+     *     balance: h.balance.toString(),
+     *   })),
+     *   dailyHMTData: hmtStatistics.dailyHMTData.map((d) => ({
+     *     ...d,
+     *     totalTransactionAmount: d.totalTransactionAmount.toString(),
+     *   })),
+     * });
+     *
+     * const hmtStatisticsRange = await statisticsClient.getHMTStatistics({
+     *   from: new Date(2023, 4, 8),
+     *   to: new Date(2023, 5, 8),
+     * });
      *
-     * @param {IStatisticsParams} params - Filter parameters.
-     * @returns {Promise<HMTStatistics>}
-     * @throws {Error} - An error object if an error occurred.
+     * console.log('HMT statistics from 5/8 - 6/8:', {
+     *   ...hmtStatisticsRange,
+     *   totalTransferAmount: hmtStatisticsRange.totalTransferAmount.toString(),
+     *   holders: hmtStatisticsRange.holders.map((h) => ({
+     *     ...h,
+     *     balance: h.balance.toString(),
+     *   })),
+     *   dailyHMTData: hmtStatisticsRange.dailyHMTData.map((d) => ({
+     *     ...d,
+     *     totalTransactionAmount: d.totalTransactionAmount.toString(),
+     *   })),
+     * });
+     * ```
      */
     async getHMTStatistics(params = {}) {
         try {