@lifi/perps-sdk 0.2.0-alpha.0 → 1.0.0

package/dist/types/websocket/WsProviderBase.d.ts

@@ -0,0 +1,89 @@
+import type { Subscription, SubscriptionEvent } from '@lifi/perps-types';
+import type { ProviderGetQuoteParams, QuoteListener } from '../types/provider.js';
+import type { ReconnectingWebSocket } from './ReconnectingWebSocket.js';
+import type { SubscriptionListener, WsProvider, WsStatusListener } from './types.js';
+/**
+ * Linger before tearing a channel off the wire after its last listener
+ * releases. A re-subscribe to the same key within this window cancels the
+ * pending teardown, so React StrictMode's synchronous unmount→remount (ref
+ * count 1→0→1) and fast route flips collapse to one wire subscription rather
+ * than a subscribe→unsubscribe→subscribe churn the venue would reject.
+ *
+ * @public
+ */
+export declare const WS_CHANNEL_TEARDOWN_LINGER_MS = 250;
+/**
+ * Base for per-provider realtime transports. Owns the {@link
+ * ReconnectingWebSocket}, the fan-out lifecycle — ref-counted multi-listener
+ * subscription per channel key, deferred teardown, status fan-out — so any
+ * number of consumers (and StrictMode double-mounts) collapse to exactly one
+ * wire subscribe/unsubscribe per key, and the wire-subscription registry:
+ * subs recorded via {@link WsProviderBase.registerSub} are sent only while
+ * connected and replayed (failure-isolated) on every (re)open. Subclasses own
+ * everything wire-specific via {@link WsProviderBase.openChannel}, {@link
+ * WsProviderBase.sendSubscribe} and {@link WsProviderBase.handleMessage}:
+ * payload framing, frame validation and dispatch.
+ *
+ * `TSub` is the per-subscription state {@link WsProviderBase.sendSubscribe}
+ * needs to (re)build one subscribe frame.
+ *
+ * @public
+ */
+export declare abstract class WsProviderBase<TSub = unknown> implements WsProvider {
+    protected readonly rws: ReconnectingWebSocket;
+    protected readonly providerKey: string;
+    private readonly channels;
+    private readonly statusListeners;
+    private readonly wireSubs;
+    constructor(rws: ReconnectingWebSocket, providerKey: string);
+    subscribe(sub: Subscription, listener: SubscriptionListener, onStatus?: WsStatusListener): Promise<() => void>;
+    reconnect(): void;
+    close(): void;
+    /** Deliver an event to every listener on `key`. */
+    protected emit(key: string, event: SubscriptionEvent): void;
+    /**
+     * Tear `key` off the wire immediately if no listener holds it — i.e. it is
+     * lingering in the deferred-teardown window (or its open is still
+     * unwinding). Returns `true` when the key is free (absent or just torn
+     * down), `false` — leaving the channel untouched — while live listeners
+     * hold it. Lets a subclass that enforces an exclusivity invariant across
+     * keys reclaim a released channel without waiting out the linger.
+     */
+    protected closeChannelIfIdle(key: string): boolean;
+    /**
+     * Record a wire subscription for replay-on-(re)open and, when the socket is
+     * already connected, send its subscribe frame via {@link sendSubscribe}.
+     * While the socket is down the replay loop on the next open is the sole
+     * sender — sending in both places would double-subscribe. A failed send
+     * removes the sub again so a rejected open leaves no registry entry behind.
+     */
+    protected registerSub(key: string, state: TSub): Promise<void>;
+    /** Forget a wire subscription so the next (re)open no longer replays it. */
+    protected unregisterSub(key: string): void;
+    private replaySubs;
+    /** Venue-specific {@link WsProvider.subscribeQuote}; see `resolveSubscribeQuote`. */
+    abstract subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
+    /** Canonical fan-out key for `sub`; must match the key the subclass emits to. */
+    protected abstract toKey(sub: Subscription): string;
+    /**
+     * Open the channel on the wire (0→1 transition only). Record the wire
+     * sub(s) via {@link registerSub} and return a closure that unregisters them
+     * and sends the unsubscribe frame(s).
+     */
+    protected abstract openChannel(sub: Subscription): Promise<() => void>;
+    /**
+     * Encode and send the subscribe frame for one registered sub. Called by the
+     * base while connected — once on register and again on every (re)open — so
+     * it must be safe to invoke repeatedly with the same state (e.g. re-fetch a
+     * fresh auth token per call rather than embedding one in `state`).
+     */
+    protected abstract sendSubscribe(state: TSub): void | Promise<void>;
+    /** Parse one inbound frame and route it via {@link emit}. */
+    protected abstract handleMessage(raw: string): void;
+    /** Release subclass-only resources on {@link close} (keep-alive, cached state). */
+    protected onClose(): void;
+    private callListener;
+    private acquireChannel;
+    private releaseChannel;
+}
+//# sourceMappingURL=WsProviderBase.d.ts.map

