@human-protocol/sdk 1.1.13 → 1.1.15

package/dist/storage.d.ts

@@ -1,6 +1,50 @@
 import { UploadFile, StorageCredentials, StorageParams } from './types';
 /**
+ *
  * @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 declare class StorageClient {
     private client;
@@ -13,39 +57,134 @@ export declare class StorageClient {
      */
     constructor(params: StorageParams, credentials?: StorageCredentials);
     /**
-     * **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');
+     * ```
      */
     downloadFiles(keys: string[], bucket: string): Promise<any[]>;
     /**
-     * **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');
+     * ```
      */
     static downloadFileFromUrl(url: string): Promise<any>;
     /**
-     * **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');
+     * ```
      */
     uploadFiles(files: any[], bucket: string): Promise<UploadFile[]>;
     /**
-     * **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');
+     * ```
      */
     bucketExists(bucket: string): Promise<boolean>;
     /**
-     * **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');
+     * ```
      */
     listObjects(bucket: string): Promise<string[]>;
 }

package/dist/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAIxE;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAgB;IAEpC;;;;;OAKG;gBACS,MAAM,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,kBAAkB;IAcnE;;;;;OAKG;IACU,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAoB1E;;;;;OAKG;WACiB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAsBlE;;;;;;OAMG;IACU,WAAW,CACtB,KAAK,EAAE,GAAG,EAAE,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC;IAkCxB;;;;;OAKG;IACU,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3D;;;;;OAKG;IACU,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAqB5D"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAIxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,YAAY,CAAgB;IAEpC;;;;;OAKG;gBACS,MAAM,EAAE,aAAa,EAAE,WAAW,CAAC,EAAE,kBAAkB;IAcnE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAoB1E;;;;;;;;;;;;;;OAcG;WACiB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAsBlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACU,WAAW,CACtB,KAAK,EAAE,GAAG,EAAE,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC;IAkCxB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3D;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACU,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAqB5D"}

package/dist/storage.js

@@ -35,7 +35,51 @@ const error_1 = require("./error");
 const utils_1 = require("./utils");
 const constants_1 = require("./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);
+ * ```
  */
 class StorageClient {
     /**
@@ -58,10 +102,30 @@ 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');
+     * ```
      */
     async downloadFiles(keys, bucket) {
         const isBucketExists = await this.client.bucketExists(bucket);
@@ -80,10 +144,19 @@ 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');
+     * ```
      */
     static async downloadFileFromUrl(url) {
         if (!(0, utils_1.isValidUrl)(url)) {
@@ -105,11 +178,35 @@ 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');
+     * ```
      */
     async uploadFiles(files, bucket) {
         const isBucketExists = await this.client.bucketExists(bucket);
@@ -136,19 +233,61 @@ 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');
+     * ```
      */
     async bucketExists(bucket) {
         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');
+     * ```
      */
     async listObjects(bucket) {
         const isBucketExists = await this.client.bucketExists(bucket);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@human-protocol/sdk",
   "description": "Human Protocol SDK",
-  "version": "1.1.13",
+  "version": "1.1.15",
   "files": [
     "src",
     "dist"
@@ -10,8 +10,10 @@
   "types": "dist/index.d.ts",
   "scripts": {
     "clean": "rm -rf ./dist",
+    "clean:doc": "rm -rf ../../../../docs/sdk/typescript/",
     "prebuild": "yarn workspace @human-protocol/core build",
     "build": "npm run clean && tsc",
+    "build:doc": "npm run clean:doc && npx typedoc --plugin typedoc-plugin-markdown --out ../../../../docs/sdk/typescript/",
     "prepublish": "npm run build",
     "test": "vitest -u",
     "lint": "eslint .",
@@ -49,5 +51,19 @@
     "secp256k1": "^4.0.3",
     "vitest": "^0.30.1",
     "winston": "^3.8.2"
+  },
+  "devDependencies": {
+    "typedoc": "^0.25.1",
+    "typedoc-plugin-markdown": "^3.16.0"
+  },
+  "typedocOptions": {
+    "entryPoints": [
+      "./src/encryption.ts",
+      "./src/escrow.ts",
+      "./src/kvstore.ts",
+      "./src/staking.ts",
+      "./src/storage.ts",
+      "./src/statistics.ts"
+    ]
   }
 }