@human-protocol/sdk 1.1.13 → 1.1.15

package/src/statistics.ts

@@ -20,6 +20,43 @@ import { IStatisticsParams } from './interfaces';
 import { NetworkData } from './types';
 import { throwError } from './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]);
+ * ```
+ */
 export class StatisticsClient {
   public network: NetworkData;
 
@@ -33,11 +70,53 @@ export class StatisticsClient {
   }
 
   /**
-   * 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: IStatisticsParams = {}
@@ -71,11 +150,48 @@ export 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: IStatisticsParams = {}
@@ -100,11 +216,71 @@ export 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: IStatisticsParams = {}
@@ -136,11 +312,85 @@ export 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: IStatisticsParams = {}

package/src/storage.ts

@@ -14,7 +14,51 @@ import { isValidUrl } from './utils';
 import { HttpStatus } from './constants';
 
 /**
+ *
  * @deprecated StorageClient is deprecated. Use Minio.Client directly.
+ *
+ * ## Introduction
+ *
+ * This client enables to interact with S3 cloud storage services like Amazon S3 Bucket, Google Cloud Storage and others.
+ *
+ * The instance creation of `StorageClient` should be made using its constructor:
+ *
+ * ```ts
+ * constructor(params: StorageParams, credentials?: StorageCredentials)
+ * ```
+ *
+ * > If credentials is not provided, it uses an anonymous access to the bucket for downloading files.
+ *
+ * ## Installation
+ *
+ * ### npm
+ * ```bash
+ * npm install @human-protocol/sdk
+ * ```
+ *
+ * ### yarn
+ * ```bash
+ * yarn install @human-protocol/sdk
+ * ```
+ *
+ * ## Code example
+ *
+ * ```ts
+ * import { StorageClient, StorageCredentials, StorageParams } from '@human-protocol/sdk';
+ *
+ * const credentials: StorageCredentials = {
+ *   accessKey: 'ACCESS_KEY',
+ *   secretKey: 'SECRET_KEY',
+ * };
+ * const params: StorageParams = {
+ *   endPoint: 'http://localhost',
+ *   port: 9000,
+ *   useSSL: false,
+ *   region: 'us-east-1'
+ * };
+ *
+ * const storageClient = new StorageClient(params, credentials);
+ * ```
  */
 export class StorageClient {
   private client: Minio.Client;
@@ -41,10 +85,30 @@ export class StorageClient {
   }
 
   /**
-   * **Download files from cloud storage**
+   * This function downloads files from a bucket.
    *
-   * @param {string} keys - Keys of files
-   * @returns {Promise<File>} - Downloaded file
+   * @param {string[]} keys Array of filenames to download.
+   * @param {string} bucket Bucket name.
+   * @returns {any[]} Returns an array of json files downloaded and parsed into objects.
+   *
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { StorageClient, StorageCredentials, StorageParams } from '@human-protocol/sdk';
+   *
+   * const params: StorageParams = {
+   *   endPoint: 'http://localhost',
+   *   port: 9000,
+   *   useSSL: false,
+   *   region: 'us-east-1'
+   * };
+   *
+   * const storageClient = new StorageClient(params);
+   *
+   * const keys = ['file1.json', 'file2.json'];
+   * const files = await storageClient.downloadFiles(keys, 'bucket-name');
+   * ```
    */
   public async downloadFiles(keys: string[], bucket: string): Promise<any[]> {
     const isBucketExists = await this.client.bucketExists(bucket);
@@ -67,10 +131,19 @@ export class StorageClient {
   }
 
   /**
-   * **Download files from cloud storage.*
+   * This function downloads files from a Url.
+   *
+   * @param {string} url Url of the file to download.
+   * @returns {any} Returns the JSON file downloaded and parsed into object.
    *
-   * @param {string} url - URL to the file
-   * @returns {Promise<File>} - Downloaded file
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { StorageClient } from '@human-protocol/sdk';
+   *
+   * const file = await storageClient.downloadFileFromUrl('http://localhost/file.json');
+   * ```
    */
   public static async downloadFileFromUrl(url: string): Promise<any> {
     if (!isValidUrl(url)) {
@@ -95,11 +168,35 @@ export class StorageClient {
   }
 
   /**
-   * **Upload file to cloud storage**
+   * This function uploads files to a bucket.
+   *
+   * @param {any[]} files Array of objects to upload serialized into json.
+   * @param {string} bucket Bucket name.
+   * @returns {UploadFile[]} Returns an array of json files downloaded and parsed into objects.
+   *
+   *
+   * **Code example**
    *
-   * @param {File[]} files - Files to upload
-   * @param {string} bucket - Bucket name
-   * @returns {Promise<UploadFile>} - Uploaded file with key/hash
+   * ```ts
+   * import { StorageClient, StorageCredentials, StorageParams } from '@human-protocol/sdk';
+   *
+   * const credentials: StorageCredentials = {
+   *   accessKey: 'ACCESS_KEY',
+   *   secretKey: 'SECRET_KEY',
+   * };
+   * const params: StorageParams = {
+   *   endPoint: 'http://localhost',
+   *   port: 9000,
+   *   useSSL: false,
+   *   region: 'us-east-1'
+   * };
+   *
+   * const storageClient = new StorageClient(params, credentials);
+   * const file1 = { name: 'file1', description: 'description of file1' };
+   * const file2 = { name: 'file2', description: 'description of file2' };
+   * const files = [file1, file2];
+   * const uploadedFiles = await storageClient.uploadFiles(files, 'bucket-name');
+   * ```
    */
   public async uploadFiles(
     files: any[],
@@ -139,20 +236,62 @@ export class StorageClient {
   }
 
   /**
-   * **Checks if a bucket exists**
+   * This function checks if a bucket exists.
+   *
+   * @param {string} bucket Bucket name.
+   * @returns {boolean} Returns `true` if exists, `false` if it doesn't.
+   *
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { StorageClient, StorageCredentials, StorageParams } from '@human-protocol/sdk';
    *
-   * @param {string} bucket - Name of the bucket
-   * @returns {Promise<boolean>} - True if bucket exists, false otherwise
+   * const credentials: StorageCredentials = {
+   *   accessKey: 'ACCESS_KEY',
+   *   secretKey: 'SECRET_KEY',
+   * };
+   * const params: StorageParams = {
+   *   endPoint: 'http://localhost',
+   *   port: 9000,
+   *   useSSL: false,
+   *   region: 'us-east-1'
+   * };
+   *
+   * const storageClient = new StorageClient(params, credentials);
+   * const exists = await storageClient.bucketExists('bucket-name');
+   * ```
    */
   public async bucketExists(bucket: string): Promise<boolean> {
     return this.client.bucketExists(bucket);
   }
 
   /**
-   * **Checks if a bucket exists**
+   * This function list all file names contained in the bucket.
+   *
+   * @param {string} bucket Bucket name.
+   * @returns {boolean} Returns the list of file names contained in the bucket.
+   *
+   *
+   * **Code example**
+   *
+   * ```ts
+   * import { StorageClient, StorageCredentials, StorageParams } from '@human-protocol/sdk';
+   *
+   * const credentials: StorageCredentials = {
+   *   accessKey: 'ACCESS_KEY',
+   *   secretKey: 'SECRET_KEY',
+   * };
+   * const params: StorageParams = {
+   *   endPoint: 'http://localhost',
+   *   port: 9000,
+   *   useSSL: false,
+   *   region: 'us-east-1'
+   * };
    *
-   * @param {string} bucket - Name of the bucket
-   * @returns {Promise<string[]>} - A list of filenames with their extensions in the bucket
+   * const storageClient = new StorageClient(params, credentials);
+   * const fileNames = await storageClient.listObjects('bucket-name');
+   * ```
    */
   public async listObjects(bucket: string): Promise<string[]> {
     const isBucketExists = await this.client.bucketExists(bucket);
@@ -165,7 +304,7 @@ export class StorageClient {
         const keys: string[] = [];
         const stream = this.client.listObjectsV2(bucket, '', true, '');
 
-        stream.on('data', (obj) => keys.push(obj.name));
+        stream.on('data', (obj: { name: string }) => keys.push(obj.name));
         stream.on('error', reject);
         stream.on('end', () => {
           resolve(keys);