package/dist/types/websocket/WsProviderBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WsProviderBase.d.ts","sourceRoot":"","sources":["../../../src/websocket/WsProviderBase.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACd,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAA;AACvE,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,gBAAgB,EACjB,MAAM,YAAY,CAAA;AAGnB;;;;;;;;GAQG;AACH,eAAO,MAAM,6BAA6B,MAAM,CAAA;AAiBhD;;;;;;;;;;;;;;;;GAgBG;AACH,8BAAsB,cAAc,CAAC,IAAI,GAAG,OAAO,CAAE,YAAW,UAAU;IACxE,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAA;IAC7C,SAAS,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAEtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkC;IAC3D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAsC;IACtE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;gBAEvC,GAAG,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM;IAcrD,SAAS,CACb,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC;IA2BtB,SAAS,IAAI,IAAI;IAOjB,KAAK,IAAI,IAAI;IAab,mDAAmD;IACnD,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,iBAAiB,GAAG,IAAI;IAU3D;;;;;;;OAOG;IACH,SAAS,CAAC,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAgBlD;;;;;;OAMG;cACa,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAapE,4EAA4E;IAC5E,SAAS,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;YAI5B,UAAU;IAaxB,qFAAqF;IACrF,QAAQ,CAAC,cAAc,CACrB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC;IAEtB,iFAAiF;IACjF,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM;IAEnD;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC;IAEtE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEnE,6DAA6D;IAC7D,SAAS,CAAC,QAAQ,CAAC,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAEnD,mFAAmF;IACnF,SAAS,CAAC,OAAO,IAAI,IAAI;IAEzB,OAAO,CAAC,YAAY;YAYN,cAAc;IAgD5B,OAAO,CAAC,cAAc;CAwCvB"}

