@human-protocol/sdk 5.1.0 → 6.0.0

package/src/utils.ts

@@ -8,6 +8,7 @@ import { ChainId } from './enums';
 import {
   ContractExecutionError,
   ErrorRetryParametersMissing,
+  ErrorRoutingRequestsToIndexerRequiresApiKey,
   EthereumError,
   InvalidArgumentError,
   NonceExpired,
@@ -20,10 +21,16 @@ import { NetworkData } from './types';
 import { SubgraphOptions } from './interfaces';
 
 /**
- * **Handle and throw the error.*
+ * Handles and throws appropriate error types based on the Ethereum error.
  *
- * @param {any} e
- * @returns
+ * @param e - The error to handle
+ * @throws {InvalidArgumentError} If the error is an invalid argument error
+ * @throws {ContractExecutionError} If the error is a contract execution error
+ * @throws {TransactionReplaced} If the transaction was replaced
+ * @throws {ReplacementUnderpriced} If the replacement transaction was underpriced
+ * @throws {NumericFault} If there's a numeric fault
+ * @throws {NonceExpired} If the nonce has expired
+ * @throws {EthereumError} For any other Ethereum-related error
  */
 export const throwError = (e: any) => {
   if (ethers.isError(e, 'INVALID_ARGUMENT')) {
@@ -44,10 +51,10 @@ export const throwError = (e: any) => {
 };
 
 /**
- * **URL validation.*
+ * Validates if a string is a valid URL.
  *
- * @param {string} url
- * @returns
+ * @param url - The URL string to validate
+ * @returns True if the URL is valid, false otherwise
  */
 export const isValidUrl = (url: string): boolean => {
   return isURL(url, {
@@ -58,10 +65,10 @@ export const isValidUrl = (url: string): boolean => {
 };
 
 /**
- * **Check if a string is a valid JSON.*
+ * Checks if a string is valid JSON.
  *
- * @param {string} input
- * @returns {boolean}
+ * @param input - The string to check
+ * @returns True if the string is valid JSON, false otherwise
  */
 export const isValidJson = (input: string): boolean => {
   try {
@@ -73,10 +80,10 @@ export const isValidJson = (input: string): boolean => {
 };
 
 /**
- * **Get the subgraph URL.*
+ * Gets the subgraph URL for the given network, using API key if available.
  *
- * @param {NetworkData} networkData
- * @returns
+ * @param networkData - The network data containing subgraph URLs
+ * @returns The subgraph URL with API key if available
  */
 export const getSubgraphUrl = (networkData: NetworkData) => {
   let subgraphUrl = networkData.subgraphUrl;
@@ -94,10 +101,10 @@ export const getSubgraphUrl = (networkData: NetworkData) => {
 };
 
 /**
- * **Convert a date to Unix timestamp (seconds since epoch).*
+ * Converts a Date object to Unix timestamp (seconds since epoch).
  *
- * @param {Date} date
- * @returns {number}
+ * @param date - The date to convert
+ * @returns Unix timestamp in seconds
  */
 export const getUnixTimestamp = (date: Date): number => {
   return Math.floor(date.getTime() / 1000);
@@ -118,9 +125,24 @@ const sleep = (ms: number): Promise<void> => {
   return new Promise((resolve) => setTimeout(resolve, ms));
 };
 
+const buildIndexerUrl = (baseUrl: string, indexerId?: string): string => {
+  if (!indexerId) {
+    return baseUrl;
+  }
+  return `${baseUrl}/indexers/id/${indexerId}`;
+};
+
 /**
- * Execute a GraphQL request with automatic retry logic for bad indexer errors.
- * Only retries if options is provided.
+ * Executes a GraphQL request with automatic retry logic for bad indexer errors.
+ * Only retries if options is provided with maxRetries and baseDelay.
+ *
+ * @param url - The GraphQL endpoint URL
+ * @param query - The GraphQL query to execute
+ * @param variables - Variables for the GraphQL query (optional)
+ * @param options - Optional configuration for subgraph requests including retry logic
+ * @returns The response data from the GraphQL query
+ * @throws ErrorRetryParametersMissing If only one of maxRetries or baseDelay is provided
+ * @throws ErrorRoutingRequestsToIndexerRequiresApiKey If indexerId is provided without API key
  */
 export const customGqlFetch = async <T = any>(
   url: string,
@@ -128,35 +150,44 @@ export const customGqlFetch = async <T = any>(
   variables?: any,
   options?: SubgraphOptions
 ): Promise<T> => {
+  const apiKey = process.env.SUBGRAPH_API_KEY;
+  const headers = apiKey
+    ? {
+        Authorization: `Bearer ${apiKey}`,
+      }
+    : undefined;
+
   if (!options) {
-    return await gqlFetch<T>(url, query, variables);
+    return await gqlFetch<T>(url, query, variables, headers);
   }
 
-  if (
-    (options.maxRetries && options.baseDelay === undefined) ||
-    (options.baseDelay && options.maxRetries === undefined)
-  ) {
+  const hasMaxRetries = options.maxRetries !== undefined;
+  const hasBaseDelay = options.baseDelay !== undefined;
+
+  if (hasMaxRetries !== hasBaseDelay) {
     throw ErrorRetryParametersMissing;
   }
+  if (options.indexerId && !headers) {
+    throw ErrorRoutingRequestsToIndexerRequiresApiKey;
+  }
+
+  const targetUrl = buildIndexerUrl(url, options.indexerId);
 
+  const maxRetries = hasMaxRetries ? (options.maxRetries as number) : 0;
+  const baseDelay = hasBaseDelay ? (options.baseDelay as number) : 0;
   let lastError: any;
 
-  for (let attempt = 0; attempt <= (options.maxRetries as number); attempt++) {
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
     try {
-      const result = await gqlFetch<T>(url, query, variables);
-      return result;
+      return await gqlFetch<T>(targetUrl, query, variables, headers);
     } catch (error) {
       lastError = error;
 
-      if (attempt === options.maxRetries) {
-        throw error;
-      }
-
-      if (!isIndexerError(error)) {
+      if (attempt === maxRetries || !isIndexerError(error)) {
         throw error;
       }
 
-      const delay = (options.baseDelay as number) * attempt;
+      const delay = baseDelay * attempt;
       await sleep(delay);
     }
   }

package/src/worker.ts

@@ -7,21 +7,40 @@ import { GET_WORKER_QUERY, GET_WORKERS_QUERY } from './graphql/queries/worker';
 import { IWorker, IWorkersFilter, SubgraphOptions } from './interfaces';
 import { getSubgraphUrl, customGqlFetch } from './utils';
 
+/**
+ * Utility class for worker-related operations.
+ *
+ * @example
+ * ```ts
+ * import { WorkerUtils, ChainId } from '@human-protocol/sdk';
+ *
+ * const worker = await WorkerUtils.getWorker(
+ *   ChainId.POLYGON_AMOY,
+ *   '0x1234567890abcdef1234567890abcdef12345678'
+ * );
+ * console.log('Worker:', worker);
+ * ```
+ */
 export class WorkerUtils {
   /**
    * This function returns the worker data for the given address.
    *
-   * @param {ChainId} chainId The chain ID.
-   * @param {string} address The worker address.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IWorker | null>} - Returns the worker details or null if not found.
-   *
-   * **Code example**
+   * @param chainId - The chain ID.
+   * @param address - The worker address.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Returns the worker details or null if not found.
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
+   * @throws ErrorInvalidAddress If the address is invalid
    *
+   * @example
    * ```ts
    * import { WorkerUtils, ChainId } from '@human-protocol/sdk';
    *
-   * const worker = await WorkerUtils.getWorker(ChainId.POLYGON, '0x1234567890abcdef1234567890abcdef12345678');
+   * const worker = await WorkerUtils.getWorker(
+   *   ChainId.POLYGON_AMOY,
+   *   '0x1234567890abcdef1234567890abcdef12345678'
+   * );
+   * console.log('Worker:', worker);
    * ```
    */
   public static async getWorker(
@@ -79,21 +98,23 @@ export class WorkerUtils {
    * };
    * ```
    *
-   * @param {IWorkersFilter} filter Filter for the workers.
-   * @param {SubgraphOptions} options Optional configuration for subgraph requests.
-   * @returns {Promise<IWorker[]>} Returns an array with all the worker details.
-   *
-   * **Code example**
+   * @param filter - Filter for the workers.
+   * @param options - Optional configuration for subgraph requests.
+   * @returns Returns an array with all the worker details.
+   * @throws ErrorUnsupportedChainID If the chain ID is not supported
+   * @throws ErrorInvalidAddress If the filter address is invalid
    *
+   * @example
    * ```ts
    * import { WorkerUtils, ChainId } from '@human-protocol/sdk';
    *
-   * const filter: IWorkersFilter = {
-   *   chainId: ChainId.POLYGON,
+   * const filter = {
+   *   chainId: ChainId.POLYGON_AMOY,
    *   first: 10,
    *   skip: 0,
    * };
    * const workers = await WorkerUtils.getWorkers(filter);
+   * console.log('Workers:', workers.length);
    * ```
    */
   public static async getWorkers(

package/dist/storage.d.ts

@@ -1,186 +0,0 @@
-import { UploadFile, StorageCredentials, StorageParams } from './types';
-/**
- *
- * @deprecated StorageClient is deprecated. Use Minio.Client directly.
- *
- * ## Introduction
- *
- * This client enables interacting 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 are not provided, it uses 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;
-    private clientParams;
-    /**
-     * **Storage client constructor**
-     *
-     * @param {StorageParams} params - Cloud storage params
-     * @param {StorageCredentials} credentials - Optional. Cloud storage access data. If credentials are not provided - use anonymous access to the bucket
-     */
-    constructor(params: StorageParams, credentials?: StorageCredentials);
-    /**
-     * This function downloads files from a bucket.
-     *
-     * @param {string[]} keys Array of filenames to download.
-     * @param {string} bucket Bucket name.
-     * @returns {Promise<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[]>;
-    /**
-     * This function downloads files from a URL.
-     *
-     * @param {string} url URL of the file to download.
-     * @returns {Promise<any>} Returns the JSON file downloaded and parsed into an object.
-     *
-     * **Code example**
-     *
-     * ```ts
-     * import { StorageClient } from '@human-protocol/sdk';
-     *
-     * const file = await StorageClient.downloadFileFromUrl('http://localhost/file.json');
-     * ```
-     */
-    static downloadFileFromUrl(url: string): Promise<any>;
-    /**
-     * This function uploads files to a bucket.
-     *
-     * @param {any[]} files Array of objects to upload serialized into JSON.
-     * @param {string} bucket Bucket name.
-     * @returns {Promise<UploadFile[]>} Returns an array of uploaded file metadata.
-     *
-     * **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);
-     * 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[]>;
-    /**
-     * This function checks if a bucket exists.
-     *
-     * @param {string} bucket Bucket name.
-     * @returns {Promise<boolean>} Returns `true` if exists, `false` if it doesn't.
-     *
-     * **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);
-     * const exists = await storageClient.bucketExists('bucket-name');
-     * ```
-     */
-    bucketExists(bucket: string): Promise<boolean>;
-    /**
-     * This function lists all file names contained in the bucket.
-     *
-     * @param {string} bucket Bucket name.
-     * @returns {Promise<string[]>} 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'
-     * };
-     *
-     * const storageClient = new StorageClient(params, credentials);
-     * const fileNames = await storageClient.listObjects('bucket-name');
-     * ```
-     */
-    listObjects(bucket: string): Promise<string[]>;
-}
-//# sourceMappingURL=storage.d.ts.map

package/dist/storage.d.ts.map

@@ -1 +0,0 @@
-{"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;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACU,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAoB1E;;;;;;;;;;;;;OAaG;WACiB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAsBlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACU,WAAW,CACtB,KAAK,EAAE,GAAG,EAAE,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,UAAU,EAAE,CAAC;IAmCxB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI3D;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACU,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CAqB5D"}