@pythnetwork/hermes-client 2.0.0 → 2.1.0

package/dist/cjs/zodSchemas.cjs

@@ -0,0 +1,351 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: Object.getOwnPropertyDescriptor(all, name).get
+    });
+}
+_export(exports, {
+    get api () {
+        return api;
+    },
+    get createApiClient () {
+        return createApiClient;
+    },
+    get schemas () {
+        return schemas;
+    }
+});
+const _core = require("@zodios/core");
+const _zod = require("zod");
+const AssetType = _zod.z.enum([
+    "crypto",
+    "fx",
+    "equity",
+    "metal",
+    "rates",
+    "crypto_redemption_rate",
+    "commodities",
+    "crypto_index",
+    "crypto_nav"
+]);
+const asset_type = AssetType.nullish();
+const RpcPriceIdentifier = _zod.z.string();
+const PriceFeedMetadata = _zod.z.object({
+    attributes: _zod.z.record(_zod.z.string()),
+    id: RpcPriceIdentifier
+}).passthrough();
+const PriceIdInput = _zod.z.string();
+const EncodingType = _zod.z.enum([
+    "hex",
+    "base64"
+]);
+const BinaryUpdate = _zod.z.object({
+    data: _zod.z.array(_zod.z.string()),
+    encoding: EncodingType
+}).passthrough();
+const RpcPrice = _zod.z.object({
+    conf: _zod.z.string(),
+    expo: _zod.z.number().int(),
+    price: _zod.z.string(),
+    publish_time: _zod.z.number().int()
+}).passthrough();
+const RpcPriceFeedMetadataV2 = _zod.z.object({
+    prev_publish_time: _zod.z.number().int().nullable(),
+    proof_available_time: _zod.z.number().int().nullable(),
+    slot: _zod.z.number().int().gte(0).nullable()
+}).partial().passthrough();
+const ParsedPriceUpdate = _zod.z.object({
+    ema_price: RpcPrice,
+    id: RpcPriceIdentifier,
+    metadata: RpcPriceFeedMetadataV2,
+    price: RpcPrice
+}).passthrough();
+const PriceUpdate = _zod.z.object({
+    binary: BinaryUpdate,
+    parsed: _zod.z.array(ParsedPriceUpdate).nullish()
+}).passthrough();
+const ParsedPublisherStakeCap = _zod.z.object({
+    cap: _zod.z.number().int().gte(0),
+    publisher: _zod.z.string()
+}).passthrough();
+const ParsedPublisherStakeCapsUpdate = _zod.z.object({
+    publisher_stake_caps: _zod.z.array(ParsedPublisherStakeCap)
+}).passthrough();
+const LatestPublisherStakeCapsUpdateDataResponse = _zod.z.object({
+    binary: BinaryUpdate,
+    parsed: _zod.z.array(ParsedPublisherStakeCapsUpdate).nullish()
+}).passthrough();
+const ParsedPriceFeedTwap = _zod.z.object({
+    down_slots_ratio: _zod.z.string(),
+    end_timestamp: _zod.z.number().int(),
+    id: RpcPriceIdentifier,
+    start_timestamp: _zod.z.number().int(),
+    twap: RpcPrice
+}).passthrough();
+const TwapsResponse = _zod.z.object({
+    binary: BinaryUpdate,
+    parsed: _zod.z.array(ParsedPriceFeedTwap).nullish()
+}).passthrough();
+const schemas = {
+    AssetType,
+    asset_type,
+    RpcPriceIdentifier,
+    PriceFeedMetadata,
+    PriceIdInput,
+    EncodingType,
+    BinaryUpdate,
+    RpcPrice,
+    RpcPriceFeedMetadataV2,
+    ParsedPriceUpdate,
+    PriceUpdate,
+    ParsedPublisherStakeCap,
+    ParsedPublisherStakeCapsUpdate,
+    LatestPublisherStakeCapsUpdateDataResponse,
+    ParsedPriceFeedTwap,
+    TwapsResponse
+};
+const endpoints = (0, _core.makeApi)([
+    {
+        method: "get",
+        path: "/v2/price_feeds",
+        alias: "price_feeds_metadata",
+        description: `Get the set of price feeds.
+
+This endpoint fetches all price feeds from the Pyth network. It can be filtered by asset type
+and query string.`,
+        requestFormat: "json",
+        parameters: [
+            {
+                name: "query",
+                type: "Query",
+                schema: _zod.z.string().nullish()
+            },
+            {
+                name: "asset_type",
+                type: "Query",
+                schema: asset_type
+            }
+        ],
+        response: _zod.z.array(PriceFeedMetadata)
+    },
+    {
+        method: "get",
+        path: "/v2/updates/price/:publish_time",
+        alias: "timestamp_price_updates",
+        description: `Get the latest price updates by price feed id.
+
+Given a collection of price feed ids, retrieve the latest Pyth price for each price feed.`,
+        requestFormat: "json",
+        parameters: [
+            {
+                name: "publish_time",
+                type: "Path",
+                schema: _zod.z.number().int()
+            },
+            {
+                name: "ids[]",
+                type: "Query",
+                schema: _zod.z.array(PriceIdInput)
+            },
+            {
+                name: "encoding",
+                type: "Query",
+                schema: _zod.z.enum([
+                    "hex",
+                    "base64"
+                ]).optional()
+            },
+            {
+                name: "parsed",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            },
+            {
+                name: "ignore_invalid_price_ids",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            }
+        ],
+        response: PriceUpdate,
+        errors: [
+            {
+                status: 404,
+                description: `Price ids not found`,
+                schema: _zod.z.void()
+            }
+        ]
+    },
+    {
+        method: "get",
+        path: "/v2/updates/price/latest",
+        alias: "latest_price_updates",
+        description: `Get the latest price updates by price feed id.
+
+Given a collection of price feed ids, retrieve the latest Pyth price for each price feed.`,
+        requestFormat: "json",
+        parameters: [
+            {
+                name: "ids[]",
+                type: "Query",
+                schema: _zod.z.array(PriceIdInput)
+            },
+            {
+                name: "encoding",
+                type: "Query",
+                schema: _zod.z.enum([
+                    "hex",
+                    "base64"
+                ]).optional()
+            },
+            {
+                name: "parsed",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            },
+            {
+                name: "ignore_invalid_price_ids",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            }
+        ],
+        response: PriceUpdate,
+        errors: [
+            {
+                status: 404,
+                description: `Price ids not found`,
+                schema: _zod.z.void()
+            }
+        ]
+    },
+    {
+        method: "get",
+        path: "/v2/updates/price/stream",
+        alias: "price_stream_sse_handler",
+        description: `SSE route handler for streaming price updates.
+
+The connection will automatically close after 24 hours to prevent resource leaks.
+Clients should implement reconnection logic to maintain continuous price updates.`,
+        requestFormat: "json",
+        parameters: [
+            {
+                name: "ids[]",
+                type: "Query",
+                schema: _zod.z.array(PriceIdInput)
+            },
+            {
+                name: "encoding",
+                type: "Query",
+                schema: _zod.z.enum([
+                    "hex",
+                    "base64"
+                ]).optional()
+            },
+            {
+                name: "parsed",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            },
+            {
+                name: "allow_unordered",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            },
+            {
+                name: "benchmarks_only",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            },
+            {
+                name: "ignore_invalid_price_ids",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            }
+        ],
+        response: PriceUpdate,
+        errors: [
+            {
+                status: 404,
+                description: `Price ids not found`,
+                schema: _zod.z.void()
+            }
+        ]
+    },
+    {
+        method: "get",
+        path: "/v2/updates/publisher_stake_caps/latest",
+        alias: "latest_publisher_stake_caps",
+        description: `Get the most recent publisher stake caps update data.`,
+        requestFormat: "json",
+        parameters: [
+            {
+                name: "encoding",
+                type: "Query",
+                schema: _zod.z.enum([
+                    "hex",
+                    "base64"
+                ]).optional()
+            },
+            {
+                name: "parsed",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            }
+        ],
+        response: LatestPublisherStakeCapsUpdateDataResponse
+    },
+    {
+        method: "get",
+        path: "/v2/updates/twap/:window_seconds/latest",
+        alias: "latest_twaps",
+        description: `Get the latest TWAP by price feed id with a custom time window.
+
+Given a collection of price feed ids, retrieve the latest Pyth TWAP price for each price feed.`,
+        requestFormat: "json",
+        parameters: [
+            {
+                name: "window_seconds",
+                type: "Path",
+                schema: _zod.z.number().int().gte(0)
+            },
+            {
+                name: "ids[]",
+                type: "Query",
+                schema: _zod.z.array(PriceIdInput)
+            },
+            {
+                name: "encoding",
+                type: "Query",
+                schema: _zod.z.enum([
+                    "hex",
+                    "base64"
+                ]).optional()
+            },
+            {
+                name: "parsed",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            },
+            {
+                name: "ignore_invalid_price_ids",
+                type: "Query",
+                schema: _zod.z.boolean().optional()
+            }
+        ],
+        response: TwapsResponse,
+        errors: [
+            {
+                status: 404,
+                description: `Price ids not found`,
+                schema: _zod.z.void()
+            }
+        ]
+    }
+]);
+const api = new _core.Zodios(endpoints);
+function createApiClient(baseUrl, options) {
+    return new _core.Zodios(baseUrl, endpoints, options);
+}

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

