@pythnetwork/hermes-client 2.0.0 → 3.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,209 @@
+/* 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;
+    accessToken;
+    /**
+   * 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 ?? {};
+        this.accessToken = config?.accessToken;
+    }
+    async httpRequest(url, schema, options, retries = this.httpRetries, backoff = 100 + Math.floor(Math.random() * 100)) {
+        try {
+            // Build auth headers if access token is provided
+            const authHeaders = {};
+            if (this.accessToken !== undefined) {
+                authHeaders.Authorization = `Bearer ${this.accessToken}`;
+            }
+            const response = await fetch(url, {
+                ...options,
+                signal: AbortSignal.any([
+                    ...options?.signal ? [
+                        options.signal
+                    ] : [],
+                    AbortSignal.timeout(this.timeout)
+                ]),
+                headers: {
+                    ...authHeaders,
+                    ...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);
+        }
+        // Build auth headers for SSE fetch
+        const authHeaders = {};
+        if (this.accessToken !== undefined) {
+            authHeaders.Authorization = `Bearer ${this.accessToken}`;
+        }
+        return new _eventsource.EventSource(url.toString(), {
+            fetch: (input, init)=>fetch(input, {
+                    ...init,
+                    headers: {
+                        ...init?.headers,
+                        ...authHeaders,
+                        ...this.headers
+                    }
+                })
+        });
+    }
+    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,13 +1,12 @@
 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>;
 export type PriceFeedMetadata = z.infer<typeof schemas.PriceFeedMetadata>;
 export type PriceIdInput = z.infer<typeof schemas.PriceIdInput>;
 export type PriceUpdate = z.infer<typeof schemas.PriceUpdate>;
-export type TwapsResponse = z.infer<typeof schemas.TwapsResponse>;
 export type PublisherCaps = z.infer<typeof schemas.LatestPublisherStakeCapsUpdateDataResponse>;
 export type UnixTimestamp = number;
 export type DurationInSeconds = number;
@@ -26,17 +25,25 @@ export type HermesClientConfig = {
      * Optional headers to be included in every request.
      */
     headers?: HeadersInit;
+    /**
+     * Optional API access token for authentication.
+     * When provided, this token will be included in all requests either:
+     * - As a Bearer token in the Authorization header (for HTTP requests)
+     * - As an ACCESS_TOKEN query parameter (for WebSocket/SSE connections)
+     */
+    accessToken?: string;
 };
 export declare class HermesClient {
     private baseURL;
     private timeout;
     private httpRetries;
     private headers;
+    private accessToken;
     /**
      * 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 +52,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 +68,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 +84,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 +102,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 +123,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.
@@ -133,27 +140,6 @@ export declare class HermesClient {
         benchmarksOnly?: boolean;
         ignoreInvalidPriceIds?: boolean;
     }): Promise<EventSource>;
-    /**
-     * 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.
-     */
-    getLatestTwaps(ids: HexString[], window_seconds: number, options?: {
-        encoding?: EncodingType;
-        parsed?: boolean;
-        ignoreInvalidPriceIds?: boolean;
-    }, fetchOptions?: RequestInit): Promise<TwapsResponse>;
     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 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "camelToSnakeCaseObject", {
+    enumerable: true,
+    get: function() {
+        return camelToSnakeCaseObject;
+    }
+});
+/* eslint-disable @typescript-eslint/no-non-null-assertion */ 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