@hfunlabs/hyperliquid 0.27.1-hfunlabs.1

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

@@ -0,0 +1,218 @@
+import { type IRequestTransport, TransportError } from "../base.js";
+import { AbortSignal_ } from "../_polyfills.js";
+
+type MaybePromise<T> = T | Promise<T>;
+
+/** Error thrown when an HTTP request fails. */
+export class HttpRequestError extends TransportError {
+  response?: Response;
+  body?: string;
+
+  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 error while making an HTTP request: ${options?.cause}`;
+    }
+
+    super(message, options);
+    this.name = "HttpRequestError";
+    this.response = response;
+    this.body = body;
+  }
+}
+
+/** Configuration options for the HTTP transport layer. */
+export interface HttpTransportOptions {
+  /**
+   * Specifies whether to use the testnet API endpoints from the {@linkcode server} property.
+   * @default false
+   */
+  isTestnet?: boolean;
+  /**
+   * Request timeout in ms. Set to `null` to disable.
+   * @default 10_000
+   */
+  timeout?: number | null;
+  /**
+   * Custom server to use for API requests.
+   * @default `https://api.hyperliquid.xyz` for mainnet and `https://api.hyperliquid-testnet.xyz` for testnet.
+   */
+  server?: {
+    mainnet?: { api?: string | URL; rpc?: string | URL };
+    testnet?: { api?: string | URL; rpc?: string | URL };
+  };
+  /** A custom [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) that is merged with a fetch request. */
+  fetchOptions?: Omit<RequestInit, "body" | "method">;
+  /**
+   * A callback function that is called before the request is sent.
+   * @param request - An original request to send.
+   * @returns If returned a [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request/Request), it will replace the original request.
+   */
+  onRequest?: (request: Request) => MaybePromise<Request | void | null | undefined>;
+  /**
+   * A callback function that is called after the response is received.
+   * @param response - An original response to process.
+   * @returns If returned a [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response), it will replace the original response.
+   */
+  onResponse?: (response: Response) => MaybePromise<Response | void | null | undefined>;
+  /**
+   * A callback function that is called when an error occurs during fetching.
+   * @param error - The error that occurred.
+   * @returns If returned an [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error), it will be thrown instead of the original error (still wraps an error in {@linkcode HttpRequestError}).
+   */
+  onError?: (error: unknown) => MaybePromise<Error | void | null | undefined>;
+}
+
+/** HTTP implementation of the REST transport interface. */
+export class HttpTransport implements IRequestTransport, HttpTransportOptions {
+  isTestnet: boolean;
+  timeout: number | null;
+  server: {
+    mainnet: { api: string | URL; rpc: string | URL };
+    testnet: { api: string | URL; rpc: string | URL };
+  };
+  fetchOptions: Omit<RequestInit, "body" | "method">;
+  onRequest?: (request: Request) => MaybePromise<Request | void | null | undefined>;
+  onResponse?: (response: Response) => MaybePromise<Response | void | null | undefined>;
+  onError?: (error: unknown) => MaybePromise<Error | void | null | undefined>;
+
+  /**
+   * 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.server = {
+      mainnet: {
+        api: options?.server?.mainnet?.api ?? "https://api.hyperliquid.xyz",
+        rpc: options?.server?.mainnet?.rpc ?? "https://rpc.hyperliquid.xyz",
+      },
+      testnet: {
+        api: options?.server?.testnet?.api ?? "https://api.hyperliquid-testnet.xyz",
+        rpc: options?.server?.testnet?.rpc ?? "https://rpc.hyperliquid-testnet.xyz",
+      },
+    };
+    this.fetchOptions = options?.fetchOptions ?? {};
+    this.onRequest = options?.onRequest;
+    this.onResponse = options?.onResponse;
+    this.onError = options?.onError;
+  }
+
+  /**
+   * Sends a request to the Hyperliquid API via fetch.
+   * @param endpoint - The API endpoint to send the request to.
+   * @param payload - The payload to send with the request.
+   * @param signal - An [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) can be used to cancel the request by calling [`abort()`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort) on the corresponding [`AbortController`](https://developer.mozilla.org/en-US/docs/Web/API/AbortController).
+   * @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,
+        this.server[this.isTestnet ? "testnet" : "mainnet"][endpoint === "explorer" ? "rpc" : "api"],
+      );
+      const init = 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 },
+      );
+      let request = new Request(url, init);
+
+      // Call the onRequest callback, if provided
+      if (this.onRequest) {
+        const customRequest = await this.onRequest(request);
+        if (customRequest instanceof Request) request = customRequest;
+      }
+
+      // Send the Request and wait for a Response
+      let response = await fetch(request)
+        .catch(async (error) => {
+          if (this.onError) {
+            const customError = await this.onError(error);
+            if (customError instanceof Error) error = customError;
+          }
+          throw error;
+        });
+
+      // Call the onResponse callback, if provided
+      if (this.onResponse) {
+        const customResponse = await this.onResponse(response);
+        if (customResponse instanceof Response) response = customResponse;
+      }
+
+      // 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 [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/Headers). */
+function mergeHeadersInit(...inits: HeadersInit[]): Headers {
+  if (inits.length === 0 || inits.length === 1) {
+    return new Headers(inits[0] as HeadersInit | undefined);
+  }
+
+  const merged = new Headers();
+  for (const headers of inits) {
+    const iterator = Symbol.iterator in headers ? headers : Object.entries(headers);
+    for (const [key, value] of iterator) {
+      merged.set(key, value);
+    }
+  }
+  return merged;
+}
+
+/** Merges multiple [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) into one [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit). */
+function mergeRequestInit(...inits: RequestInit[]): RequestInit {
+  const merged = inits.reduce((acc, init) => ({ ...acc, ...init }), {});
+
+  const headersList = inits.map((init) => init.headers)
+    .filter((headers) => typeof headers === "object");
+  if (headersList.length > 0) {
+    merged.headers = mergeHeadersInit(...headersList);
+  }
+
+  const signals = inits.map((init) => init.signal)
+    .filter((signal) => signal instanceof AbortSignal);
+  if (signals.length > 0) {
+    merged.signal = signals.length > 1 ? AbortSignal_.any(signals) : signals[0];
+  }
+
+  return merged;
+}

package/src/src/transport/websocket/_hyperliquid_event_target.ts

@@ -0,0 +1,137 @@
+import * as v from "valibot";
+import { CustomEvent_ } from "../_polyfills.js";
+
+/** Response to subscribe to or unsubscribe from an event. */
+interface SubscribeUnsubscribeResponse {
+  /** Type of response */
+  method: "subscribe" | "unsubscribe";
+  /** Original request. */
+  subscription: unknown;
+}
+
+/** Response to post request. */
+interface PostResponse {
+  /** Unique request identifier. */
+  id: number;
+  /** Server response. */
+  response:
+    /** Response containing requested information. */
+    | {
+      /** Indicates that this is an informational response. */
+      type: "info";
+      /** Contains the information data. */
+      payload: {
+        /** Type of information being returned. */
+        type: string;
+        /** Information specific data. */
+        data: unknown;
+      };
+    }
+    /** Response containing action result. */
+    | {
+      /** Indicates that this is an action response. */
+      type: "action";
+      /** Action result. */
+      payload: {
+        /** Response status indicating success or failure of the action. */
+        status: "ok" | "err";
+        /** Success data or error message. */
+        response:
+          | {
+            /** Type of operation. */
+            type: string;
+            /** Specific data for the action. */
+            data?: unknown;
+          }
+          | string;
+      };
+    }
+    /** Response containing error message. */
+    | {
+      /** Indicates that this is an action response. */
+      type: "error";
+      /** Contains the error message, e.g. 429 Too Many Requests */
+      payload: 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 BlockDetails = /* @__PURE__ */ (() => {
+  return v.pipe(
+    v.object({
+      blockTime: v.pipe(v.number(), v.integer(), v.minValue(0)),
+      hash: v.pipe(v.string(), v.regex(/^0[xX][0-9a-fA-F]+$/), v.length(66)),
+      height: v.pipe(v.number(), v.integer(), v.minValue(0)),
+      numTxs: v.pipe(v.number(), v.integer(), v.minValue(0)),
+      proposer: v.pipe(v.string(), v.regex(/^0[xX][0-9a-fA-F]+$/), v.length(42)),
+    }),
+  );
+})();
+type BlockDetails = v.InferOutput<typeof BlockDetails>;
+const TxDetails = /* @__PURE__ */ (() => {
+  return v.object({
+    action: v.looseObject({ type: v.string() }),
+    block: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    error: v.nullable(v.string()),
+    hash: v.pipe(v.string(), v.regex(/^0[xX][0-9a-fA-F]+$/), v.length(66)),
+    time: v.pipe(v.number(), v.integer(), v.minValue(0)),
+    user: v.pipe(v.string(), v.regex(/^0[xX][0-9a-fA-F]+$/), v.length(42)),
+  });
+})();
+type TxDetails = v.InferOutput<typeof TxDetails>;
+
+const HyperliquidEventSchema = /* @__PURE__ */ (() => {
+  return v.object({ channel: v.string(), data: v.unknown() });
+})();
+const ExplorerBlockEventSchema = /* @__PURE__ */ (() => {
+  return v.pipe(v.array(BlockDetails), v.minLength(1));
+})();
+const ExplorerTxsEventSchema = /* @__PURE__ */ (() => {
+  return v.pipe(v.array(TxDetails), v.minLength(1));
+})();
+
+/** Listens for WebSocket messages and sends them as Hyperliquid typed events. */
+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(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
+      }
+    });
+  }
+}
+
+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;
+}

