@pythnetwork/hermes-client 2.0.0 → 2.1.0

package/README.md

@@ -9,13 +9,13 @@ This library is a client for interacting with Hermes, allowing your application
 ### npm
 
 ```
-$ npm install --save @pythnetwork/hermes-client
+npm install --save @pythnetwork/hermes-client
 ```
 
 ### Yarn
 
 ```
-$ yarn add @pythnetwork/hermes-client
+yarn add @pythnetwork/hermes-client
 ```
 
 ## Quickstart
@@ -76,11 +76,12 @@ The [HermesClient](./src/examples/HermesClient.ts) example demonstrates both the
 examples above. To run the example:
 
 1. Clone [the Pyth monorepo](https://github.com/pyth-network/pyth-crosschain)
-2. In the root of the monorepo, run `pnpm example:hermes-client -- <args>`. For
-   example, to print BTC and ETH price feeds in the testnet network, run:
+2. In the root of the monorepo, run `pnpm turbo --filter
+   @pythnetwork/hermes-client example -- <args>`. For example, to print BTC and
+   ETH price feeds in the testnet network, run:
 
 ```bash
-pnpm example:hermes-client -- \
+pnpm turbo --filter @pythnetwork/hermes-client example -- \
   --endpoint https://hermes.pyth.network \
   --price-ids \
     0xe62df6c8b4a85fe1a67db44dc12de5db330f7ac66b72dc658afedf0f4a415b43 \

package/dist/cjs/hermes-client.cjs

@@ -0,0 +1,220 @@
+/* eslint-disable @typescript-eslint/require-await */ /* eslint-disable @typescript-eslint/no-misused-spread */ /* eslint-disable @typescript-eslint/no-unsafe-assignment */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "HermesClient", {
+    enumerable: true,
+    get: function() {
+        return HermesClient;
+    }
+});
+const _eventsource = require("eventsource");
+const _utils = require("./utils.cjs");
+const _zodSchemas = require("./zodSchemas.cjs");
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_HTTP_RETRIES = 3;
+class HermesClient {
+    baseURL;
+    timeout;
+    httpRetries;
+    headers;
+    /**
+   * Constructs a new Connection.
+   *
+   * @param endpoint - endpoint URL to the price service. Example: https://website/example/
+   * @param config - Optional HermesClientConfig for custom configurations.
+   */ constructor(endpoint, config){
+        this.baseURL = endpoint;
+        this.timeout = config?.timeout ?? DEFAULT_TIMEOUT;
+        this.httpRetries = config?.httpRetries ?? DEFAULT_HTTP_RETRIES;
+        this.headers = config?.headers ?? {};
+    }
+    async httpRequest(url, schema, options, retries = this.httpRetries, backoff = 100 + Math.floor(Math.random() * 100)) {
+        try {
+            const response = await fetch(url, {
+                ...options,
+                signal: AbortSignal.any([
+                    ...options?.signal ? [
+                        options.signal
+                    ] : [],
+                    AbortSignal.timeout(this.timeout)
+                ]),
+                headers: {
+                    ...this.headers,
+                    ...options?.headers
+                }
+            });
+            if (!response.ok) {
+                const errorBody = await response.text();
+                throw new Error(`HTTP error! status: ${response.status.toString()}${errorBody ? `, body: ${errorBody}` : ""}`);
+            }
+            const data = await response.json();
+            return schema.parse(data);
+        } catch (error) {
+            if (retries > 0 && !(error instanceof Error && error.name === "AbortError")) {
+                // Wait for a backoff period before retrying
+                await new Promise((resolve)=>setTimeout(resolve, backoff));
+                return this.httpRequest(url, schema, options, retries - 1, backoff * 2); // Exponential backoff
+            }
+            throw error;
+        }
+    }
+    /**
+   * Fetch the set of available price feeds.
+   * This endpoint can be filtered by asset type and query string.
+   * This will throw an error if there is a network problem or the price service returns a non-ok response.
+   *
+   * @param options - Optional parameters:
+   *        - query: String to filter the price feeds. If provided, the results will be filtered to all price feeds whose symbol contains the query string. Query string is case insensitive. Example: "bitcoin".
+   *        - assetType: String to filter the price feeds by asset type. Possible values are "crypto", "equity", "fx", "metal", "rates", "crypto_redemption_rate". Filter string is case insensitive.
+   *
+   * @returns Array of PriceFeedMetadata objects.
+   */ async getPriceFeeds({ fetchOptions, ...options } = {}) {
+        const url = this.buildURL("price_feeds");
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (options) {
+            const transformedOptions = (0, _utils.camelToSnakeCaseObject)(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return await this.httpRequest(url.toString(), _zodSchemas.schemas.PriceFeedMetadata.array(), fetchOptions);
+    }
+    /**
+   * Fetch the latest publisher stake caps.
+   * This endpoint can be customized by specifying the encoding type and whether the results should also return the parsed publisher caps.
+   * This will throw an error if there is a network problem or the price service returns a non-ok response.
+   *
+   * @param options - Optional parameters:
+   *        - encoding: Encoding type. If specified, return the publisher caps in the encoding specified by the encoding parameter. Default is hex.
+   *        - parsed: Boolean to specify if the parsed publisher caps should be included in the response. Default is false.
+   *
+   * @returns PublisherCaps object containing the latest publisher stake caps.
+   */ async getLatestPublisherCaps({ fetchOptions, ...options } = {}) {
+        const url = this.buildURL("updates/publisher_stake_caps/latest");
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (options) {
+            this.appendUrlSearchParams(url, options);
+        }
+        return await this.httpRequest(url.toString(), _zodSchemas.schemas.LatestPublisherStakeCapsUpdateDataResponse, fetchOptions);
+    }
+    /**
+   * Fetch the latest price updates for a set of price feed IDs.
+   * This endpoint can be customized by specifying the encoding type and whether the results should also return the parsed price update using the options object.
+   * This will throw an error if there is a network problem or the price service returns a non-ok response.
+   *
+   * @param ids - Array of hex-encoded price feed IDs for which updates are requested.
+   * @param options - Optional parameters:
+   *        - encoding: Encoding type. If specified, return the price update in the encoding specified by the encoding parameter. Default is hex.
+   *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
+   *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
+   *
+   * @returns PriceUpdate object containing the latest updates.
+   */ async getLatestPriceUpdates(ids, options, fetchOptions) {
+        const url = this.buildURL("updates/price/latest");
+        for (const id of ids){
+            url.searchParams.append("ids[]", id);
+        }
+        if (options) {
+            const transformedOptions = (0, _utils.camelToSnakeCaseObject)(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return this.httpRequest(url.toString(), _zodSchemas.schemas.PriceUpdate, fetchOptions);
+    }
+    /**
+   * Fetch the price updates for a set of price feed IDs at a given timestamp.
+   * This endpoint can be customized by specifying the encoding type and whether the results should also return the parsed price update.
+   * This will throw an error if there is a network problem or the price service returns a non-ok response.
+   *
+   * @param publishTime - Unix timestamp in seconds.
+   * @param ids - Array of hex-encoded price feed IDs for which updates are requested.
+   * @param options - Optional parameters:
+   *        - encoding: Encoding type. If specified, return the price update in the encoding specified by the encoding parameter. Default is hex.
+   *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
+   *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
+   *
+   * @returns PriceUpdate object containing the updates at the specified timestamp.
+   */ async getPriceUpdatesAtTimestamp(publishTime, ids, options, fetchOptions) {
+        const url = this.buildURL(`updates/price/${publishTime.toString()}`);
+        for (const id of ids){
+            url.searchParams.append("ids[]", id);
+        }
+        if (options) {
+            const transformedOptions = (0, _utils.camelToSnakeCaseObject)(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return this.httpRequest(url.toString(), _zodSchemas.schemas.PriceUpdate, fetchOptions);
+    }
+    /**
+   * Fetch streaming price updates for a set of price feed IDs.
+   * This endpoint can be customized by specifying the encoding type, whether the results should include parsed updates,
+   * and if unordered updates or only benchmark updates are allowed.
+   * This will return an EventSource that can be used to listen to streaming updates.
+   * If an invalid hex-encoded ID is passed, it will throw an error.
+   *
+   * @param ids - Array of hex-encoded price feed IDs for which streaming updates are requested.
+   * @param options - Optional parameters:
+   *        - encoding: Encoding type. If specified, updates are returned in the specified encoding. Default is hex.
+   *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
+   *        - allowUnordered: Boolean to specify if unordered updates are allowed to be included in the stream. Default is false.
+   *        - benchmarksOnly: Boolean to specify if only benchmark prices should be returned. Default is false.
+   *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
+   *
+   * @returns An EventSource instance for receiving streaming updates.
+   */ async getPriceUpdatesStream(ids, options) {
+        const url = this.buildURL("updates/price/stream");
+        for (const id of ids){
+            url.searchParams.append("ids[]", id);
+        }
+        if (options) {
+            const transformedOptions = (0, _utils.camelToSnakeCaseObject)(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return new _eventsource.EventSource(url.toString(), {
+            fetch: (input, init)=>fetch(input, {
+                    ...init,
+                    headers: {
+                        ...init?.headers,
+                        ...this.headers
+                    }
+                })
+        });
+    }
+    /**
+   * Fetch the latest TWAP (time weighted average price) for a set of price feed IDs.
+   * This endpoint can be customized by specifying the encoding type and whether the results should also return the calculated TWAP using the options object.
+   * This will throw an error if there is a network problem or the price service returns a non-ok response.
+   *
+   * @param ids - Array of hex-encoded price feed IDs for which updates are requested.
+   * @param window_seconds - The time window in seconds over which to calculate the TWAP, ending at the current time.
+   *  For example, a value of 300 would return the most recent 5 minute TWAP. Must be greater than 0 and less than or equal to 600 seconds (10 minutes).
+   * @param options - Optional parameters:
+   *        - encoding: Encoding type. If specified, return the TWAP binary data in the encoding specified by the encoding parameter. Default is hex.
+   *        - parsed: Boolean to specify if the calculated TWAP should be included in the response. Default is false.
+   *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
+   *
+   * @returns TwapsResponse object containing the latest TWAPs.
+   */ async getLatestTwaps(ids, window_seconds, options, fetchOptions) {
+        const url = this.buildURL(`updates/twap/${window_seconds.toString()}/latest`);
+        for (const id of ids){
+            url.searchParams.append("ids[]", id);
+        }
+        if (options) {
+            const transformedOptions = (0, _utils.camelToSnakeCaseObject)(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return this.httpRequest(url.toString(), _zodSchemas.schemas.TwapsResponse, fetchOptions);
+    }
+    appendUrlSearchParams(url, params) {
+        for (const [key, value] of Object.entries(params)){
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (value !== undefined) {
+                url.searchParams.append(key, String(value));
+            }
+        }
+    }
+    buildURL(endpoint) {
+        return new URL(// eslint-disable-next-line unicorn/relative-url-style
+        `./v2/${endpoint}`, // We ensure the `baseURL` ends with a `/` so that URL doesn't resolve the
+        // path relative to the parent.
+        `${this.baseURL}${this.baseURL.endsWith("/") ? "" : "/"}`);
+    }
+}

package/{lib/HermesClient.d.ts → dist/cjs/hermes-client.d.ts}

@@ -1,6 +1,6 @@
 import { EventSource } from "eventsource";
-import { schemas } from "./zodSchemas";
 import { z } from "zod";
+import { schemas } from "./zodSchemas.js";
 export type AssetType = z.infer<typeof schemas.AssetType>;
 export type BinaryPriceUpdate = z.infer<typeof schemas.BinaryUpdate>;
 export type EncodingType = z.infer<typeof schemas.EncodingType>;
@@ -35,8 +35,8 @@ export declare class HermesClient {
     /**
      * Constructs a new Connection.
      *
-     * @param endpoint endpoint URL to the price service. Example: https://website/example/
-     * @param config Optional HermesClientConfig for custom configurations.
+     * @param endpoint - endpoint URL to the price service. Example: https://website/example/
+     * @param config - Optional HermesClientConfig for custom configurations.
      */
     constructor(endpoint: string, config?: HermesClientConfig);
     private httpRequest;
@@ -45,7 +45,7 @@ export declare class HermesClient {
      * This endpoint can be filtered by asset type and query string.
      * This will throw an error if there is a network problem or the price service returns a non-ok response.
      *
-     * @param options Optional parameters:
+     * @param options - Optional parameters:
      *        - query: String to filter the price feeds. If provided, the results will be filtered to all price feeds whose symbol contains the query string. Query string is case insensitive. Example: "bitcoin".
      *        - assetType: String to filter the price feeds by asset type. Possible values are "crypto", "equity", "fx", "metal", "rates", "crypto_redemption_rate". Filter string is case insensitive.
      *
@@ -61,7 +61,7 @@ export declare class HermesClient {
      * This endpoint can be customized by specifying the encoding type and whether the results should also return the parsed publisher caps.
      * This will throw an error if there is a network problem or the price service returns a non-ok response.
      *
-     * @param options Optional parameters:
+     * @param options - Optional parameters:
      *        - encoding: Encoding type. If specified, return the publisher caps in the encoding specified by the encoding parameter. Default is hex.
      *        - parsed: Boolean to specify if the parsed publisher caps should be included in the response. Default is false.
      *
@@ -77,8 +77,8 @@ export declare class HermesClient {
      * This endpoint can be customized by specifying the encoding type and whether the results should also return the parsed price update using the options object.
      * This will throw an error if there is a network problem or the price service returns a non-ok response.
      *
-     * @param ids Array of hex-encoded price feed IDs for which updates are requested.
-     * @param options Optional parameters:
+     * @param ids - Array of hex-encoded price feed IDs for which updates are requested.
+     * @param options - Optional parameters:
      *        - encoding: Encoding type. If specified, return the price update in the encoding specified by the encoding parameter. Default is hex.
      *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
      *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
@@ -95,9 +95,9 @@ export declare class HermesClient {
      * This endpoint can be customized by specifying the encoding type and whether the results should also return the parsed price update.
      * This will throw an error if there is a network problem or the price service returns a non-ok response.
      *
-     * @param publishTime Unix timestamp in seconds.
-     * @param ids Array of hex-encoded price feed IDs for which updates are requested.
-     * @param options Optional parameters:
+     * @param publishTime - Unix timestamp in seconds.
+     * @param ids - Array of hex-encoded price feed IDs for which updates are requested.
+     * @param options - Optional parameters:
      *        - encoding: Encoding type. If specified, return the price update in the encoding specified by the encoding parameter. Default is hex.
      *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
      *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
@@ -116,8 +116,8 @@ export declare class HermesClient {
      * This will return an EventSource that can be used to listen to streaming updates.
      * If an invalid hex-encoded ID is passed, it will throw an error.
      *
-     * @param ids Array of hex-encoded price feed IDs for which streaming updates are requested.
-     * @param options Optional parameters:
+     * @param ids - Array of hex-encoded price feed IDs for which streaming updates are requested.
+     * @param options - Optional parameters:
      *        - encoding: Encoding type. If specified, updates are returned in the specified encoding. Default is hex.
      *        - parsed: Boolean to specify if the parsed price update should be included in the response. Default is false.
      *        - allowUnordered: Boolean to specify if unordered updates are allowed to be included in the stream. Default is false.
@@ -138,10 +138,10 @@ export declare class HermesClient {
      * This endpoint can be customized by specifying the encoding type and whether the results should also return the calculated TWAP using the options object.
      * This will throw an error if there is a network problem or the price service returns a non-ok response.
      *
-     * @param ids Array of hex-encoded price feed IDs for which updates are requested.
-     * @param window_seconds The time window in seconds over which to calculate the TWAP, ending at the current time.
+     * @param ids - Array of hex-encoded price feed IDs for which updates are requested.
+     * @param window_seconds - The time window in seconds over which to calculate the TWAP, ending at the current time.
      *  For example, a value of 300 would return the most recent 5 minute TWAP. Must be greater than 0 and less than or equal to 600 seconds (10 minutes).
-     * @param options Optional parameters:
+     * @param options - Optional parameters:
      *        - encoding: Encoding type. If specified, return the TWAP binary data in the encoding specified by the encoding parameter. Default is hex.
      *        - parsed: Boolean to specify if the calculated TWAP should be included in the response. Default is false.
      *        - ignoreInvalidPriceIds: Boolean to specify if invalid price IDs should be ignored instead of returning an error. Default is false.
@@ -156,4 +156,3 @@ export declare class HermesClient {
     private appendUrlSearchParams;
     private buildURL;
 }
-//# sourceMappingURL=HermesClient.d.ts.map

package/dist/cjs/index.cjs

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+_export_star(require("./hermes-client.cjs"), exports);
+function _export_star(from, to) {
+    Object.keys(from).forEach(function(k) {
+        if (k !== "default" && !Object.prototype.hasOwnProperty.call(to, k)) {
+            Object.defineProperty(to, k, {
+                enumerable: true,
+                get: function() {
+                    return from[k];
+                }
+            });
+        }
+    });
+    return from;
+}

package/dist/cjs/index.d.ts

@@ -0,0 +1 @@
+export * from "./hermes-client.js";

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{ "type": "commonjs" }

package/dist/cjs/utils.cjs

@@ -0,0 +1,22 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "camelToSnakeCaseObject", {
+    enumerable: true,
+    get: function() {
+        return camelToSnakeCaseObject;
+    }
+});
+function camelToSnakeCase(str) {
+    return str.replaceAll(/[A-Z]/g, (letter)=>`_${letter.toLowerCase()}`);
+}
+function camelToSnakeCaseObject(obj) {
+    const result = {};
+    for (const key of Object.keys(obj)){
+        const newKey = camelToSnakeCase(key);
+        const val = obj[key];
+        result[newKey] = val;
+    }
+    return result;
+}

package/{lib → dist/cjs}/utils.d.ts

@@ -1,2 +1 @@
 export declare function camelToSnakeCaseObject(obj: Record<string, string | boolean>): Record<string, string | boolean>;
-//# sourceMappingURL=utils.d.ts.map