@nktkas/hyperliquid 0.30.3 → 0.32.0

package/src/src/transport/http/mod.ts

@@ -1,205 +0,0 @@
-/**
- * HTTP transport for executing requests to the Hyperliquid API.
- *
- * Use {@link HttpTransport} for simple requests via HTTP POST.
- *
- * @example
- * ```ts
- * import { HttpTransport, InfoClient } from "@nktkas/hyperliquid";
- *
- * const transport = new HttpTransport();
- * const client = new InfoClient({ transport });
- *
- * const mids = await client.allMids();
- * ```
- *
- * @module
- */
-
-import { type IRequestTransport, TransportError } from "../_base.js";
-import { AbortSignal_ } from "../_polyfills.js";
-
-/** Error thrown when an HTTP request fails. */
-export class HttpRequestError extends TransportError {
-  /** The HTTP response that caused the error. */
-  response?: Response;
-  /** The response body text. */
-  body?: string;
-
-  /**
-   * Creates a new HTTP request error.
-   *
-   * @param args - The error arguments.
-   * @param args.response - The HTTP response that caused the error.
-   * @param args.body - The response body text.
-   * @param options - The error options.
-   */
-  constructor(args?: { response?: Response; body?: string }, options?: ErrorOptions) {
-    const { response, body } = args ?? {};
-
-    let message: string;
-    if (response) {
-      message = `${response.status} ${response.statusText}`.trim();
-      if (body) message += ` - ${body}`;
-    } else {
-      message = `Unknown HTTP request error: ${options?.cause}`;
-    }
-
-    super(message, options);
-    this.name = "HttpRequestError";
-    this.response = response;
-    this.body = body;
-  }
-}
-
-/** Configuration options for the HTTP transport layer. */
-export interface HttpTransportOptions {
-  /**
-   * Indicates this transport uses testnet endpoint.
-   * @default false
-   */
-  isTestnet?: boolean;
-  /**
-   * Request timeout in ms. Set to `null` to disable.
-   * @default 10_000
-   */
-  timeout?: number | null;
-  /**
-   * Custom API URL for requests.
-   * @default `https://api.hyperliquid.xyz` for mainnet, `https://api.hyperliquid-testnet.xyz` for testnet.
-   */
-  apiUrl?: string | URL;
-  /**
-   * Custom RPC URL for explorer requests.
-   * @default `https://rpc.hyperliquid.xyz` for mainnet, `https://rpc.hyperliquid-testnet.xyz` for testnet.
-   */
-  rpcUrl?: string | URL;
-  /** A custom {@link https://developer.mozilla.org/en-US/docs/Web/API/RequestInit | RequestInit} that is merged with a fetch request. */
-  fetchOptions?: Omit<RequestInit, "body" | "method">;
-}
-
-/** Mainnet API URL. */
-export const MAINNET_API_URL = "https://api.hyperliquid.xyz";
-/** Testnet API URL. */
-export const TESTNET_API_URL = "https://api.hyperliquid-testnet.xyz";
-/** Mainnet RPC URL. */
-export const MAINNET_RPC_URL = "https://rpc.hyperliquid.xyz";
-/** Testnet RPC URL. */
-export const TESTNET_RPC_URL = "https://rpc.hyperliquid-testnet.xyz";
-
-/**
- * HTTP transport for Hyperliquid API.
- *
- * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint
- * @see https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint
- */
-export class HttpTransport implements IRequestTransport {
-  /** Indicates this transport uses testnet endpoint. */
-  isTestnet: boolean;
-  /** Request timeout in ms. Set to `null` to disable. */
-  timeout: number | null;
-  /** Custom API URL for requests. */
-  apiUrl: string | URL;
-  /** Custom RPC URL for explorer requests. */
-  rpcUrl: string | URL;
-  /** A custom {@link https://developer.mozilla.org/en-US/docs/Web/API/RequestInit | RequestInit} that is merged with a fetch request. */
-  fetchOptions: Omit<RequestInit, "body" | "method">;
-
-  /**
-   * Creates a new HTTP transport instance.
-   *
-   * @param options - Configuration options for the HTTP transport layer.
-   */
-  constructor(options?: HttpTransportOptions) {
-    this.isTestnet = options?.isTestnet ?? false;
-    this.timeout = options?.timeout === undefined ? 10_000 : options.timeout;
-    this.apiUrl = options?.apiUrl ?? (this.isTestnet ? TESTNET_API_URL : MAINNET_API_URL);
-    this.rpcUrl = options?.rpcUrl ?? (this.isTestnet ? TESTNET_RPC_URL : MAINNET_RPC_URL);
-    this.fetchOptions = options?.fetchOptions ?? {};
-  }
-
-  /**
-   * Sends a request to the Hyperliquid API via {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | fetch}.
-   *
-   * @param endpoint - The API endpoint to send the request to.
-   * @param payload - The payload to send with the request.
-   * @param signal - {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} to cancel the request.
-   *
-   * @returns A promise that resolves with parsed JSON response body.
-   *
-   * @throws {HttpRequestError} Thrown when the HTTP request fails.
-   */
-  async request<T>(endpoint: "info" | "exchange" | "explorer", payload: unknown, signal?: AbortSignal): Promise<T> {
-    try {
-      // Construct a Request
-      const url = new URL(endpoint, endpoint === "explorer" ? this.rpcUrl : this.apiUrl);
-      const init = this._mergeRequestInit(
-        {
-          body: JSON.stringify(payload),
-          headers: {
-            "Accept-Encoding": "gzip, deflate, br, zstd",
-            "Content-Type": "application/json",
-          },
-          keepalive: true,
-          method: "POST",
-          signal: this.timeout ? AbortSignal_.timeout(this.timeout) : undefined,
-        },
-        this.fetchOptions,
-        { signal },
-      );
-
-      // Send the Request and wait for a Response
-      const response = await fetch(url, init);
-
-      // Validate the Response
-      if (!response.ok || !response.headers.get("Content-Type")?.includes("application/json")) {
-        // Unload the response body to prevent memory leaks
-        const body = await response.text().catch(() => undefined);
-        throw new HttpRequestError({ response, body });
-      }
-
-      // Parse the response body
-      const body = await response.json();
-
-      // Check if the response is an error
-      if (body?.type === "error") {
-        throw new HttpRequestError({ response, body: body?.message });
-      }
-
-      // Return the response body
-      return body;
-    } catch (error) {
-      if (error instanceof TransportError) throw error; // Re-throw known errors
-      throw new HttpRequestError(undefined, { cause: error });
-    }
-  }
-
-  /** Merges multiple `HeadersInit` into one {@link https://developer.mozilla.org/en-US/docs/Web/API/Headers/Headers | Headers}. */
-  protected _mergeHeadersInit(...inits: HeadersInit[]): Headers {
-    const merged = new Headers();
-    for (const headers of inits) {
-      const entries = Symbol.iterator in headers ? headers : Object.entries(headers);
-      for (const [key, value] of entries) {
-        merged.set(key, value);
-      }
-    }
-    return merged;
-  }
-
-  /** Merges multiple {@link https://developer.mozilla.org/en-US/docs/Web/API/RequestInit | RequestInit} into one {@link https://developer.mozilla.org/en-US/docs/Web/API/RequestInit | RequestInit}. */
-  protected _mergeRequestInit(...inits: RequestInit[]): RequestInit {
-    const merged: RequestInit = {};
-    const headersList: HeadersInit[] = [];
-    const signals: AbortSignal[] = [];
-
-    for (const init of inits) {
-      Object.assign(merged, init);
-      if (init.headers) headersList.push(init.headers);
-      if (init.signal) signals.push(init.signal);
-    }
-    if (headersList.length > 0) merged.headers = this._mergeHeadersInit(...headersList);
-    if (signals.length > 0) merged.signal = signals.length > 1 ? AbortSignal_.any(signals) : signals[0];
-
-    return merged;
-  }
-}