package/src/src/transport/websocket/_websocket_async_request.ts

@@ -0,0 +1,242 @@
+import { TransportError } from "../base.js";
+import { Promise_ } from "../_polyfills.js";
+import type { ReconnectingWebSocket } from "@nktkas/rews";
+import type { HyperliquidEventTarget } from "./_hyperliquid_event_target.js";
+
+interface PostRequest {
+  method: "post";
+  id: number;
+  request: unknown;
+}
+interface SubscribeUnsubscribeRequest {
+  method: "subscribe" | "unsubscribe";
+  subscription: unknown;
+}
+interface PingRequest {
+  method: "ping";
+}
+
+/** 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 requests to the Hyperliquid API.
+ * Handles request creation, sending, and mapping responses to their corresponding requests.
+ */
+export class WebSocketAsyncRequest {
+  protected socket: ReconnectingWebSocket;
+  protected lastId = 0;
+  protected queue: {
+    id: number | string;
+    // deno-lint-ignore no-explicit-any
+    resolve: (value?: any) => void;
+    // deno-lint-ignore no-explicit-any
+    reject: (reason?: any) => void;
+  }[] = [];
+  /** Timestamp of the last request sent. */
+  lastRequestTime = 0;
+
+  /**
+   * 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
+   */
+  constructor(socket: ReconnectingWebSocket, hlEvents: HyperliquidEventTarget) {
+    this.socket = socket;
+
+    // Monitor responses and match the pending request
+    hlEvents.addEventListener("subscriptionResponse", (event) => {
+      const id = WebSocketAsyncRequest.requestToId(event.detail);
+      this.queue.find((x) => x.id === id)?.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 {
+        // 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 = WebSocketAsyncRequest.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 = WebSocketAsyncRequest.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 = WebSocketAsyncRequest.requestToId({
+            method: "unsubscribe",
+            subscription: parsedRequest,
+          });
+          this.queue.find((x) => x.id === id)
+            ?.reject(new WebSocketRequestError(event.detail));
+          return;
+        }
+
+        // For unknown requests
+        const id = WebSocketAsyncRequest.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> {
+    const payload = payloadOrSignal instanceof AbortSignal ? undefined : payloadOrSignal;
+    const signal = payloadOrSignal instanceof AbortSignal ? payloadOrSignal : maybeSignal;
+
+    // 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 = WebSocketAsyncRequest.requestToId(request);
+    }
+
+    // Send the request
+    this.socket.send(JSON.stringify(request));
+    this.lastRequestTime = Date.now();
+
+    // 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);
+    });
+  }
+
+  /** Normalizes an object and then converts it to a string. */
+  static requestToId(value: unknown): string {
+    const transformed = deepTransform(value, [
+      // sort object keys
+      (v) => {
+        if (typeof v !== "object" || v === null || Array.isArray(v)) return v;
+
+        const out: Record<string, unknown> = {};
+        for (const key of Object.keys(v).sort()) {
+          out[key] = (v as Record<string, unknown>)[key];
+        }
+        return out;
+      },
+      // hex to lowercase
+      (v) => typeof v === "string" && /^0[xX][0-9a-fA-F]+$/.test(v) ? v.toLowerCase() : v,
+    ]);
+    return JSON.stringify(transformed); // also removes undefined values
+  }
+}
+
+/**
+ * Recursively transforms object/array values using a sequence of transformers.
+ *
+ * Issues:
+ * - does not support circular references
+ * - Symbol-keys are not preserved
+ */
+function deepTransform(obj: unknown, transformers: ((value: unknown, key?: string) => unknown)[]): unknown {
+  const transform = (val: unknown, key?: string): unknown => {
+    // Apply all transformers in sequence
+    const transformed = transformers.reduce((acc, fn) => acc === undefined ? undefined : fn(acc, key), val);
+
+    // Recurse into arrays and objects
+    if (typeof transformed !== "object" || transformed === null) return transformed; // skip primitives
+    if (Array.isArray(transformed)) return transformed.map((v) => transform(v));
+
+    const out: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(transformed)) {
+      const transformedValue = transform(v, k);
+      out[k] = transformedValue;
+    }
+    return out;
+  };
+
+  return transform(obj);
+}