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

package/dist/types/services/resolveQuote.d.ts

@@ -0,0 +1,36 @@
+import { type FeeTier, type Market, type MarketPrice, type Quote } from '@lifi/perps-types';
+import type { SDKRequestOptions } from '../types/config.js';
+import type { PerpsSDKClient, ProviderGetQuoteParams } from '../types/provider.js';
+/**
+ * Shared provider-side `getQuote` implementation: resolve `params.symbol` to a
+ * market on `provider` (matching `baseAsset.displaySymbol`, scoped by
+ * `params.type`), fetch the orderbook snapshot, and build the {@link Quote}
+ * with the provider's public base `feeTier`. Both venue plugins delegate here
+ * so symbol resolution and the book walk live in one place; each plugin only
+ * supplies its own base tier.
+ *
+ * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
+ * @internal
+ */
+export declare function resolveQuote(client: PerpsSDKClient, provider: string, params: ProviderGetQuoteParams, feeTier: FeeTier, options?: SDKRequestOptions): Promise<Quote>;
+/**
+ * Resolve `params.symbol` to a market on `provider` (matching
+ * `baseAsset.displaySymbol`, scoped by `params.type`). Shared by the one-shot
+ * {@link resolveQuote} and the streaming quote subscription so both quote the
+ * same market for a given symbol+type.
+ *
+ * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
+ * @internal
+ */
+export declare function resolveQuoteMarket(client: PerpsSDKClient, provider: string, params: Pick<ProviderGetQuoteParams, 'symbol' | 'type'>, options?: SDKRequestOptions): Promise<Market>;
+/**
+ * Fetch the live {@link MarketPrice} for `marketId` on `provider`, the source
+ * of the `markPrice` and `funding` a {@link Quote} carries. Shared by the
+ * one-shot {@link resolveQuote} and the streaming quote subscription.
+ *
+ * @throws {PerpsError} `ServerError` when the provider returns no price for the
+ * market.
+ * @internal
+ */
+export declare function resolveQuotePrice(client: PerpsSDKClient, provider: string, marketId: string, options?: SDKRequestOptions): Promise<MarketPrice>;
+//# sourceMappingURL=resolveQuote.d.ts.map

package/dist/types/services/resolveQuote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveQuote.d.ts","sourceRoot":"","sources":["../../../src/services/resolveQuote.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EACZ,KAAK,MAAM,EACX,KAAK,WAAW,EAEhB,KAAK,KAAK,EACX,MAAM,mBAAmB,CAAA;AAE1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAC3D,OAAO,KAAK,EACV,cAAc,EACd,sBAAsB,EACvB,MAAM,sBAAsB,CAAA;AAM7B;;;;;;;;;;GAUG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,KAAK,CAAC,CAqBhB;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,IAAI,CAAC,sBAAsB,EAAE,QAAQ,GAAG,MAAM,CAAC,EACvD,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,MAAM,CAAC,CAcjB;AAOD;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,WAAW,CAAC,CActB"}

package/dist/types/services/resolveSubscribeQuote.d.ts

@@ -0,0 +1,31 @@
+import type { FeeTier } from '@lifi/perps-types';
+import type { PerpsSDKClient, ProviderGetQuoteParams, QuoteListener } from '../types/provider.js';
+import type { WsProvider } from '../websocket/types.js';
+/**
+ * Minimum gap between successive streamed {@link Quote} emissions — the same
+ * 100 ms pacing applied to streamed orderbook rendering, so a quote ticks no
+ * faster than the book it derives from.
+ *
+ * @public
+ */
+export declare const QUOTE_THROTTLE_MS = 100;
+/**
+ * Shared provider-side `subscribeQuote` implementation: resolve
+ * `params.symbol` to a market on `provider` (via {@link resolveQuoteMarket}),
+ * subscribe to that market's orderbook channel on `ws`, and on each book
+ * update rebuild the {@link Quote} with the provider's public base `feeTier` —
+ * the same transform the one-shot `resolveQuote` applies to a REST snapshot.
+ * Emissions are throttled to {@link QUOTE_THROTTLE_MS}: the first book update
+ * emits immediately, then at most one (trailing, latest-book) emission per
+ * interval. Both venue WS plugins delegate here; each only supplies its own
+ * base tier.
+ *
+ * The returned unsubscribe is idempotent — it releases the underlying
+ * orderbook listener once and cancels any pending trailing emission, so the
+ * wire subscription's ref count cannot be double-decremented.
+ *
+ * @throws {PerpsError} `MarketNotFound` when no market matches symbol+type.
+ * @internal
+ */
+export declare function resolveSubscribeQuote(client: PerpsSDKClient, provider: string, ws: Pick<WsProvider, 'subscribe'>, params: ProviderGetQuoteParams, feeTier: FeeTier, onQuote: QuoteListener): Promise<() => void>;
+//# sourceMappingURL=resolveSubscribeQuote.d.ts.map

