@pythnetwork/hermes-client 2.0.0 → 2.1.0

package/dist/esm/hermes-client.mjs

@@ -0,0 +1,210 @@
+/* eslint-disable @typescript-eslint/require-await */ /* eslint-disable @typescript-eslint/no-misused-spread */ /* eslint-disable @typescript-eslint/no-unsafe-assignment */ import { EventSource } from "eventsource";
+import { camelToSnakeCaseObject } from "./utils.mjs";
+import { schemas } from "./zodSchemas.mjs";
+const DEFAULT_TIMEOUT = 5000;
+const DEFAULT_HTTP_RETRIES = 3;
+export 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 = camelToSnakeCaseObject(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return await this.httpRequest(url.toString(), 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(), 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 = camelToSnakeCaseObject(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return this.httpRequest(url.toString(), 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 = camelToSnakeCaseObject(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return this.httpRequest(url.toString(), 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 = camelToSnakeCaseObject(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return new 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 = camelToSnakeCaseObject(options);
+            this.appendUrlSearchParams(url, transformedOptions);
+        }
+        return this.httpRequest(url.toString(), 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/dist/esm/index.d.ts

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

package/dist/esm/index.mjs

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

package/dist/esm/package.json

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

package/dist/esm/utils.d.ts

@@ -0,0 +1 @@
+export declare function camelToSnakeCaseObject(obj: Record<string, string | boolean>): Record<string, string | boolean>;

package/dist/esm/utils.mjs

@@ -0,0 +1,12 @@
+/* eslint-disable @typescript-eslint/no-non-null-assertion */ function camelToSnakeCase(str) {
+    return str.replaceAll(/[A-Z]/g, (letter)=>`_${letter.toLowerCase()}`);
+}
+export 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;
+}