blink-trade-sdk 0.1.0

package/dist/ws.d.ts

@@ -0,0 +1,328 @@
+/**
+ * WebSocket protocol v1 (`/v1/ws`): frames, per-channel continuity, the
+ * client, and local state appliers. See `docs/v1/websocket.md`.
+ *
+ * The client subscribes by channel string; every server push is an `update`
+ * frame whose data fields are merged into the frame; stateful channels carry
+ * `previous_sequence` / `sequence`. `WsSession` is the transport-free state
+ * machine that tracks continuity per channel and turns a sequence gap or a
+ * server-closed subscription into a "resubscribe required" signal;
+ * `WsClient` drives it over a socket.
+ */
+import type { AccountCatalog, AccountCatalogEntry, AccountSnapshot, Balance, Bbo, BookLevels, Candle, CollectionOperation, Delegation, Fill, FundingPayment, FundingRate, Leverage, MarkCandle, Market, MarketStats, MarketType, Order, Position, PriceLevel, Resolution, Subaccount, WsTrade } from './types.js';
+export { WS_PROTOCOL_VERSION } from './ws-transport.js';
+export interface HelloFrame {
+    type: 'hello';
+    protocol_version: number;
+    /** The server closes a connection that sends nothing for this long. */
+    keepalive_timeout_ms: number;
+}
+export interface PongFrame {
+    type: 'pong';
+    timestamp_ns: string;
+}
+export interface UnsubscribedFrame {
+    type: 'unsubscribed';
+    channel: string;
+    timestamp_ns: string;
+}
+/** `400` invalid command or channel, `404` not found, `409` already subscribed, `503` stream unavailable. */
+export type WsErrorCode = 400 | 404 | 409 | 503;
+export interface ErrorFrame {
+    type: 'error';
+    /** Set when the error concerns one subscription (a rejected subscribe, or a stream the server closed). */
+    channel?: string;
+    code: WsErrorCode | number;
+    message: string;
+    timestamp_ns: string;
+}
+/**
+ * An `update` frame as received. Data fields are merged into the frame;
+ * `classifyUpdate` narrows them by channel. `previous_sequence` is `null` on
+ * the first frame after subscribing (a snapshot) and absent on channels
+ * without sequences (`bbo`, candles), whose every frame is complete.
+ */
+export interface UpdateFrame {
+    type: 'update';
+    channel: string;
+    timestamp_ns: string;
+    previous_sequence?: string | null;
+    sequence?: string | null;
+    [field: string]: unknown;
+}
+export type WsMessage = HelloFrame | PongFrame | UpdateFrame | UnsubscribedFrame | ErrorFrame;
+interface Envelope {
+    type: 'update';
+    channel: string;
+    timestamp_ns: string;
+}
+interface SequencedEnvelope extends Envelope {
+    previous_sequence: string | null;
+    sequence: string | null;
+}
+export interface MarketsUpdateFrame extends SequencedEnvelope {
+    markets: Market[];
+}
+export interface MarketStatsUpdateFrame extends SequencedEnvelope {
+    market_stats: MarketStats[];
+}
+export interface BboUpdateFrame extends Envelope {
+    bbo: Bbo;
+}
+export interface OrderbookUpdateFrame extends SequencedEnvelope {
+    orderbook: BookLevels;
+}
+export interface TradesUpdateFrame extends SequencedEnvelope {
+    trades: WsTrade[];
+}
+export interface CandlesUpdateFrame extends Envelope {
+    candles: Candle[];
+}
+export interface MarkCandlesUpdateFrame extends Envelope {
+    candles: MarkCandle[];
+}
+export interface FundingRatesUpdateFrame extends SequencedEnvelope {
+    funding_rates: FundingRate[];
+}
+export interface AccountsSnapshotFrame extends SequencedEnvelope, AccountCatalog {
+    previous_sequence: null;
+}
+export interface AccountsDeltaFrame extends SequencedEnvelope {
+    operations: CollectionOperation[];
+}
+export interface AccountSnapshotFrame extends SequencedEnvelope, AccountSnapshot {
+    previous_sequence: null;
+}
+export interface AccountDeltaFrame extends SequencedEnvelope {
+    operations: CollectionOperation[];
+}
+/** An update narrowed by its channel. */
+export type ChannelUpdate = {
+    kind: 'markets';
+    frame: MarketsUpdateFrame;
+} | {
+    kind: 'market-stats';
+    frame: MarketStatsUpdateFrame;
+} | {
+    kind: 'bbo';
+    frame: BboUpdateFrame;
+} | {
+    kind: 'orderbook';
+    frame: OrderbookUpdateFrame;
+} | {
+    kind: 'trades';
+    frame: TradesUpdateFrame;
+} | {
+    kind: 'candles';
+    frame: CandlesUpdateFrame;
+} | {
+    kind: 'mark-candles';
+    frame: MarkCandlesUpdateFrame;
+} | {
+    kind: 'funding-rates';
+    frame: FundingRatesUpdateFrame;
+} | {
+    kind: 'accounts';
+    frame: AccountsSnapshotFrame | AccountsDeltaFrame;
+} | {
+    kind: 'account';
+    frame: AccountSnapshotFrame | AccountDeltaFrame;
+} | {
+    kind: 'unknown';
+    frame: UpdateFrame;
+};
+/** `true` when the frame replaces local state: the first frame after subscribing, or any frame on a channel without sequences. */
+export declare function isSnapshot(frame: {
+    previous_sequence?: string | null;
+}): boolean;
+/** Narrow an account-channel frame: the snapshot carries the collections, later frames carry `operations`. */
+export declare function isAccountSnapshot(frame: AccountSnapshotFrame | AccountDeltaFrame): frame is AccountSnapshotFrame;
+export declare function isAccountsSnapshot(frame: AccountsSnapshotFrame | AccountsDeltaFrame): frame is AccountsSnapshotFrame;
+/** Narrow an `update` frame by its channel name. */
+export declare function classifyUpdate(frame: UpdateFrame): ChannelUpdate;
+export type ParsedChannel = {
+    kind: 'markets';
+} | {
+    kind: 'market-stats';
+    marketType: MarketType;
+    marketId?: number;
+} | {
+    kind: 'bbo';
+    marketType: MarketType;
+    marketId: number;
+} | {
+    kind: 'orderbook';
+    marketType: MarketType;
+    marketId: number;
+} | {
+    kind: 'trades';
+    marketType: MarketType;
+    marketId: number;
+} | {
+    kind: 'candles';
+    marketType: MarketType;
+    marketId: number;
+    resolution: string;
+} | {
+    kind: 'mark-candles';
+    marketId: number;
+    resolution: string;
+} | {
+    kind: 'funding-rates';
+    marketId: number;
+} | {
+    kind: 'accounts';
+    address: string;
+} | {
+    kind: 'account';
+    address: string;
+    subaccountId: number;
+};
+/** Channel-name builders. */
+export declare const channels: {
+    markets: () => string;
+    marketStats: (marketType: MarketType, marketId?: number) => string;
+    bbo: (marketType: MarketType, marketId: number) => string;
+    orderbook: (marketType: MarketType, marketId: number) => string;
+    trades: (marketType: MarketType, marketId: number) => string;
+    candles: (marketType: MarketType, marketId: number, resolution: Resolution) => string;
+    markCandles: (marketId: number, resolution: Resolution) => string;
+    fundingRates: (marketId: number) => string;
+    accounts: (address: string) => string;
+    account: (address: string, subaccountId: number) => string;
+};
+/** Parse a channel name; `undefined` for names this SDK does not know. */
+export declare function parseChannel(channel: string): ParsedChannel | undefined;
+export type ResubscribeReason = 
+/** An update's `previous_sequence` did not match the last installed `sequence`; the frame was dropped. */
+{
+    kind: 'sequence_gap';
+    expected: string | null;
+    previous_sequence: string | null;
+    sequence: string | null;
+}
+/** The server closed the subscription (an `error` frame naming the channel, e.g. `503 stream unavailable`). */
+ | {
+    kind: 'subscription_closed';
+    code: number;
+    message: string;
+};
+/** Local state for `channel` is stale: discard it and subscribe again (`WsClient.resubscribe`). */
+export interface ResubscribeRequired {
+    channel: string;
+    reason: ResubscribeReason;
+}
+export type SessionEvent = {
+    type: 'message';
+    message: WsMessage;
+} | {
+    type: 'resubscribe_required';
+    channel: string;
+    reason: ResubscribeReason;
+};
+/**
+ * Transport-free protocol state: subscribed channels, the last installed
+ * sequence per channel, and continuity checks. Feed it every server frame
+ * with `ingest`.
+ */
+export declare class WsSession {
+    private readonly state;
+    /** Record a `subscribe` command. */
+    subscribe(channel: string): void;
+    /** Record an `unsubscribe` command; the channel stays tracked until the server's `unsubscribed` frame. */
+    unsubscribe(channel: string): void;
+    /** Channels currently subscribed. */
+    channels(): string[];
+    /** Last installed sequence; `undefined` when nothing is installed, `null` when the channel has no sequence yet. */
+    lastSequence(channel: string): string | null | undefined;
+    isInstalled(channel: string): boolean;
+    /** Decode one server frame and update continuity. */
+    ingest(message: WsMessage): SessionEvent;
+}
+export interface WsClientOptions {
+    /** Every server frame: `hello`, `pong`, `update`, `unsubscribed`, `error`. Updates that fail the continuity check are not delivered. */
+    onMessage: (message: WsMessage) => void;
+    /** A channel's local state is stale; call `resubscribe(channel)` and reinstall the snapshot that follows. */
+    onResubscribeRequired?: (signal: ResubscribeRequired) => void;
+    onClose?: (event: CloseEvent) => void;
+    onError?: (error: unknown) => void;
+    /**
+     * Ping period; defaults to half the server's `keepalive_timeout_ms`.
+     * Uses transport pings when available and protocol-v1 JSON pings in browsers.
+     */
+    keepaliveIntervalMs?: number;
+    /** WebSocket implementation; defaults to `globalThis.WebSocket`. */
+    WebSocket?: typeof WebSocket;
+}
+export declare class WsClient {
+    private readonly transport;
+    private readonly session;
+    constructor(url: string, options: WsClientOptions);
+    /** Resolves with the server's `hello` once the connection is usable. */
+    ready(): Promise<HelloFrame>;
+    hello(): HelloFrame | undefined;
+    /** Channels currently subscribed. */
+    channels(): string[];
+    /** Last installed sequence for a channel (see `WsSession.lastSequence`). */
+    lastSequence(channel: string): string | null | undefined;
+    isInstalled(channel: string): boolean;
+    /** Subscribe to a channel (`channels.orderbook('perp', 1)`); the first `update` is the snapshot. A duplicate subscribe yields a `409` error frame. */
+    subscribe(channel: string): Promise<void>;
+    /** Unsubscribe; the server acknowledges with an `unsubscribed` frame. */
+    unsubscribe(channel: string): Promise<void>;
+    /** Recover from `onResubscribeRequired`: unsubscribe (a no-op if the server already closed the channel) and subscribe again. */
+    resubscribe(channel: string): Promise<void>;
+    close(): void;
+}
+/** A price-level order book built from `orderbook/...` updates. */
+export declare class LocalBook {
+    private readonly bidLevels;
+    private readonly askLevels;
+    sequence: string | null;
+    /** Apply an update: a snapshot replaces the book, a delta sets absolute sizes (size `0` removes the level). */
+    apply(frame: OrderbookUpdateFrame): void;
+    applyLevels(snapshot: boolean, levels: BookLevels): void;
+    /** Bids, best (highest price) first. */
+    bids(): PriceLevel[];
+    /** Asks, best (lowest price) first. */
+    asks(): PriceLevel[];
+    bestBid(): PriceLevel | undefined;
+    bestAsk(): PriceLevel | undefined;
+    isEmpty(): boolean;
+}
+/**
+ * Apply one operation to a generic collection. Append-only collections are
+ * kept newest first (like the snapshot): an `insert` goes to the front, and a
+ * row whose key is already present (a replayed transaction) is dropped.
+ */
+export declare function applyOperation<T extends Record<string, unknown>>(rows: T[], operation: CollectionOperation): T[];
+/**
+ * Typed state of one subaccount, maintained from the
+ * `account/{address}/{subaccount_id}` channel: the snapshot fills every
+ * collection, later frames carry `operations` applied in order with each
+ * collection's documented key. `fills` and `funding_payments` are kept newest
+ * first and grow with every insert; `truncateHistory` bounds them. Operations
+ * on unknown collections are ignored.
+ */
+export declare class AccountState {
+    account?: Subaccount;
+    delegations: Delegation[];
+    balances: Balance[];
+    positions: Position[];
+    leverages: Leverage[];
+    orders: Order[];
+    fills: Fill[];
+    funding_payments: FundingPayment[];
+    apply(frame: AccountSnapshotFrame | AccountDeltaFrame): void;
+    install(snapshot: AccountSnapshot): void;
+    applyOperation(operation: CollectionOperation): void;
+    /** Keep only the `maxRows` most recent `fills` and `funding_payments`. */
+    truncateHistory(maxRows: number): void;
+}
+/** The `accounts/{address}` catalog, maintained from its snapshot and `reset` operations. */
+export declare class AccountCatalogState {
+    subaccounts: AccountCatalogEntry[];
+    delegations: Delegation[];
+    apply(frame: AccountsSnapshotFrame | AccountsDeltaFrame): void;
+    applyOperation(operation: CollectionOperation): void;
+}