package/dist/types/services/resolveSubscribeQuote.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolveSubscribeQuote.d.ts","sourceRoot":"","sources":["../../../src/services/resolveSubscribeQuote.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAqB,MAAM,mBAAmB,CAAA;AACnE,OAAO,KAAK,EACV,cAAc,EACd,sBAAsB,EACtB,aAAa,EACd,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AAGvD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,MAAM,CAAA;AAEpC;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,EACjC,MAAM,EAAE,sBAAsB,EAC9B,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,GACrB,OAAO,CAAC,MAAM,IAAI,CAAC,CAgErB"}

package/dist/types/storage/parseStoredRecord.d.ts

@@ -0,0 +1,29 @@
+import type { StorageAdapter } from './types.js';
+/**
+ * Parse a persisted (browser-writable) JSON record and validate it against a
+ * caller-supplied shape guard. localStorage is user-writable, so a stored value
+ * may be truncated, hand-edited, or written by an older schema; `JSON.parse(...)
+ * as T` would type-check such a record yet carry missing/invalid fields that
+ * fail far from here.
+ *
+ * Returns the parsed value when `isValid` accepts it; returns `null` when the
+ * record is absent, unparseable, or fails validation (i.e. poisoned). A `null`
+ * result is the "malformed-or-absent" signal — callers decide whether that
+ * means "regenerate deliberately" or "surface an error", but they never get a
+ * structurally-invalid `T`.
+ *
+ * @param raw Stored string, or `null` when the key is absent.
+ * @param isValid Shape guard run against the parsed value.
+ */
+export declare function parseStoredRecord<T>(raw: string | null, isValid: (value: unknown) => value is T): T | null;
+/**
+ * Read and validate a persisted record in one step, evicting the key when the
+ * stored value is present but poisoned (unparseable or failing `isValid`) so a
+ * later read does not keep tripping over the same corrupt entry.
+ *
+ * Returns `null` for both the genuine-absence and the evicted-poison cases;
+ * callers that must distinguish them should compare against the pre-read
+ * presence of the key themselves.
+ */
+export declare function readValidatedRecord<T>(storage: StorageAdapter, key: string, isValid: (value: unknown) => value is T): Promise<T | null>;
+//# sourceMappingURL=parseStoredRecord.d.ts.map

package/dist/types/storage/parseStoredRecord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parseStoredRecord.d.ts","sourceRoot":"","sources":["../../../src/storage/parseStoredRecord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GACtC,CAAC,GAAG,IAAI,CAWV;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,EACzC,OAAO,EAAE,cAAc,EACvB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,KAAK,IAAI,CAAC,GACtC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAOnB"}

package/dist/{esm/agent → types/storage}/storage.d.ts

@@ -1,12 +1,15 @@
 import type { StorageAdapter } from './types.js';
 /**
- * localStorage adapter for browser environments.
- * Agent keys are stored as JSON strings with the key pattern:
- * `lifi-perps-agent:{address}:{provider}`
+ * localStorage adapter for browser environments. Falls back to a no-op when
+ * `localStorage` is unavailable (e.g. SSR).
+ *
+ * @public
  */
 export declare const localStorageAdapter: StorageAdapter;
 /**
  * In-memory storage adapter for testing or server-side use.
+ *
+ * @public
  */
 export declare function createMemoryStorage(): StorageAdapter;
 //# sourceMappingURL=storage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/storage/storage.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,EAAE,cA0BjC,CAAA;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,cAAc,CAkBpD"}

