@human-protocol/sdk 1.1.13 → 1.1.15

package/dist/kvstore.d.ts

@@ -1,6 +1,75 @@
 import { Provider } from '@ethersproject/abstract-provider';
 import { Signer } from 'ethers';
 import { NetworkData } from './types';
+/**
+ * ## Introduction
+ *
+ * This client enables to perform actions on KVStore contract and obtain information from both the contracts and subgraph.
+ *
+ * Internally, the SDK will use one network or another according to the network ID of the `signerOrProvider`.
+ * To use this client, it is recommended to initialize it using the static `build` method.
+ *
+ * ```ts
+ * static async build(signerOrProvider: Signer | Provider);
+ * ```
+ *
+ * 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
+ *
+ * ### Signer
+ *
+ * **Using private key(backend)**
+ *
+ * ```ts
+ * import { KVStoreClient } from '@human-protocol/sdk';
+ * import { Wallet, providers } from 'ethers';
+ *
+ * const rpcUrl = 'YOUR_RPC_URL';
+ * const privateKey = 'YOUR_PRIVATE_KEY'
+ *
+ * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const signer = new Wallet(privateKey, provider);
+ * const kvstoreClient = await KVStoreClient.build(signer);
+ * ```
+ *
+ * **Using Wagmi(frontend)**
+ *
+ * ```ts
+ * import { useSigner, useChainId } from 'wagmi';
+ * import { KVStoreClient } from '@human-protocol/sdk';
+ *
+ * const { data: signer } = useSigner();
+ * const kvstoreClient = await KVStoreClient.build(signer);
+ * ```
+ *
+ * ### Provider
+ *
+ * ```ts
+ * import { KVStoreClient } from '@human-protocol/sdk';
+ * import { providers } from 'ethers';
+ *
+ * const rpcUrl = 'YOUR_RPC_URL';
+ *
+ * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const kvstoreClient = await KVStoreClient.build(signer);
+ * ```
+ */
 export declare class KVStoreClient {
     private contract;
     private signerOrProvider;
@@ -21,30 +90,84 @@ export declare class KVStoreClient {
      */
     static build(signerOrProvider: Signer | Provider): Promise<KVStoreClient>;
     /**
-     * Sets a key-value pair in the contract
+     * This function sets a key-value pair associated with the address that submits the transaction.
      *
-     * @param {string} key - The key of the key-value pair to set
-     * @param {string} value - The value of the key-value pair to set
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred
+     * @param {string} key Key of the key-value pair
+     * @param {string} value Value of the key-value pair
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
+     *
+     * > Need to have available stake.
+     *
+     * ```ts
+     * import { Wallet, providers } from 'ethers';
+     * import { KVStoreClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     * const privateKey = 'YOUR_PRIVATE_KEY'
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const signer = new Wallet(privateKey, provider);
+     * const kvstoreClient = await KVStoreClient.build(signer);
+     *
+     * await kvstoreClient.set('Role', 'RecordingOracle');
+     * ```
      */
     set(key: string, value: string): Promise<void>;
     /**
-     * Sets multiple key-value pairs in the contract
+     * This function sets key-value pairs in bulk associated with the address that submits the transaction.
+     *
+     * @param {string[]} keys Array of keys (keys and value must have the same order)
+     * @param {string[]} values Array of values
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
+     *
+     * > Need to have available stake.
      *
-     * @param {string[]} keys - An array of keys to set
-     * @param {string[]} values - An array of values to set
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred
+     * ```ts
+     * import { Wallet, providers } from 'ethers';
+     * import { KVStoreClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     * const privateKey = 'YOUR_PRIVATE_KEY'
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const signer = new Wallet(privateKey, provider);
+     * const kvstoreClient = await KVStoreClient.build(signer);
+     *
+     * const keys = ['Role', 'Webhook_url'];
+     * const values = ['RecordingOracle', 'http://localhost'];
+     * await kvstoreClient.set(keys, values);
+     * ```
      */
     setBulk(keys: string[], values: string[]): Promise<void>;
     /**
-     * Gets the value of a key-value pair in the contract
+     * This function returns the value for a specified key and address.
+     *
+     * @param {string} address Address from which to get the key value.
+     * @param {string} key Key to obtain the value.
+     * @returns {string} Value of the key.
+     *
+     *
+     * **Code example**
+     *
+     * > Need to have available stake.
+     *
+     * ```ts
+     * import { providers } from 'ethers';
+     * import { KVStoreClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const kvstoreClient = await KVStoreClient.build(provider);
      *
-     * @param {string} address - The Ethereum address associated with the key-value pair
-     * @param {string} key - The key of the key-value pair to get
-     * @returns {Promise<string>} - The value of the key-value pair if it exists
-     * @throws {Error} - An error object if an error occurred
+     * const value = await kvstoreClient.get('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', 'Role');
+     * ```
      */
     get(address: string, key: string): Promise<string>;
 }

package/dist/kvstore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kvstore.d.ts","sourceRoot":"","sources":["../src/kvstore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAM5D,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AAYxC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,gBAAgB,CAAoB;IAE5C;;;;;OAKG;gBACS,gBAAgB,EAAE,MAAM,GAAG,QAAQ,EAAE,OAAO,EAAE,WAAW;IAQrE;;;;;;;OAOG;WACiB,KAAK,CAAC,gBAAgB,EAAE,MAAM,GAAG,QAAQ;IAsB7D;;;;;;;OAOG;IAEU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3D;;;;;;;OAOG;IAEU,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAarE;;;;;;;OAOG;IACU,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAYhE"}
+{"version":3,"file":"kvstore.d.ts","sourceRoot":"","sources":["../src/kvstore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAM5D,OAAO,EAAE,MAAM,EAAU,MAAM,QAAQ,CAAC;AAYxC,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,gBAAgB,CAAoB;IAE5C;;;;;OAKG;gBACS,gBAAgB,EAAE,MAAM,GAAG,QAAQ,EAAE,OAAO,EAAE,WAAW;IAQrE;;;;;;;OAOG;WACiB,KAAK,CAAC,gBAAgB,EAAE,MAAM,GAAG,QAAQ;IAsB7D;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IAEU,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU3D;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IAEU,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAarE;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAYhE"}

package/dist/kvstore.js

@@ -15,6 +15,75 @@ const ethers_1 = require("ethers");
 const constants_1 = require("./constants");
 const decorators_1 = require("./decorators");
 const error_1 = require("./error");
+/**
+ * ## Introduction
+ *
+ * This client enables to perform actions on KVStore contract and obtain information from both the contracts and subgraph.
+ *
+ * Internally, the SDK will use one network or another according to the network ID of the `signerOrProvider`.
+ * To use this client, it is recommended to initialize it using the static `build` method.
+ *
+ * ```ts
+ * static async build(signerOrProvider: Signer | Provider);
+ * ```
+ *
+ * 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
+ *
+ * ### Signer
+ *
+ * **Using private key(backend)**
+ *
+ * ```ts
+ * import { KVStoreClient } from '@human-protocol/sdk';
+ * import { Wallet, providers } from 'ethers';
+ *
+ * const rpcUrl = 'YOUR_RPC_URL';
+ * const privateKey = 'YOUR_PRIVATE_KEY'
+ *
+ * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const signer = new Wallet(privateKey, provider);
+ * const kvstoreClient = await KVStoreClient.build(signer);
+ * ```
+ *
+ * **Using Wagmi(frontend)**
+ *
+ * ```ts
+ * import { useSigner, useChainId } from 'wagmi';
+ * import { KVStoreClient } from '@human-protocol/sdk';
+ *
+ * const { data: signer } = useSigner();
+ * const kvstoreClient = await KVStoreClient.build(signer);
+ * ```
+ *
+ * ### Provider
+ *
+ * ```ts
+ * import { KVStoreClient } from '@human-protocol/sdk';
+ * import { providers } from 'ethers';
+ *
+ * const rpcUrl = 'YOUR_RPC_URL';
+ *
+ * const provider = new providers.JsonRpcProvider(rpcUrl);
+ * const kvstoreClient = await KVStoreClient.build(signer);
+ * ```
+ */
 class KVStoreClient {
     /**
      * **KVStoreClient constructor**
@@ -53,12 +122,30 @@ class KVStoreClient {
         return new KVStoreClient(signerOrProvider, networkData);
     }
     /**
-     * Sets a key-value pair in the contract
+     * This function sets a key-value pair associated with the address that submits the transaction.
      *
-     * @param {string} key - The key of the key-value pair to set
-     * @param {string} value - The value of the key-value pair to set
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred
+     * @param {string} key Key of the key-value pair
+     * @param {string} value Value of the key-value pair
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
+     *
+     * > Need to have available stake.
+     *
+     * ```ts
+     * import { Wallet, providers } from 'ethers';
+     * import { KVStoreClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     * const privateKey = 'YOUR_PRIVATE_KEY'
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const signer = new Wallet(privateKey, provider);
+     * const kvstoreClient = await KVStoreClient.build(signer);
+     *
+     * await kvstoreClient.set('Role', 'RecordingOracle');
+     * ```
      */
     async set(key, value) {
         if (!ethers_1.Signer.isSigner(this.signerOrProvider))
@@ -74,12 +161,32 @@ class KVStoreClient {
         }
     }
     /**
-     * Sets multiple key-value pairs in the contract
+     * This function sets key-value pairs in bulk associated with the address that submits the transaction.
+     *
+     * @param {string[]} keys Array of keys (keys and value must have the same order)
+     * @param {string[]} values Array of values
+     * @returns Returns void if successful. Throws error if any.
+     *
+     *
+     * **Code example**
+     *
+     * > Need to have available stake.
      *
-     * @param {string[]} keys - An array of keys to set
-     * @param {string[]} values - An array of values to set
-     * @returns {Promise<void>}
-     * @throws {Error} - An error object if an error occurred
+     * ```ts
+     * import { Wallet, providers } from 'ethers';
+     * import { KVStoreClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     * const privateKey = 'YOUR_PRIVATE_KEY'
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const signer = new Wallet(privateKey, provider);
+     * const kvstoreClient = await KVStoreClient.build(signer);
+     *
+     * const keys = ['Role', 'Webhook_url'];
+     * const values = ['RecordingOracle', 'http://localhost'];
+     * await kvstoreClient.set(keys, values);
+     * ```
      */
     async setBulk(keys, values) {
         if (!ethers_1.Signer.isSigner(this.signerOrProvider))
@@ -97,12 +204,28 @@ class KVStoreClient {
         }
     }
     /**
-     * Gets the value of a key-value pair in the contract
+     * This function returns the value for a specified key and address.
+     *
+     * @param {string} address Address from which to get the key value.
+     * @param {string} key Key to obtain the value.
+     * @returns {string} Value of the key.
+     *
+     *
+     * **Code example**
+     *
+     * > Need to have available stake.
+     *
+     * ```ts
+     * import { providers } from 'ethers';
+     * import { KVStoreClient } from '@human-protocol/sdk';
+     *
+     * const rpcUrl = 'YOUR_RPC_URL';
+     *
+     * const provider = new providers.JsonRpcProvider(rpcUrl);
+     * const kvstoreClient = await KVStoreClient.build(provider);
      *
-     * @param {string} address - The Ethereum address associated with the key-value pair
-     * @param {string} key - The key of the key-value pair to get
-     * @returns {Promise<string>} - The value of the key-value pair if it exists
-     * @throws {Error} - An error object if an error occurred
+     * const value = await kvstoreClient.get('0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266', 'Role');
+     * ```
      */
     async get(address, key) {
         if (key === '')