package/src/src/transport/websocket/_hyperliquidEventTarget.ts

@@ -1,131 +0,0 @@
-import * as v from "valibot";
-import { CustomEvent_ } from "../_polyfills.js";
-
-interface SubscribeUnsubscribeResponse {
-  method: "subscribe" | "unsubscribe";
-  /** Original subscription request payload. */
-  subscription: unknown;
-}
-
-interface PostResponse {
-  id: number;
-  response:
-    | {
-      type: "info";
-      payload: { type: string; data: unknown };
-    }
-    | {
-      type: "action";
-      payload: {
-        status: "ok" | "err";
-        response:
-          | { type: string; data?: unknown }
-          | string;
-      };
-    }
-    | {
-      type: "error";
-      /** Error message, e.g. "Cannot track more than 10 total users." */
-      payload: string;
-    };
-}
-
-interface BlockDetails {
-  blockTime: number;
-  hash: string;
-  height: number;
-  numTxs: number;
-  proposer: string;
-}
-
-interface TxDetails {
-  action: {
-    type: string;
-    [key: string]: unknown;
-  };
-  block: number;
-  error: string | null;
-  hash: string;
-  time: number;
-  user: string;
-}
-
-/** Base system events and dynamic channel events for Hyperliquid WebSocket API. */
-interface HyperliquidEventMap {
-  subscriptionResponse: CustomEvent<SubscribeUnsubscribeResponse>;
-  post: CustomEvent<PostResponse>;
-  error: CustomEvent<string>;
-  pong: CustomEvent<undefined>;
-  _explorerBlock: CustomEvent<BlockDetails[]>;
-  _explorerTxs: CustomEvent<TxDetails[]>;
-  // deno-lint-ignore no-explicit-any
-  [key: string]: CustomEvent<any>;
-}
-
-const BlockDetailsSchema = /* @__PURE__ */ (() => {
-  return v.looseObject({
-    blockTime: v.unknown(),
-    hash: v.unknown(),
-    height: v.unknown(),
-    numTxs: v.unknown(),
-    proposer: v.unknown(),
-  });
-})();
-const TxDetailsSchema = /* @__PURE__ */ (() => {
-  return v.looseObject({
-    action: v.unknown(),
-    block: v.unknown(),
-    error: v.unknown(),
-    hash: v.unknown(),
-    time: v.unknown(),
-    user: v.unknown(),
-  });
-})();
-const HyperliquidEventSchema = /* @__PURE__ */ (() => {
-  return v.object({ channel: v.string(), data: v.unknown() });
-})();
-const PongEventSchema = /* @__PURE__ */ (() => {
-  return v.object({ channel: v.literal("pong") });
-})();
-const ExplorerBlockEventSchema = /* @__PURE__ */ (() => {
-  return v.pipe(v.array(BlockDetailsSchema), v.nonEmpty());
-})();
-const ExplorerTxsEventSchema = /* @__PURE__ */ (() => {
-  return v.pipe(v.array(TxDetailsSchema), v.nonEmpty());
-})();
-
-/** Listens for WebSocket messages and sends them as Hyperliquid typed events. */
-export interface HyperliquidEventTarget {
-  addEventListener<K extends keyof HyperliquidEventMap>(
-    type: K,
-    listener: ((event: HyperliquidEventMap[K]) => void) | EventListenerObject | null,
-    options?: boolean | AddEventListenerOptions,
-  ): void;
-  removeEventListener<K extends keyof HyperliquidEventMap>(
-    type: K,
-    listener: ((event: HyperliquidEventMap[K]) => void) | EventListenerObject | null,
-    options?: boolean | EventListenerOptions,
-  ): void;
-  dispatchEvent(event: HyperliquidEventMap[keyof HyperliquidEventMap]): boolean;
-}
-export class HyperliquidEventTarget extends EventTarget {
-  constructor(socket: WebSocket) {
-    super();
-    socket.addEventListener("message", (event) => {
-      try {
-        const msg = JSON.parse(event.data);
-        if (v.is(HyperliquidEventSchema, msg)) {
-          this.dispatchEvent(new CustomEvent_(msg.channel, { detail: msg.data }));
-        } else if (v.is(PongEventSchema, msg)) {
-          this.dispatchEvent(new CustomEvent_("pong", { detail: undefined }));
-        } else if (v.is(ExplorerBlockEventSchema, msg)) {
-          this.dispatchEvent(new CustomEvent_("_explorerBlock", { detail: msg }));
-        } else if (v.is(ExplorerTxsEventSchema, msg)) {
-          this.dispatchEvent(new CustomEvent_("_explorerTxs", { detail: msg }));
-        }
-      } catch {
-        // Ignore JSON parsing errors
-      }
-    });
-  }
-}