package/dist/types/storage/types.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Storage adapter interface for persisting SDK session credentials (provider
+ * agent keypairs, API keys, read-only tokens). Implement this to use custom
+ * storage (e.g. encrypted storage, a database, async key-value stores).
+ */
+export interface StorageAdapter {
+    /** Get a value by key. */
+    get(key: string): Promise<string | null>;
+    /** Set a value by key. */
+    set(key: string, value: string): Promise<void>;
+    /** Remove a value by key. */
+    remove(key: string): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/storage/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,0BAA0B;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACxC,0BAA0B;IAC1B,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9C,6BAA6B;IAC7B,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC"}

package/dist/types/transport/fetchWithRetry.d.ts

@@ -0,0 +1,22 @@
+import type { ResolvedRetryPolicy } from './retryPolicy.js';
+/**
+ * Options for {@link fetchWithRetry}.
+ *
+ * @public
+ */
+export interface FetchWithRetryOptions {
+    policy: ResolvedRetryPolicy;
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+}
+/**
+ * Wrap `fetch` with policy-driven retry. Honors `Retry-After` (when present
+ * and `respectRetryAfter` is true), otherwise falls back to exponential
+ * backoff with full jitter, capped by `maxDelayMs`. Network errors (thrown
+ * `fetch` rejections) are treated as `retry-network` — same retry budget as
+ * 5xx. An aborted signal short-circuits without further attempts.
+ *
+ * @public
+ */
+export declare function fetchWithRetry(input: RequestInfo | URL, init: RequestInit | undefined, options: FetchWithRetryOptions): Promise<Response>;
+//# sourceMappingURL=fetchWithRetry.d.ts.map

package/dist/types/transport/fetchWithRetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetchWithRetry.d.ts","sourceRoot":"","sources":["../../../src/transport/fetchWithRetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAuB,MAAM,kBAAkB,CAAA;AAEhF;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,mBAAmB,CAAA;IAC3B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;IACxB,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,GAAG,GAAG,EACxB,IAAI,EAAE,WAAW,GAAG,SAAS,EAC7B,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,QAAQ,CAAC,CAyDnB"}

package/dist/types/transport/request.d.ts

@@ -0,0 +1,25 @@
+import type { PerpsBaseConfig, SDKRequestOptions } from '../types/config.js';
+import { type RetryPolicy } from './retryPolicy.js';
+/**
+ * `RequestInit` plus a per-call retry override.
+ *
+ * @internal
+ */
+export interface RequestOptions extends RequestInit {
+    /** Per-call retry override. Falls back to the resolved client-level policy. */
+    retry?: RetryPolicy | false;
+}
+/**
+ * Internal HTTP helper: applies SDK headers, retry policy, and the request
+ * interceptor, then normalizes failures into {@link PerpsError}.
+ *
+ * @internal
+ */
+export declare function request<T>(config: PerpsBaseConfig, url: string, options?: RequestOptions, sdkOptions?: SDKRequestOptions): Promise<T>;
+/**
+ * Build a URL with a query string from defined params (skips `undefined`).
+ *
+ * @internal
+ */
+export declare function buildUrl(baseUrl: string, params: Record<string, string | number | boolean | undefined>): string;
+//# sourceMappingURL=request.d.ts.map

package/dist/types/transport/request.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.ts","sourceRoot":"","sources":["../../../src/transport/request.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAA;AAG5E,OAAO,EAGL,KAAK,WAAW,EAEjB,MAAM,kBAAkB,CAAA;AAEzB;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,+EAA+E;IAC/E,KAAK,CAAC,EAAE,WAAW,GAAG,KAAK,CAAA;CAC5B;AAED;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,CAAC,EAC7B,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,cAAmB,EAC5B,UAAU,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAmEZ;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,GAC5D,MAAM,CAWR"}

package/dist/types/transport/retryPolicy.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Provider key for LI.FI-backend-proxied requests in a
+ * {@link ProviderRetryConfig}.
+ *
+ * @public
+ */
+export declare const LIFI_REQUEST_KEY: "lifi";
+/**
+ * Outcome of classifying a response/error for retry: the three `retry-*`
+ * variants are retriable; `'fail'` is terminal.
+ *
+ * @public
+ */
+export type RetryClassification = 'retry-rate-limit' | 'retry-server' | 'retry-network' | 'fail';
+/**
+ * Context passed to a {@link RetryPolicy.classify} callback.
+ *
+ * @public
+ */
+export interface RetryClassifyContext {
+    response: Response;
+}
+/**
+ * Context passed to a {@link RetryPolicy.shouldRetry} callback for each
+ * attempt.
+ *
+ * @public
+ */
+export interface RetryAttemptContext {
+    attempt: number;
+    response?: Response;
+    error?: unknown;
+    classification: RetryClassification;
+}
+/**
+ * User-supplied retry tuning. All fields optional — anything left unset
+ * inherits the built-in default for the target provider. `classify` returning
+ * `undefined` defers to the base classifier; returning `'fail'` short-circuits
+ * retry. `shouldRetry` runs after `classify` has already decided to retry and
+ * gives a final yes/no per attempt.
+ *
+ * @public
+ */
+export interface RetryPolicy {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    respectRetryAfter?: boolean;
+    classify?: (ctx: RetryClassifyContext) => RetryClassification | undefined;
+    shouldRetry?: (ctx: RetryAttemptContext) => boolean | Promise<boolean>;
+}
+/**
+ * A fully resolved retry policy with every field populated — the form
+ * {@link fetchWithRetry} consumes.
+ *
+ * @public
+ */
+export interface ResolvedRetryPolicy {
+    enabled: boolean;
+    maxAttempts: number;
+    baseDelayMs: number;
+    maxDelayMs: number;
+    respectRetryAfter: boolean;
+    classify: (ctx: RetryClassifyContext) => RetryClassification;
+    shouldRetry?: (ctx: RetryAttemptContext) => boolean | Promise<boolean>;
+}
+/**
+ * Per-provider overrides keyed by the provider plugin's `type` (e.g. `'hyperliquid'`,
+ * `'lighter'`), plus `'lifi'` for backend-proxied requests. `default` is the
+ * fallback applied to any provider not explicitly listed.
+ *
+ * @public
+ */
+export interface ProviderRetryConfig {
+    default?: RetryPolicy | false;
+    [providerKey: string]: RetryPolicy | false | undefined;
+}
+/**
+ * Top-level `retry` option: a flat {@link RetryPolicy} for all providers,
+ * `false` to disable retries, or a per-provider {@link ProviderRetryConfig}.
+ *
+ * @public
+ */
+export type RetryConfig = RetryPolicy | false | ProviderRetryConfig;
+/**
+ * Built-in default retry policy for LI.FI-backend requests.
+ *
+ * @public
+ */
+export declare const LIFI_RETRY_DEFAULTS: ResolvedRetryPolicy;
+/**
+ * A resolved policy that performs a single attempt with no retries.
+ *
+ * @public
+ */
+export declare const DISABLED_RETRY: ResolvedRetryPolicy;
+/**
+ * Merge a user-supplied {@link RetryConfig} onto a provider's built-in default.
+ * Resolution order when `config` is a {@link ProviderRetryConfig}:
+ * `config[providerKey]` → `config.default` → `base`. A flat {@link RetryPolicy}
+ * applies to every provider. `false` (at any level) disables retries entirely.
+ *
+ * @public
+ */
+export declare function resolveRetryPolicy(base: ResolvedRetryPolicy, config: RetryConfig | undefined, providerKey: string): ResolvedRetryPolicy;
+//# sourceMappingURL=retryPolicy.d.ts.map

package/dist/types/transport/retryPolicy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retryPolicy.d.ts","sourceRoot":"","sources":["../../../src/transport/retryPolicy.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAG,MAAe,CAAA;AAE/C;;;;;GAKG;AACH,MAAM,MAAM,mBAAmB,GAC3B,kBAAkB,GAClB,cAAc,GACd,eAAe,GACf,MAAM,CAAA;AAEV;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,QAAQ,CAAA;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,cAAc,EAAE,mBAAmB,CAAA;CACpC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,WAAW;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,mBAAmB,GAAG,SAAS,CAAA;IACzE,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACvE;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,iBAAiB,EAAE,OAAO,CAAA;IAC1B,QAAQ,EAAE,CAAC,GAAG,EAAE,oBAAoB,KAAK,mBAAmB,CAAA;IAC5D,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,mBAAmB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACvE;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,WAAW,GAAG,KAAK,CAAA;IAC7B,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,CAAA;CACvD;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,KAAK,GAAG,mBAAmB,CAAA;AAEnE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,EAAE,mBAejC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,mBAO5B,CAAA;AAyCD;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,mBAAmB,EACzB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,WAAW,EAAE,MAAM,GAClB,mBAAmB,CAkBrB"}

package/dist/types/types/api.d.ts

@@ -0,0 +1,214 @@
+import type { AccountConfigSetting, AccountResponse, ActionStep, ExecuteActionResponse, MarketRef, ModifyOrderInput, OrderSide, OrderType, SignedActionStep, TimeInForce, TriggerOrderInput, WithdrawalParams } from '@lifi/perps-types';
+import type { Account, Address, WalletClient } from 'viem';
+import type { RetryConfig } from '../transport/retryPolicy.js';
+import type { ProviderConfigs, RequestInterceptor } from './config.js';
+import type { PerpsProviderPlugin } from './provider.js';
+/**
+ * Configuration for {@link createPerpsClient}.
+ *
+ * @public
+ */
+export interface PerpsConfig {
+    integrator: string;
+    apiKey: string;
+    apiUrl?: string;
+    disableVersionCheck?: boolean;
+    requestInterceptor?: RequestInterceptor;
+    /**
+     * Provider plugins or per-provider config. Two shapes are accepted:
+     *
+     * - `PerpsProviderPlugin[]` — plugin objects implementing the read surface
+     *   for one DEX each. Bound to the client at construction and looked up at
+     *   runtime as bound {@link PerpsProvider}s via `client.getProvider(key)`.
+     *   Modelled on `@lifi/sdk`'s `providers: SDKProvider[]`.
+     * - `ProviderConfigs` — keyed config object (e.g.
+     *   `{ hyperliquid: { markets: [...] } }`). Used internally by
+     *   `PerpsWsClient` to filter which markets are subscribed to.
+     *
+     * Both may be supplied during the migration to provider packages;
+     * the array form is preferred for new code.
+     */
+    providers?: PerpsProviderPlugin[] | ProviderConfigs;
+    /**
+     * The end-user's wallet, used whenever an action's descriptor names the user
+     * wallet in its `signers` list. Accepts any viem-compatible WalletClient:
+     *   - Browser wallet: wagmi's useWalletClient() result
+     *   - Private key:    createWalletClient({ account: privateKeyToAccount('0x...'), transport: http() })
+     *   - Mnemonic:       createWalletClient({ account: mnemonicToAccount('word1 ...'), transport: http() })
+     */
+    userWallet?: WalletClient<any, any, Account>;
+    /**
+     * Retry behaviour for HTTP requests. Pass `false` to disable retries
+     * everywhere (single-shot — useful when wrapping with TanStack Query or
+     * similar consumer-side retry). Pass a flat {@link RetryPolicy} to apply
+     * one policy across providers, or a per-provider object keyed by provider
+     * type (`'lifi'`, `'hyperliquid'`, `'lighter'`) with an optional `default`
+     * fallback. Per-provider built-in defaults apply when omitted.
+     */
+    retry?: RetryConfig;
+    /**
+     * Replace the global `fetch` used by the SDK and provider HTTP clients —
+     * for instrumentation, custom proxying, or test injection. Does not affect
+     * retry policy.
+     */
+    fetch?: typeof fetch;
+}
+/**
+ * Options for PerpsClient constructor.
+ *
+ * @public
+ */
+export interface PerpsClientOptions {
+    integrator: string;
+    /** API key for authenticated requests (get one at https://portal.li.fi/) */
+    apiKey: string;
+    /** Defaults to DEFAULT_API_URL */
+    apiUrl?: string;
+    /**
+     * Provider plugins or per-provider config. Accepts the same two shapes as
+     * {@link PerpsConfig.providers}: an array of `PerpsProviderPlugin` plugins or
+     * a keyed `ProviderConfigs` map.
+     */
+    providers?: PerpsProviderPlugin[] | ProviderConfigs;
+}
+/**
+ * Parameters for the internal `buildProviderSetup` helper that materialises
+ * typed-data envelopes for the setup descriptors.
+ *
+ * @public
+ */
+export interface BuildProviderSetupParams {
+    provider: string;
+    address: Address;
+}
+/**
+ * Parameters for placing an order.
+ *
+ * @public
+ */
+export interface PlaceOrderParams {
+    provider: string;
+    address: Address;
+    market: MarketRef;
+    side: OrderSide;
+    type: OrderType;
+    size: string;
+    price: string;
+    leverage?: number;
+    reduceOnly?: boolean;
+    timeInForce?: TimeInForce;
+    expiresAt?: string;
+    takeProfit?: TriggerOrderInput;
+    stopLoss?: TriggerOrderInput;
+}
+/**
+ * Parameters for placing trigger-only orders (TP/SL on existing positions).
+ * Sends a TRIGGER_ONLY order that skips the main order wire.
+ *
+ * @public
+ */
+export interface PlaceTriggerOrderParams {
+    provider: string;
+    address: Address;
+    market: MarketRef;
+    side: OrderSide;
+    takeProfit?: TriggerOrderInput;
+    stopLoss?: TriggerOrderInput;
+}
+/**
+ * Parameters for withdrawing funds.
+ *
+ * @public
+ */
+export interface WithdrawParams {
+    provider: string;
+    address: Address;
+    withdrawal: WithdrawalParams;
+}
+/**
+ * Parameters for canceling orders.
+ *
+ * @public
+ */
+export interface CancelOrdersParams {
+    provider: string;
+    address: Address;
+    ids: string[];
+}
+/**
+ * Parameters for modifying orders.
+ *
+ * @public
+ */
+export interface ModifyOrdersParams {
+    provider: string;
+    address: Address;
+    modifications: ModifyOrderInput[];
+}
+/**
+ * Parameters for {@link PerpsClient.checkSetup}.
+ *
+ * @public
+ */
+export interface GetSetupParams {
+    provider: string;
+    address: Address;
+}
+/**
+ * Result from {@link PerpsClient.checkSetup}.
+ *
+ * Reports the unsatisfied entries on `Provider.setup` for the queried account
+ * as a flat list — each `ActionStep` is self-describing (its action keys back
+ * to the provider's `setup` descriptor, which declares the step's signer and
+ * scheme), so no signer-role partition is exposed here.
+ *
+ * `Provider.options` items are NEVER included here — they don't gate trading
+ * and are surfaced separately via `getAccount().settings`.
+ *
+ * @public
+ */
+export interface ProviderSetup {
+    /** Unsatisfied setup steps, ordered by descriptor `sequence`. */
+    setup: ActionStep[];
+    /** Whether all setup items are already satisfied (ready to trade) */
+    isReady: boolean;
+}
+/**
+ * Parameters for {@link PerpsClient.executeProviderSetup}.
+ *
+ * @public
+ */
+export interface ExecuteProviderSetupParams {
+    /** Provider to satisfy setup for */
+    provider: string;
+    /** User wallet address */
+    address: Address;
+    /** The unsatisfied setup steps from checkSetup() */
+    setup: ActionStep[];
+    /** Signed counterparts of `setup`, in the same order */
+    signedActions: SignedActionStep[];
+}
+/**
+ * Result from {@link PerpsClient.executeProviderSetup}.
+ *
+ * @public
+ */
+export interface ExecuteProviderSetupResult {
+    results: ExecuteActionResponse;
+}
+/**
+ * Result envelope returned by {@link PerpsClient.getAccount} — wraps the
+ * backend's `AccountResponse` with a single SDK-projected `settings` array.
+ *
+ * `settings` contains exactly one `AccountConfigSetting` per descriptor on
+ * `Provider.setup` + `Provider.options` (in that order). Index the
+ * projection by `setting.type === descriptor.type` and read
+ * `setting.values[i].value` for each `Param` the descriptor declared.
+ *
+ * @public
+ */
+export interface GetAccountResult extends AccountResponse {
+    /** SDK-projected current state of every setup + options descriptor. */
+    settings: AccountConfigSetting[];
+}
+//# sourceMappingURL=api.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/types/api.ts"],"names":[],"mappings":"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"}

package/dist/types/types/config.d.ts

@@ -0,0 +1,70 @@
+import type { Account, WalletClient } from 'viem';
+import type { RetryConfig } from '../transport/retryPolicy.js';
+/**
+ * Viem `WalletClient` shape used by `PerpsSDKClient.userWallet`. Aliased here
+ * so provider plugins can name the type without re-deriving the viem generics.
+ *
+ * @public
+ */
+export type PerpsClientSigner = WalletClient<any, any, Account>;
+/**
+ * Per-provider config — restricts which `markets` the WS client subscribes
+ * to. Indexed by provider key.
+ *
+ * @public
+ */
+export interface ProviderConfig {
+    markets?: string[];
+}
+/**
+ * @deprecated Use {@link ProviderConfig}.
+ * @public
+ */
+export type HyperliquidConfig = ProviderConfig;
+/**
+ * Map of per-provider {@link ProviderConfig}, keyed by provider key.
+ *
+ * @public
+ */
+export interface ProviderConfigs {
+    [provider: string]: ProviderConfig | undefined;
+}
+/**
+ * Hook to rewrite each outgoing request's URL/`RequestInit` before it is sent.
+ *
+ * @public
+ */
+export type RequestInterceptor = (url: string, options: RequestInit) => RequestInit | Promise<RequestInit>;
+/**
+ * Per-call request options threaded through the service functions.
+ *
+ * @public
+ */
+export interface SDKRequestOptions {
+    signal?: AbortSignal;
+    /**
+     * Lighter auth token consumed by provider-direct venue reads (getOrders,
+     * getOrder, getActivity, getAccount). Create via
+     * `lighterSigner.createAuthToken(deadline, context)`. Sent only to Lighter
+     * venue endpoints, never to the LI.FI backend — read-only by design
+     * (8h max TTL, cannot authorize writes).
+     */
+    lighterAuthToken?: string;
+}
+/**
+ * Immutable snapshot of the resolved client configuration after defaults
+ * are applied. Exposed via {@link PerpsSDKClient.config}.
+ *
+ * @public
+ */
+export interface PerpsBaseConfig {
+    integrator: string;
+    apiKey: string;
+    apiUrl: string;
+    disableVersionCheck?: boolean;
+    requestInterceptor?: RequestInterceptor;
+    providers?: ProviderConfigs;
+    retry?: RetryConfig;
+    fetch?: typeof fetch;
+}
+//# sourceMappingURL=config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,MAAM,CAAA;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,6BAA6B,CAAA;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GAAG,YAAY,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,CAAA;AAE/D;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,cAAc,CAAA;AAE9C;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAAA;CAC/C;AAED;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,KACjB,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;AAEvC;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAC7B,kBAAkB,CAAC,EAAE,kBAAkB,CAAA;IACvC,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,KAAK,CAAC,EAAE,WAAW,CAAA;IACnB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;CACrB"}