package/dist/types/websocket/cachePromise.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Single-flight a promise through a caller-owned cache slot, evicting the
+ * cached promise if it rejects so the next call retries cleanly.
+ *
+ * Concurrent callers share the one in-flight promise; the rejection still
+ * propagates to every awaiter that triggered it. Only a settled rejection is
+ * evicted — a resolved promise stays cached.
+ *
+ * @param read - Returns the currently cached promise, or `undefined` if none.
+ * @param write - Stores (or with `undefined`, clears) the cached promise.
+ * @param factory - Creates the promise when the slot is empty.
+ */
+export declare function cachePromise<T>(read: () => Promise<T> | undefined, write: (promise: Promise<T> | undefined) => void, factory: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=cachePromise.d.ts.map

package/dist/types/websocket/cachePromise.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cachePromise.d.ts","sourceRoot":"","sources":["../../../src/websocket/cachePromise.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,EAClC,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,KAAK,IAAI,EAChD,OAAO,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GACxB,OAAO,CAAC,CAAC,CAAC,CAaZ"}

package/dist/types/websocket/types.d.ts

@@ -0,0 +1,60 @@
+import type { Subscription, SubscriptionEvent } from '@lifi/perps-types';
+import type { ProviderGetQuoteParams, QuoteListener } from '../types/provider.js';
+/**
+ * The concrete {@link SubscriptionEvent} variant a given subscription `S`
+ * emits, narrowed by its `channel`.
+ *
+ * @public
+ */
+export type EventForSubscription<S extends Subscription> = Extract<SubscriptionEvent, {
+    channel: S['channel'];
+}>;
+/**
+ * Listener invoked with each realtime {@link SubscriptionEvent}.
+ *
+ * @public
+ */
+export type SubscriptionListener = (event: SubscriptionEvent) => void;
+/**
+ * Health of a provider's underlying WS connection.
+ *
+ * - `connected` — socket open, live data flowing.
+ * - `reconnecting` — socket dropped; auto-reconnect with backoff in progress.
+ *   Data may be stale until it returns to `connected`.
+ * - `disconnected` — reconnection abandoned after the retry cap. The
+ *   connection is permanently dead and will not recover on its own; the
+ *   subscription's data is stale. Terminal.
+ *
+ * @public
+ */
+export type WsConnectionStatus = 'connected' | 'reconnecting' | 'disconnected';
+/**
+ * Listener invoked when the underlying WS connection's health changes.
+ *
+ * @public
+ */
+export type WsStatusListener = (status: WsConnectionStatus) => void;
+/**
+ * Per-provider realtime transport contract used by {@link PerpsWsClient}.
+ * Implemented by the provider packages' WS plugins.
+ *
+ * @public
+ */
+export interface WsProvider {
+    subscribe(sub: Subscription, listener: SubscriptionListener, onStatus?: WsStatusListener): Promise<() => void>;
+    /**
+     * Recover a terminally exhausted connection. Safe no-op unless status is
+     * `disconnected`.
+     */
+    reconnect(): void;
+    /**
+     * Stream live fill {@link Quote}s for `params.size` USD notional of
+     * `params.symbol` on this venue, layered on the orderbook channel: the
+     * provider resolves the symbol against its own markets and re-runs the
+     * one-shot quote transform on each (throttled) book update, applying its
+     * public base fee tier. Returns an idempotent unsubscribe.
+     */
+    subscribeQuote(params: ProviderGetQuoteParams, onQuote: QuoteListener): Promise<() => void>;
+    close(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types/websocket/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/websocket/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACxE,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACd,MAAM,sBAAsB,CAAA;AAE7B;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,YAAY,IAAI,OAAO,CAChE,iBAAiB,EACjB;IAAE,OAAO,EAAE,CAAC,CAAC,SAAS,CAAC,CAAA;CAAE,CAC1B,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;AAErE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,cAAc,GAAG,cAAc,CAAA;AAE9E;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,SAAS,CACP,GAAG,EAAE,YAAY,EACjB,QAAQ,EAAE,oBAAoB,EAC9B,QAAQ,CAAC,EAAE,gBAAgB,GAC1B,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IACtB;;;OAGG;IACH,SAAS,IAAI,IAAI,CAAA;IACjB;;;;;;OAMG;IACH,cAAc,CACZ,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC,CAAA;IACtB,KAAK,IAAI,IAAI,CAAA;CACd"}

package/dist/types/websocket/wsLog.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Structured logger for WS message-handling and subscription failures, shared
+ * by the provider packages so a malformed frame, a throwing mapper, or a failed
+ * resubscribe never vanishes silently.
+ *
+ * @internal
+ */
+export declare const wsLog: {
+    /**
+     * A single frame that could not be parsed as JSON. Expected to recur on a
+     * noisy stream, so logged at `warn` with a truncated payload — never fatal.
+     */
+    readonly parseFailure: (provider: string, raw: string) => void;
+    /**
+     * A frame parsed but its handler threw (mapper bug, `MarketNotFound`, …).
+     * This is unexpected and must surface; the frame is skipped so one bad
+     * frame does not stall the stream or starve other channels.
+     */
+    readonly handlerFailure: (provider: string, error: unknown) => void;
+    /**
+     * An `error`-channel frame the server pushed (e.g. a rejected or duplicate
+     * subscription). The frame parsed fine — this is the venue reporting a
+     * problem, not a malformed frame — so surface it at `error` with the
+     * server's own text rather than mislabelling it a parse failure.
+     */
+    readonly serverError: (provider: string, message: string) => void;
+    /**
+     * A channel's (re)subscribe threw while (re)opening the socket — e.g. an
+     * auth-token fetch rejected after a reconnect. Surfaced at `error`; the
+     * channel is skipped so one failure does not abort the others.
+     */
+    readonly subscribeFailure: (provider: string, channel: string, error: unknown) => void;
+    /**
+     * A frame item referenced a market id missing from the registry (e.g.
+     * listed after the snapshot). The item is skipped — never the whole frame —
+     * so logged at `warn`.
+     */
+    readonly unknownMarket: (provider: string, marketId: string) => void;
+    /**
+     * A background market-registry refetch rejected. Unknown-market items keep
+     * being skipped until the next cooldown-gated retry, so logged at `warn`.
+     */
+    readonly marketRefreshFailure: (provider: string, error: unknown) => void;
+    /**
+     * A consumer listener callback threw during fan-out. Logged and skipped so
+     * one bad listener cannot starve sibling listeners or break socket flow.
+     */
+    readonly listenerFailure: (provider: string, listenerType: string, error: unknown) => void;
+};
+//# sourceMappingURL=wsLog.d.ts.map

package/dist/types/websocket/wsLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsLog.d.ts","sourceRoot":"","sources":["../../../src/websocket/wsLog.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,eAAO,MAAM,KAAK;IAChB;;;OAGG;sCACoB,MAAM,OAAO,MAAM,KAAG,IAAI;IAGjD;;;;OAIG;wCACsB,MAAM,SAAS,OAAO,KAAG,IAAI;IAGtD;;;;;OAKG;qCACmB,MAAM,WAAW,MAAM,KAAG,IAAI;IAGpD;;;;OAIG;0CACwB,MAAM,WAAW,MAAM,SAAS,OAAO,KAAG,IAAI;IAMzE;;;;OAIG;uCACqB,MAAM,YAAY,MAAM,KAAG,IAAI;IAKvD;;;OAGG;8CAC4B,MAAM,SAAS,OAAO,KAAG,IAAI;IAG5D;;;OAGG;yCAES,MAAM,gBACF,MAAM,SACb,OAAO,KACb,IAAI;CAMC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifi/perps-sdk",
-  "version": "0.2.0-alpha.0",
+  "version": "1.0.0",
   "description": "LI.FI Perps SDK for perpetuals trading",
   "homepage": "https://github.com/lifinance/perps-sdk",
   "bugs": {
@@ -10,52 +10,22 @@
     "type": "git",
     "url": "https://github.com/lifinance/perps-sdk.git"
   },
-  "engines": {
-    "node": ">=24"
-  },
   "license": "Apache-2.0",
   "author": "LI.FI <dev@li.fi>",
   "type": "module",
-  "sideEffects": false,
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/types/index.d.ts",
   "typings": "./dist/types/index.d.ts",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
       "import": "./dist/esm/index.js",
       "default": "./dist/cjs/index.js"
     },
-    "./utils/hyperliquid": {
-      "types": "./dist/types/utils/hyperliquid/index.d.ts",
-      "import": "./dist/esm/utils/hyperliquid/index.js",
-      "default": "./dist/cjs/utils/hyperliquid/index.js"
-    },
-    "./wasm/*": "./wasm/*",
     "./package.json": "./package.json"
   },
-  "dependencies": {
-    "@lifi/perps-types": "0.2.0-alpha.0",
-    "viem": "2.48.8"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.13",
-    "@commitlint/cli": "^20.3.1",
-    "@commitlint/config-conventional": "^20.3.1",
-    "@types/node": "^25.2.3",
-    "@vitest/coverage-v8": "^2.1.8",
-    "husky": "^9.1.7",
-    "knip": "^5.82.1",
-    "madge": "^8.0.0",
-    "msw": "^2.7.0",
-    "standard-version": "^9.5.0",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
   "files": [
     "dist/**",
     "!dist/**/*.tsbuildinfo",
@@ -68,10 +38,17 @@
     "!**/__mocks__/**",
     "!*.tmp",
     "!*.env",
-    "!tsconfig.json",
-    "wasm/lighter-signer.wasm",
-    "wasm/wasm_exec.js"
+    "!tsconfig.json"
   ],
+  "dependencies": {
+    "@lifi/types": "17.82.1",
+    "partysocket": "^1.1.19",
+    "viem": "^2.48.8",
+    "@lifi/perps-types": "1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "keywords": [
     "perps",
     "perpetuals",
@@ -82,29 +59,5 @@
     "sdk",
     "viem",
     "hyperliquid"
-  ],
-  "scripts": {
-    "build": "pnpm clean && pnpm build:version && pnpm build:cjs && pnpm build:esm && pnpm build:types && pnpm build:wasm && pnpm build:clean",
-    "build:cjs": "tsc --project ./tsconfig.json --module commonjs --outDir ./dist/cjs --removeComments --verbatimModuleSyntax false && mkdir -p ./dist/cjs && printf '{\"type\":\"commonjs\"}' > ./dist/cjs/package.json",
-    "build:esm": "tsc --project ./tsconfig.json --module es2022 --outDir ./dist/esm && mkdir -p ./dist/esm && printf '{\"type\": \"module\",\"sideEffects\":false}' > ./dist/esm/package.json",
-    "build:wasm": "mkdir -p ./dist/esm/wasm ./dist/cjs/wasm && cp ./wasm/lighter-signer.wasm ./wasm/wasm_exec.js ./dist/esm/wasm/ && cp ./wasm/lighter-signer.wasm ./wasm/wasm_exec.js ./dist/cjs/wasm/",
-    "build:types": "tsc --project ./tsconfig.json --module esnext --declarationDir ./dist/types --emitDeclarationOnly --declaration --declarationMap",
-    "build:clean": "rm -rf tsconfig.tsbuildinfo ./dist/tsconfig.tsbuildinfo",
-    "build:version": "node scripts/version.js",
-    "clean": "pnpm build:clean && rm -rf dist",
-    "check": "biome check",
-    "check:write": "biome check --write",
-    "check:types": "tsc --noEmit",
-    "check:circular-deps": "madge --circular $(find ./src -name '*.ts')",
-    "knip:check": "knip --dependencies --files --no-config-hints --exclude binaries",
-    "knip:write": "pnpm knip:check --fix",
-    "release": "standard-version -a -s",
-    "release:alpha": "standard-version -a -s --prerelease alpha --skip.changelog",
-    "release:beta": "standard-version -a -s --prerelease beta --skip.changelog",
-    "test": "vitest --run",
-    "test:cov": "vitest --run --coverage",
-    "test:unit": "vitest --run .unit.spec.ts --passWithNoTests",
-    "pre-commit": "pnpm check && pnpm check:types && pnpm check:circular-deps && pnpm knip:check",
-    "pre-push": "pnpm test:unit"
-  }
+  ]
 }