@@ -1,8 +1,8 @@
 import { type ZodiosOptions } from "@zodios/core";
 import { z } from "zod";
 export declare const schemas: {
-    AssetType: z.ZodEnum<["crypto", "fx", "equity", "metal", "rates", "crypto_redemption_rate"]>;
-    asset_type: z.ZodOptional<z.ZodNullable<z.ZodEnum<["crypto", "fx", "equity", "metal", "rates", "crypto_redemption_rate"]>>>;
+    AssetType: z.ZodEnum<["crypto", "fx", "equity", "metal", "rates", "crypto_redemption_rate", "commodities", "crypto_index", "crypto_nav"]>;
+    asset_type: z.ZodOptional<z.ZodNullable<z.ZodEnum<["crypto", "fx", "equity", "metal", "rates", "crypto_redemption_rate", "commodities", "crypto_index", "crypto_nav"]>>>;
     RpcPriceIdentifier: z.ZodString;
     PriceFeedMetadata: z.ZodObject<{
         attributes: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -1141,7 +1141,7 @@ export declare const api: import("@zodios/core").ZodiosInstance<[{
     }, {
         name: "asset_type";
         type: "Query";
-        schema: z.ZodOptional<z.ZodNullable<z.ZodEnum<["crypto", "fx", "equity", "metal", "rates", "crypto_redemption_rate"]>>>;
+        schema: z.ZodOptional<z.ZodNullable<z.ZodEnum<["crypto", "fx", "equity", "metal", "rates", "crypto_redemption_rate", "commodities", "crypto_index", "crypto_nav"]>>>;
     }];
     response: z.ZodArray<z.ZodObject<{
         attributes: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -2137,7 +2137,7 @@ export declare const api: import("@zodios/core").ZodiosInstance<[{
     method: "get";
     path: "/v2/updates/price/stream";
     alias: "price_stream_sse_handler";
-    description: "SSE route handler for streaming price updates.";
+    description: "SSE route handler for streaming price updates.\n\nThe connection will automatically close after 24 hours to prevent resource leaks.\nClients should implement reconnection logic to maintain continuous price updates.";
     requestFormat: "json";
     parameters: [{
         name: "ids[]";
@@ -3052,7 +3052,7 @@ export declare function createApiClient(baseUrl: string, options?: ZodiosOptions
     }, {
         name: "asset_type";
         type: "Query";
-        schema: z.ZodOptional<z.ZodNullable<z.ZodEnum<["crypto", "fx", "equity", "metal", "rates", "crypto_redemption_rate"]>>>;
+        schema: z.ZodOptional<z.ZodNullable<z.ZodEnum<["crypto", "fx", "equity", "metal", "rates", "crypto_redemption_rate", "commodities", "crypto_index", "crypto_nav"]>>>;
     }];
     response: z.ZodArray<z.ZodObject<{
         attributes: z.ZodRecord<z.ZodString, z.ZodString>;
@@ -4048,7 +4048,7 @@ export declare function createApiClient(baseUrl: string, options?: ZodiosOptions
     method: "get";
     path: "/v2/updates/price/stream";
     alias: "price_stream_sse_handler";
-    description: "SSE route handler for streaming price updates.";
+    description: "SSE route handler for streaming price updates.\n\nThe connection will automatically close after 24 hours to prevent resource leaks.\nClients should implement reconnection logic to maintain continuous price updates.";
     requestFormat: "json";
     parameters: [{
         name: "ids[]";
@@ -4950,4 +4950,3 @@ export declare function createApiClient(baseUrl: string, options?: ZodiosOptions
         schema: z.ZodVoid;
     }];
 }]>;
-//# sourceMappingURL=zodSchemas.d.ts.map

package/dist/esm/hermes-client.d.ts

@@ -0,0 +1,158 @@
+import { EventSource } from "eventsource";
+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;
+export type HexString = string;
+export type DurationInMs = number;
+export type HermesClientConfig = {
+    timeout?: DurationInMs;
+    /**
+     * Number of times a HTTP request will be retried before the API returns a failure. Default: 3.
+     *
+     * The connection uses exponential back-off for the delay between retries. However,
+     * it will timeout regardless of the retries at the configured `timeout` time.
+     */
+    httpRetries?: number;
+    /**
+     * Optional headers to be included in every request.
+     */
+    headers?: HeadersInit;
+};
+export declare class HermesClient {
+    private baseURL;
+    private timeout;
+    private httpRetries;
+    private 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: string, config?: HermesClientConfig);
+    private httpRequest;
+    /**
+     * 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.
+     */
+    getPriceFeeds({ fetchOptions, ...options }?: {
+        query?: string;
+        assetType?: AssetType;
+        fetchOptions?: RequestInit;
+    }): Promise<PriceFeedMetadata[]>;
+    /**
+     * 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.
+     */
+    getLatestPublisherCaps({ fetchOptions, ...options }?: {
+        encoding?: EncodingType;
+        parsed?: boolean;
+        fetchOptions?: RequestInit;
+    }): Promise<PublisherCaps>;
+    /**
+     * 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.
+     */
+    getLatestPriceUpdates(ids: HexString[], options?: {
+        encoding?: EncodingType;
+        parsed?: boolean;
+        ignoreInvalidPriceIds?: boolean;
+    }, fetchOptions?: RequestInit): Promise<PriceUpdate>;
+    /**
+     * 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.
+     */
+    getPriceUpdatesAtTimestamp(publishTime: UnixTimestamp, ids: HexString[], options?: {
+        encoding?: EncodingType;
+        parsed?: boolean;
+        ignoreInvalidPriceIds?: boolean;
+    }, fetchOptions?: RequestInit): Promise<PriceUpdate>;
+    /**
+     * 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.
+     */
+    getPriceUpdatesStream(ids: HexString[], options?: {
+        encoding?: EncodingType;
+        parsed?: boolean;
+        allowUnordered?: boolean;
+        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;
+}