package/src/src/transport/websocket/_postRequest.ts

@@ -1,292 +0,0 @@
-import { TransportError } from "../_base.js";
-import { AbortSignal_, Promise_ } from "../_polyfills.js";
-import type { ReconnectingWebSocket } from "@nktkas/rews";
-import type { HyperliquidEventTarget } from "./_hyperliquidEventTarget.js";
-
-interface PostRequest {
-  method: "post";
-  id: number;
-  request: unknown;
-}
-interface SubscribeUnsubscribeRequest {
-  method: "subscribe" | "unsubscribe";
-  subscription: unknown;
-}
-interface PingRequest {
-  method: "ping";
-}
-
-interface PendingRequest {
-  id: number | string;
-  // deno-lint-ignore no-explicit-any
-  resolve: (value?: any) => void;
-  // deno-lint-ignore no-explicit-any
-  reject: (reason?: any) => void;
-}
-
-/** Error thrown when a WebSocket request fails. */
-export class WebSocketRequestError extends TransportError {
-  constructor(message?: string, options?: ErrorOptions) {
-    super(message, options);
-    this.name = "WebSocketRequestError";
-  }
-}
-
-/**
- * Manages WebSocket post requests to the Hyperliquid API.
- * Handles request creation, sending, and mapping responses to their corresponding requests.
- */
-export class WebSocketPostRequest {
-  /** Timeout for requests in ms. Set to `null` to disable. */
-  timeout: number | null;
-
-  protected _socket: ReconnectingWebSocket;
-  protected _lastId = 0;
-  protected _queue: PendingRequest[] = [];
-
-  /**
-   * Creates a new WebSocket async request handler.
-   *
-   * @param socket - WebSocket connection instance for sending requests to the Hyperliquid WebSocket API
-   * @param hlEvents - Used to recognize Hyperliquid responses and match them with sent requests
-   * @param timeout - Timeout for requests in ms. Set to `null` to disable.
-   */
-  constructor(socket: ReconnectingWebSocket, hlEvents: HyperliquidEventTarget, timeout: number | null) {
-    this.timeout = timeout;
-    this._socket = socket;
-
-    // Monitor responses and match the pending request
-    hlEvents.addEventListener("subscriptionResponse", (event) => {
-      this._queue
-        // NOTE: API may add new fields over time, so perform a loose check of the payload.
-        .find((x) => typeof x.id === "string" && isSubset(JSON.parse(x.id), event.detail))
-        ?.resolve(event.detail);
-    });
-    hlEvents.addEventListener("post", (event) => {
-      if (event.detail.response.type === "error") {
-        this._queue
-          .find((x) => x.id === event.detail.id)
-          ?.reject(new WebSocketRequestError(event.detail.response.payload));
-        return;
-      }
-      const data = event.detail.response.type === "info"
-        ? event.detail.response.payload.data
-        : event.detail.response.payload;
-      this._queue.find((x) => x.id === event.detail.id)?.resolve(data);
-    });
-    hlEvents.addEventListener("pong", () => {
-      this._queue.find((x) => x.id === "ping")?.resolve();
-    });
-    hlEvents.addEventListener("error", (event) => {
-      try {
-        // For errors with `id=` suffix (e.g., `too many pending post requests id=1234`)
-        const idMatch = event.detail.match(/id=(\d+)$/);
-        if (idMatch) {
-          const id = parseInt(idMatch[1], 10);
-          this._queue.find((x) => x.id === id)
-            ?.reject(new WebSocketRequestError(event.detail));
-          return;
-        }
-
-        // Error event doesn't have an id, use original request to match
-        const request = event.detail.match(/{.*}/)?.[0];
-        if (!request) return;
-
-        const parsedRequest = JSON.parse(request);
-
-        // For `post` requests
-        if ("id" in parsedRequest && typeof parsedRequest.id === "number") {
-          this._queue.find((x) => x.id === parsedRequest.id)
-            ?.reject(new WebSocketRequestError(event.detail));
-          return;
-        }
-
-        // For `subscribe` and `unsubscribe` requests
-        if (
-          "subscription" in parsedRequest &&
-          typeof parsedRequest.subscription === "object" && parsedRequest.subscription !== null
-        ) {
-          const id = WebSocketPostRequest.requestToId(parsedRequest);
-          this._queue.find((x) => x.id === id)
-            ?.reject(new WebSocketRequestError(event.detail));
-          return;
-        }
-
-        // For `Already subscribed` and `Invalid subscription` requests
-        if (
-          event.detail.startsWith("Already subscribed") ||
-          event.detail.startsWith("Invalid subscription")
-        ) {
-          const id = WebSocketPostRequest.requestToId({
-            method: "subscribe",
-            subscription: parsedRequest,
-          });
-          this._queue.find((x) => x.id === id)
-            ?.reject(new WebSocketRequestError(event.detail));
-          return;
-        }
-
-        // For `Already unsubscribed` requests
-        if (event.detail.startsWith("Already unsubscribed")) {
-          const id = WebSocketPostRequest.requestToId({
-            method: "unsubscribe",
-            subscription: parsedRequest,
-          });
-          this._queue.find((x) => x.id === id)
-            ?.reject(new WebSocketRequestError(event.detail));
-          return;
-        }
-
-        // For unknown requests
-        const id = WebSocketPostRequest.requestToId(parsedRequest);
-        this._queue.find((x) => x.id === id)
-          ?.reject(new WebSocketRequestError(event.detail));
-      } catch {
-        // Ignore JSON parsing errors
-      }
-    });
-
-    // Throws all pending requests if the connection is dropped
-    const handleClose = () => {
-      this._queue.forEach(({ reject }) => {
-        reject(new WebSocketRequestError("WebSocket connection closed"));
-      });
-      this._queue = [];
-    };
-    socket.addEventListener("close", handleClose);
-    socket.addEventListener("error", handleClose);
-  }
-
-  /**
-   * Sends a request to the Hyperliquid API.
-   *
-   * @returns A promise that resolves with the parsed JSON response body.
-   */
-  async request(method: "ping", signal?: AbortSignal): Promise<void>;
-  async request<T>(method: "post" | "subscribe" | "unsubscribe", payload: unknown, signal?: AbortSignal): Promise<T>;
-  async request<T>(
-    method: "post" | "subscribe" | "unsubscribe" | "ping",
-    payloadOrSignal?: unknown | AbortSignal,
-    maybeSignal?: AbortSignal,
-  ): Promise<T> {
-    try {
-      const payload = payloadOrSignal instanceof AbortSignal ? undefined : payloadOrSignal;
-      const userSignal = payloadOrSignal instanceof AbortSignal ? payloadOrSignal : maybeSignal;
-
-      const timeoutSignal = this.timeout ? AbortSignal_.timeout(this.timeout) : undefined;
-      const signal = userSignal && timeoutSignal
-        ? AbortSignal_.any([userSignal, timeoutSignal])
-        : userSignal ?? timeoutSignal;
-
-      // Reject the request if the signal is aborted
-      if (signal?.aborted) return Promise.reject(signal.reason);
-      // or if the WebSocket connection is permanently closed
-      if (this._socket.terminationSignal.aborted) {
-        return Promise.reject(this._socket.terminationSignal.reason);
-      }
-
-      // Create a request
-      let id: string | number;
-      let request: SubscribeUnsubscribeRequest | PostRequest | PingRequest;
-      if (method === "post") {
-        id = ++this._lastId;
-        request = { method, id, request: payload };
-      } else if (method === "ping") {
-        id = "ping";
-        request = { method };
-      } else {
-        request = { method, subscription: payload };
-        id = WebSocketPostRequest.requestToId(request);
-      }
-
-      // Send the request
-      this._socket.send(JSON.stringify(request));
-
-      // Wait for a response
-      const { promise, resolve, reject } = Promise_.withResolvers<T>();
-      this._queue.push({ id, resolve, reject });
-
-      const onAbort = () => reject(signal?.reason);
-      signal?.addEventListener("abort", onAbort, { once: true });
-
-      return await promise.finally(() => {
-        const index = this._queue.findIndex((item) => item.id === id);
-        if (index !== -1) this._queue.splice(index, 1);
-
-        signal?.removeEventListener("abort", onAbort);
-      });
-    } catch (error) {
-      if (error instanceof TransportError) throw error; // Re-throw known errors
-      throw new WebSocketRequestError(
-        `Unknown error while making a WebSocket request: ${error}`,
-        { cause: error },
-      );
-    }
-  }
-
-  /** Normalizes an object and then converts it to a string. */
-  static requestToId(value: unknown): string {
-    const sortedKeys = recursiveSortObjectKeys(value);
-    const lowercasedHex = recursiveHexToLowercase(sortedKeys);
-    return JSON.stringify(lowercasedHex);
-  }
-}
-
-function recursiveSortObjectKeys<T>(obj: T): T {
-  if (Array.isArray(obj)) {
-    return obj.map(recursiveSortObjectKeys) as T;
-  }
-  if (typeof obj === "object" && obj !== null) {
-    const result: Record<string, unknown> = {};
-    for (const key of Object.keys(obj).sort()) {
-      result[key] = recursiveSortObjectKeys((obj as Record<string, unknown>)[key]);
-    }
-    return result as T;
-  }
-  return obj;
-}
-
-function recursiveHexToLowercase(value: unknown): unknown {
-  if (typeof value === "string" && /^0[xX][0-9a-fA-F]+$/.test(value)) {
-    return value.toLowerCase();
-  }
-  if (Array.isArray(value)) {
-    return value.map(recursiveHexToLowercase);
-  }
-  if (typeof value === "object" && value !== null) {
-    const result: Record<string, unknown> = {};
-    for (const key in value) {
-      result[key] = recursiveHexToLowercase((value as Record<string, unknown>)[key]);
-    }
-    return result;
-  }
-  return value;
-}
-
-/** Checks if `subset` is a subset of `superset` (all fields in subset exist in superset with same values). */
-function isSubset(subset: unknown, superset: unknown): boolean {
-  // Strings: compare hex addresses case-insensitively, others strictly
-  if (typeof subset === "string" && typeof superset === "string") {
-    const hexRegex = /^0x[0-9a-f]+$/i;
-    return hexRegex.test(subset) && hexRegex.test(superset)
-      ? subset.toLowerCase() === superset.toLowerCase()
-      : subset === superset;
-  }
-
-  // Primitives or type mismatch
-  if (typeof subset !== "object" || typeof superset !== "object" || subset === null || superset === null) {
-    return subset === superset;
-  }
-
-  // Arrays: must match element by element
-  if (Array.isArray(subset)) {
-    return Array.isArray(superset) &&
-      subset.length === superset.length &&
-      subset.every((item, i) => isSubset(item, superset[i]));
-  }
-
-  // Objects: all keys in subset must exist in superset with matching values
-  const sub = subset as Record<string, unknown>;
-  const sup = superset as Record<string, unknown>;
-  return Object.keys(sub).every((key) => key in sup && isSubset(sub[key], sup[key]));
-}