@hfunlabs/hyperliquid 0.29.1-hfunlabs.1 → 0.30.2-hfunlabs.2

package/src/src/signing/_abstractWallet.ts

@@ -1,11 +1,11 @@
 import * as v from "valibot";
-import { HyperliquidError } from "../_errors.js";
+import { HyperliquidError } from "../_base.js";
 
 // =============================================================
 // Ethers V6
 // =============================================================
 
-/** Abstract interface for an [ethers.js v6](https://docs.ethers.org/v6/api/providers/#Signer) */
+/** Abstract interface for an {@link https://docs.ethers.org/v6/api/providers/#Signer | ethers.js v6} */
 export interface AbstractEthersV6Signer {
   signTypedData(
     domain: {
@@ -28,24 +28,26 @@ export interface AbstractEthersV6Signer {
     | null;
 }
 
-const AbstractEthersV6SignerSchema = v.object({
-  signTypedData: v.pipe(
-    v.function(),
-    v.check((fn) => fn.length === 3),
-  ),
-  getAddress: v.function(),
-  provider: v.nullish(
-    v.object({
-      getNetwork: v.function(),
-    }),
-  ),
-});
+const AbstractEthersV6SignerSchema = /* @__PURE__ */ (() => {
+  return v.object({
+    signTypedData: v.pipe(
+      v.function(),
+      v.check((fn) => fn.length === 3, "Number of arguments must be 3"),
+    ),
+    getAddress: v.function(),
+    provider: v.nullish(
+      v.object({
+        getNetwork: v.function(),
+      }),
+    ),
+  });
+})();
 
 // =============================================================
 // Ethers V5
 // =============================================================
 
-/** Abstract interface for an [ethers.js v5](https://docs.ethers.org/v5/api/signer/) */
+/** Abstract interface for an {@link https://docs.ethers.org/v5/api/signer/ | ethers.js v5} */
 export interface AbstractEthersV5Signer {
   _signTypedData(
     domain: {
@@ -68,24 +70,26 @@ export interface AbstractEthersV5Signer {
     | null;
 }
 
-const AbstractEthersV5SignerSchema = v.object({
-  _signTypedData: v.pipe(
-    v.function(),
-    v.check((fn) => fn.length === 3),
-  ),
-  getAddress: v.function(),
-  provider: v.nullish(
-    v.object({
-      getNetwork: v.function(),
-    }),
-  ),
-});
+const AbstractEthersV5SignerSchema = /* @__PURE__ */ (() => {
+  return v.object({
+    _signTypedData: v.pipe(
+      v.function(),
+      v.check((fn) => fn.length === 3, "Number of arguments must be 3"),
+    ),
+    getAddress: v.function(),
+    provider: v.nullish(
+      v.object({
+        getNetwork: v.function(),
+      }),
+    ),
+  });
+})();
 
 // =============================================================
 // Viem
 // =============================================================
 
-/** Abstract interface for a [viem JSON-RPC Account](https://viem.sh/docs/accounts/jsonRpc#json-rpc-account). */
+/** Abstract interface for a {@link https://viem.sh/docs/accounts/jsonRpc#json-rpc-account | viem JSON-RPC Account}. */
 export interface AbstractViemJsonRpcAccount {
   signTypedData(
     params: {
@@ -110,16 +114,18 @@ export interface AbstractViemJsonRpcAccount {
   getChainId(): Promise<number>;
 }
 
-const AbstractViemJsonRpcAccountSchema = v.object({
-  signTypedData: v.pipe(
-    v.function(),
-    v.check((fn) => fn.length === 1 || fn.length === 2),
-  ),
-  getAddresses: v.function(),
-  getChainId: v.function(),
-});
+const AbstractViemJsonRpcAccountSchema = /* @__PURE__ */ (() => {
+  return v.object({
+    signTypedData: v.pipe(
+      v.function(),
+      v.check((fn) => fn.length === 1 || fn.length === 2, "Number of arguments must be 1 or 2"),
+    ),
+    getAddresses: v.function(),
+    getChainId: v.function(),
+  });
+})();
 
-/** Abstract interface for a [viem Local Account](https://viem.sh/docs/accounts/local). */
+/** Abstract interface for a {@link https://viem.sh/docs/accounts/local | viem Local Account}. */
 export interface AbstractViemLocalAccount {
   signTypedData(
     params: {
@@ -143,13 +149,15 @@ export interface AbstractViemLocalAccount {
   address: `0x${string}`;
 }
 
-const AbstractViemLocalAccountSchema = v.object({
-  signTypedData: v.pipe(
-    v.function(),
-    v.check((fn) => fn.length === 1 || fn.length === 2),
-  ),
-  address: v.string(),
-});
+const AbstractViemLocalAccountSchema = /* @__PURE__ */ (() => {
+  return v.object({
+    signTypedData: v.pipe(
+      v.function(),
+      v.check((fn) => fn.length === 1 || fn.length === 2, "Number of arguments must be 1 or 2"),
+    ),
+    address: v.string(),
+  });
+})();
 
 // =============================================================
 // Abstract Signer
@@ -217,25 +225,19 @@ export async function signTypedData(args: {
         message,
       }) as `0x${string}`;
     } catch (error) {
-      throw new AbstractWalletError("Failed to sign typed data with viem wallet. See cause for details.", {
-        cause: error,
-      });
+      throw new AbstractWalletError("Failed to sign typed data with viem wallet", { cause: error });
     }
   } else if (v.is(AbstractEthersV6SignerSchema, wallet)) {
     try {
       signature = await wallet.signTypedData(domain, types, message) as `0x${string}`;
     } catch (error) {
-      throw new AbstractWalletError("Failed to sign typed data with ethers v6 wallet. See cause for details.", {
-        cause: error,
-      });
+      throw new AbstractWalletError("Failed to sign typed data with ethers v6 wallet", { cause: error });
     }
   } else if (v.is(AbstractEthersV5SignerSchema, wallet)) {
     try {
       signature = await wallet._signTypedData(domain, types, message) as `0x${string}`;
     } catch (error) {
-      throw new AbstractWalletError("Failed to sign typed data with ethers v5 wallet. See cause for details.", {
-        cause: error,
-      });
+      throw new AbstractWalletError("Failed to sign typed data with ethers v5 wallet", { cause: error });
     }
   } else {
     throw new AbstractWalletError("Failed to sign typed data: unknown wallet");
@@ -262,9 +264,7 @@ export async function getWalletChainId(wallet: AbstractWallet): Promise<`0x${str
       const chainId = await wallet.getChainId() as number;
       return `0x${chainId.toString(16)}`;
     } catch (error) {
-      throw new AbstractWalletError("Failed to get chain ID from viem wallet. See cause for details.", {
-        cause: error,
-      });
+      throw new AbstractWalletError("Failed to get chain ID from viem wallet", { cause: error });
     }
   }
   if (v.is(AbstractEthersV6SignerSchema, wallet)) {
@@ -273,9 +273,7 @@ export async function getWalletChainId(wallet: AbstractWallet): Promise<`0x${str
         const network = await wallet.provider.getNetwork() as { chainId: number | bigint };
         return `0x${network.chainId.toString(16)}`;
       } catch (error) {
-        throw new AbstractWalletError("Failed to get chain ID from ethers v6 wallet. See cause for details.", {
-          cause: error,
-        });
+        throw new AbstractWalletError("Failed to get chain ID from ethers v6 wallet", { cause: error });
       }
     }
   }
@@ -285,9 +283,7 @@ export async function getWalletChainId(wallet: AbstractWallet): Promise<`0x${str
         const network = await wallet.provider.getNetwork() as { chainId: number | bigint };
         return `0x${network.chainId.toString(16)}`;
       } catch (error) {
-        throw new AbstractWalletError("Failed to get chain ID from ethers v5 wallet. See cause for details.", {
-          cause: error,
-        });
+        throw new AbstractWalletError("Failed to get chain ID from ethers v5 wallet", { cause: error });
       }
     }
   }
@@ -301,9 +297,7 @@ export async function getWalletAddress(wallet: AbstractWallet): Promise<`0x${str
       const addresses = await wallet.getAddresses() as `0x${string}`[];
       return addresses[0].toLowerCase() as `0x${string}`;
     } catch (error) {
-      throw new AbstractWalletError("Failed to get address from viem wallet. See cause for details.", {
-        cause: error,
-      });
+      throw new AbstractWalletError("Failed to get address from viem wallet", { cause: error });
     }
   }
   if (v.is(AbstractViemLocalAccountSchema, wallet)) {
@@ -314,9 +308,7 @@ export async function getWalletAddress(wallet: AbstractWallet): Promise<`0x${str
       const address = await wallet.getAddress() as string;
       return address.toLowerCase() as `0x${string}`;
     } catch (error) {
-      throw new AbstractWalletError("Failed to get address from ethers wallet. See cause for details.", {
-        cause: error,
-      });
+      throw new AbstractWalletError("Failed to get address from ethers wallet", { cause: error });
     }
   }
   throw new AbstractWalletError("Failed to get wallet address: unknown wallet");

package/src/src/signing/mod.ts

@@ -1,5 +1,5 @@
 /**
- * This module contains functions for generating Hyperliquid transaction signatures.
+ * Low-level utilities for signing Hyperliquid transactions.
  *
  * @example Signing an L1 action
  * ```ts
@@ -63,7 +63,7 @@
 
 import { keccak_256 } from "@noble/hashes/sha3.js";
 import { bytesToHex, concatBytes, hexToBytes } from "@noble/hashes/utils.js";
-import { encode as encodeMsgpack, type ValueType } from "../../deps/jsr.io/@std/msgpack/1.0.3/mod.js";
+import { encode as encodeMsgpack, type ValueType } from "../../deps/jsr.io/@std/msgpack/1.0.3/encode.js";
 import { type AbstractWallet, type Signature, signTypedData } from "./_abstractWallet.js";
 
 export {
@@ -154,7 +154,7 @@ function largeIntToBigInt(obj: ValueType): ValueType {
   if (Array.isArray(obj)) return obj.map(largeIntToBigInt);
   if (typeof obj === "object" && obj !== null) {
     const result: Record<string, ValueType> = {};
-    for (const k in obj) result[k] = largeIntToBigInt(obj[k]);
+    for (const key in obj) result[key] = largeIntToBigInt(obj[key]);
     return result;
   }
   return obj;
@@ -164,9 +164,9 @@ function removeUndefinedKeys(obj: ValueType): ValueType {
   if (Array.isArray(obj)) return obj.map(removeUndefinedKeys);
   if (typeof obj === "object" && obj !== null) {
     const result: Record<string, ValueType> = {};
-    for (const k in obj) {
-      if (obj[k] !== undefined) {
-        result[k] = removeUndefinedKeys(obj[k]);
+    for (const key in obj) {
+      if (obj[key] !== undefined) {
+        result[key] = removeUndefinedKeys(obj[key]);
       }
     }
     return result;

package/src/src/transport/_base.ts

@@ -0,0 +1,57 @@
+import { HyperliquidError } from "../_base.js";
+
+/**
+ * Transport interface for executing requests to Hyperliquid servers.
+ *
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/info-endpoint | Info endpoint}
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint | Exchange endpoint}
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/post-requests | WebSocket POST requests}
+ */
+export interface IRequestTransport {
+  /** Indicates this transport uses testnet endpoint(s). */
+  isTestnet: boolean;
+  /**
+   * Sends a request to the Hyperliquid API.
+   *
+   * @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.
+   */
+  request<T>(endpoint: "info" | "exchange" | "explorer", payload: unknown, signal?: AbortSignal): Promise<T>;
+}
+
+/**
+ * Transport interface for WebSocket subscriptions (real-time updates).
+ *
+ * @see {@link https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/websocket/subscriptions | WebSocket subscriptions}
+ */
+export interface ISubscriptionTransport {
+  /**
+   * Subscribes to a Hyperliquid event channel.
+   *
+   * @param channel - The event channel to listen to.
+   * @param payload - The payload to send with the subscription request.
+   * @param listener - The function to call when the event is dispatched.
+   *
+   * @returns A promise that resolves with a {@link ISubscription} object to manage the subscription lifecycle.
+   */
+  subscribe<T>(channel: string, payload: unknown, listener: (data: CustomEvent<T>) => void): Promise<ISubscription>;
+}
+
+/** WebSocket subscription with failure signal. */
+export interface ISubscription {
+  /** Removes the event listener and unsubscribes from the event channel. */
+  unsubscribe(): Promise<void>;
+  /** {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal} that is aborted if the subscription fails to restore after reconnection. */
+  failureSignal: AbortSignal;
+}
+
+/** Thrown when an error occurs at the transport level (e.g., timeout). */
+export class TransportError extends HyperliquidError {
+  constructor(message?: string, options?: ErrorOptions) {
+    super(message, options);
+    this.name = "TransportError";
+  }
+}

package/src/src/transport/_polyfills.ts

@@ -12,6 +12,16 @@ export const Promise_ = /* @__PURE__ */ (() => {
   };
 })();
 
+/** @see https://developer.mozilla.org/en-US/docs/Web/API/DOMException */
+export const DOMException_ = /* @__PURE__ */ (() => {
+  return globalThis.DOMException || class DOMExceptionPolyfill extends Error {
+    constructor(message = "", name = "Error") {
+      super(message);
+      this.name = name;
+    }
+  };
+})();
+
 export const AbortSignal_ = /* @__PURE__ */ (() => {
   return {
     /** @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/any_static */
@@ -34,7 +44,7 @@ export const AbortSignal_ = /* @__PURE__ */ (() => {
     /** @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal/timeout_static */
     timeout: AbortSignal.timeout ? (ms: number) => AbortSignal.timeout(ms) : (ms: number) => {
       const controller = new AbortController();
-      setTimeout(() => controller.abort(new DOMException("Signal timed out.", "TimeoutError")), ms);
+      setTimeout(() => controller.abort(new DOMException_("Signal timed out.", "TimeoutError")), ms);
       return controller.signal;
     },
   };
@@ -42,7 +52,7 @@ export const AbortSignal_ = /* @__PURE__ */ (() => {
 
 /** @see https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent */
 export const CustomEvent_ = /* @__PURE__ */ (() => {
-  return globalThis.CustomEvent || class<T> extends Event {
+  return globalThis.CustomEvent || class CustomEventPolyfill<T> extends Event {
     readonly detail: T | null;
     constructor(type: string, eventInitDict?: CustomEventInit<T>) {
       super(type, eventInitDict);

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

@@ -1,4 +1,22 @@
-import { TransportError } from "../../_errors.js";
+/**
+ * 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. */
@@ -10,6 +28,7 @@ export class HttpRequestError extends TransportError {
 
   /**
    * 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.
@@ -40,26 +59,22 @@ export interface HttpTransportOptions {
    * @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 [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) that is merged with a fetch request. */
+  /** 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">;
 }
 
@@ -78,15 +93,21 @@ export const TESTNET_RPC_URL = "https://rpc.hyperliquid-testnet.xyz";
  * @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 HttpTransportOptions {
+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) {
@@ -98,11 +119,11 @@ export class HttpTransport implements HttpTransportOptions {
   }
 
   /**
-   * Sends a request to the Hyperliquid API via [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API).
+   * 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 - [AbortSignal](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) to cancel 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.
    *
@@ -153,7 +174,7 @@ export class HttpTransport implements HttpTransportOptions {
     }
   }
 
-  /** Merges multiple `HeadersInit` into one [`Headers`](https://developer.mozilla.org/en-US/docs/Web/API/Headers/Headers). */
+  /** 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) {
@@ -165,7 +186,7 @@ export class HttpTransport implements HttpTransportOptions {
     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). */
+  /** 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[] = [];

package/src/src/transport/mod.ts

@@ -0,0 +1,19 @@
+/**
+ * Transport layer for executing requests to Hyperliquid servers.
+ *
+ * Use {@link HttpTransport} for HTTP POST requests, and {@link WebSocketTransport} for subscriptions and WebSocket POST
+ * requests.
+ *
+ * @example
+ * ```ts
+ * import { HttpTransport } from "@nktkas/hyperliquid";
+ *
+ * const transport = new HttpTransport();
+ * ```
+ *
+ * @module
+ */
+
+export * from "./_base.js";
+export * from "./http/mod.js";
+export * from "./websocket/mod.js";

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

@@ -88,10 +88,10 @@ const PongEventSchema = /* @__PURE__ */ (() => {
   return v.object({ channel: v.literal("pong") });
 })();
 const ExplorerBlockEventSchema = /* @__PURE__ */ (() => {
-  return v.pipe(v.array(BlockDetailsSchema), v.minLength(1));
+  return v.pipe(v.array(BlockDetailsSchema), v.nonEmpty());
 })();
 const ExplorerTxsEventSchema = /* @__PURE__ */ (() => {
-  return v.pipe(v.array(TxDetailsSchema), v.minLength(1));
+  return v.pipe(v.array(TxDetailsSchema), v.nonEmpty());
 })();
 
 /** Listens for WebSocket messages and sends them as Hyperliquid typed events. */