@reefclaw/openclaw-plugin 0.1.0

package/live/user-data-stream.d.ts

@@ -0,0 +1,243 @@
+import { EventEmitter } from 'node:events';
+import type { BinancePrivateApi } from '../ccxt/binance-private.js';
+import { ListenKeyManager } from './listen-key-manager.js';
+import type { ListenKeyManagerOptions } from './listen-key-manager.js';
+import type { ParsedAccountUpdate, ParsedOrderUpdate } from './live-state-store.js';
+/** Minimal WebSocket shape we depend on — matches both the `ws` library and
+ *  the browser WebSocket. Tests implement this directly. */
+export interface StreamWebSocket {
+    on(event: 'open', cb: () => void): void;
+    on(event: 'close', cb: (code?: number, reason?: Buffer | string) => void): void;
+    on(event: 'error', cb: (err: Error) => void): void;
+    on(event: 'message', cb: (data: Buffer | string) => void): void;
+    on(event: 'ping', cb: (data: Buffer) => void): void;
+    on(event: 'pong', cb: (data: Buffer) => void): void;
+    /** Close the connection gracefully. Safe to call if already closed. */
+    close(code?: number, reason?: string): void;
+    /** Called to reply to server pings. Most WS clients auto-pong; we expose
+     *  this for tests + for when the client library doesn't. */
+    pong?(data?: Buffer): void;
+    /** Force-terminate (no TCP FIN). Fallback for stuck sockets. */
+    terminate?(): void;
+}
+export type WebSocketFactory = (url: string) => StreamWebSocket;
+export interface StreamTimerDeps {
+    setTimeout: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
+    clearTimeout: (handle: ReturnType<typeof setTimeout>) => void;
+    setInterval: (fn: () => void, ms: number) => ReturnType<typeof setInterval>;
+    clearInterval: (handle: ReturnType<typeof setInterval>) => void;
+    now: () => number;
+    /** Used for jittered backoff. Tests override with a deterministic RNG. */
+    random: () => number;
+}
+export interface UserDataStreamOptions {
+    /** Mainnet: 'wss://fstream.binance.com/private/ws'. Testnet: 'wss://stream.binancefuture.com/ws'.
+     *  The listenKey is appended at connect time. Do NOT include trailing slash. */
+    wsBaseUrl: string;
+    /** Injection — produces a StreamWebSocket given the full URL. */
+    webSocketFactory: WebSocketFactory;
+    /** ListenKeyManager-compat options passed through. */
+    listenKey?: ListenKeyManagerOptions;
+    /** Reconnect backoff base. Default 1000 ms. */
+    reconnectBaseMs?: number;
+    /** Reconnect backoff cap. Default 60000 ms. */
+    reconnectCapMs?: number;
+    /** Fractional jitter applied to each reconnect delay. Default 0.2 (±20%). */
+    reconnectJitterPct?: number;
+    /** Dead-socket watchdog. Compares the configured threshold against the
+     *  most recent INCOMING FRAME of any kind — `message`, `ping`, or `pong`
+     *  (tracked as `lastFrameAt`), NOT just data-bearing message frames. Binance
+     *  documents server pings every 3 min on the user-data stream
+     *  (developers.binance.com → futures websocket-market-streams); counting
+     *  them as liveness signals means a calm account (no fills, stable balance)
+     *  doesn't trip the watchdog.
+     *
+     *  Default 6 min — comfortably above the 180 s ping interval, comfortably
+     *  below Binance's own 10-min no-pong cutoff. The watchdog is the
+     *  "TCP-is-actually-dead" safety net; the active REST probe (60 s tick,
+     *  see UserDataActiveProbe) is the canonical "events stopped arriving"
+     *  detector for missed fills on open positions. */
+    staleEventWatchdogMs?: number;
+    /** Alert thresholds on consecutive reconnect attempts. */
+    warnThreshold?: number;
+    errorThreshold?: number;
+    fatalThreshold?: number;
+    /** Injection — timers + RNG. Defaults to real. */
+    timers?: Partial<StreamTimerDeps>;
+    /** Injection — testability. Tests supply a fake ListenKeyManager. */
+    listenKeyManagerFactory?: (api: BinancePrivateApi, opts: ListenKeyManagerOptions | undefined) => ListenKeyManager;
+    /** Translate Binance raw market IDs (`BTCUSDT`) back to unified CCXT
+     *  symbols (`BTC/USDT`) before emitting. Defaults to `api.symbolFromMarketId`
+     *  which uses CCXT's market cache. Identity function for unit tests that
+     *  don't care about symbol shape. */
+    symbolTranslator?: (marketId: string) => string;
+}
+export type StreamStatus = 'stopped' | 'connecting' | 'open' | 'reconnecting';
+export interface StreamHealth {
+    status: StreamStatus;
+    currentListenKey: string | null;
+    /** Last `message` frame timestamp (data event from Binance). Drives the
+     *  active REST probe's freshness check. Null until first frame after
+     *  (re)connect. */
+    lastEventAt: number | null;
+    /** Last frame of ANY kind — message, ping, or pong. Drives the dead-socket
+     *  watchdog. Distinct from `lastEventAt` because Binance pings every 3 min
+     *  on the user-data stream regardless of account activity, and those pings
+     *  are the only liveness signal an idle account ever gets. */
+    lastFrameAt: number | null;
+    lastConnectedAt: number | null;
+    consecutiveReconnectAttempts: number;
+    totalReconnects: number;
+}
+export type UserDataStreamEvents = {
+    /** WS opened successfully. Parent should run a REST snapshot and seed the store. */
+    connected: () => void;
+    /** WS closed. `willReconnect` is false only for a manual stop(). */
+    disconnected: (reason: string, willReconnect: boolean) => void;
+    /** Emitted every time we're about to attempt a reconnect. Useful for metrics. */
+    reconnecting: (attempt: number, delayMs: number) => void;
+    /** ACCOUNT_UPDATE event — positions + balance deltas. */
+    accountUpdate: (ev: ParsedAccountUpdate) => void;
+    /** ORDER_TRADE_UPDATE event — single order state transition. */
+    orderUpdate: (ev: ParsedOrderUpdate) => void;
+    /** ALGO_UPDATE event — single algo/conditional order state transition
+     *  (STOP_MARKET / TAKE_PROFIT_MARKET / TRAILING_STOP_MARKET). Binance does
+     *  NOT route these through ORDER_TRADE_UPDATE — they have their own event
+     *  type that we previously swallowed at the `default` branch. Downstream
+     *  listeners use this to detect bracket-leg cancellation by the exchange. */
+    algoUpdate: (ev: ParsedAlgoUpdate) => void;
+    /** MARGIN_CALL event — pre-liquidation warning. Advisory. */
+    marginCall: (ev: ParsedMarginCall) => void;
+    /** ACCOUNT_CONFIG_UPDATE event — leverage/margin-mode changes. Operator-visible. */
+    accountConfigUpdate: (ev: ParsedAccountConfigUpdate) => void;
+    /** Server-sent listenKey expiry notice. We re-mint + reconnect automatically. */
+    listenKeyExpired: () => void;
+    /** Forced reconnect due to staleness watchdog (no events for too long). */
+    staleForcedReconnect: (idleMs: number) => void;
+    /** Parent should run a REST snapshot + re-seed the store. Emitted on every
+     *  successful (re)connect AFTER 'connected' — gives a distinct hook for
+     *  resync logic that doesn't also fire on first connect (which uses the
+     *  'connected' hook). */
+    resyncRequired: (cause: 'reconnect' | 'listen_key_rotation') => void;
+};
+export interface ParsedMarginCall {
+    eventTime: number;
+    crossWallet: number;
+    positions: Array<{
+        symbol: string;
+        positionSide: 'LONG' | 'SHORT' | 'BOTH';
+        positionAmt: number;
+        marginType: 'cross' | 'isolated';
+        isolatedWallet: number;
+        markPrice: number;
+        unrealizedPnl: number;
+        maintMargin: number;
+    }>;
+}
+export interface ParsedAccountConfigUpdate {
+    eventTime: number;
+    /** Which section changed. Binance sends either `ac` (leverage) or `ai`
+     *  (account-level multi-asset mode). We surface both under one type. */
+    kind: 'leverage' | 'multi_asset_mode' | 'other';
+    symbol?: string;
+    leverage?: number;
+    multiAssetMode?: boolean;
+}
+/** Parsed ALGO_UPDATE event. Mirrors Binance Futures' conditional-order
+ *  user-data frame for STOP_MARKET / TAKE_PROFIT_MARKET / TRAILING_STOP_MARKET.
+ *  Field shape VERIFIED 2026-05-15 against the authoritative doc
+ *  (developers.binance.com → USD-M Futures → User Data Streams → Event Algo
+ *  Order Update) + a raw prod capture. Binance wraps the algo-order detail
+ *  under the **`o`** key (NOT `ao`/`a` — the original guess was wrong and
+ *  parsed nothing). Status `X` semantics that matter downstream:
+ *  CANCELED = manual cancel (our explicit cancelOrder); EXPIRED = system
+ *  cancel (e.g. position closed → Binance auto-cancels the sibling).
+ *
+ *  The 2026-05-15 ATOM/SOL/LINK bracket-spiral incident traced to this event
+ *  being silently swallowed at the `default` case in `handleFrame`. Listeners
+ *  should still treat `status` defensively (Binance has added new states
+ *  without notice — e.g. 2024's `EXPIRED_IN_MATCH`). The original raw payload is
+ *  preserved under `raw` so post-hoc analysis can recover missing fields. */
+export interface ParsedAlgoUpdate {
+    eventTime: number;
+    transactionTime: number;
+    symbol: string;
+    algoId: string;
+    clientAlgoId: string | null;
+    side: 'buy' | 'sell';
+    /** Binance's documented enum: STOP_MARKET, TAKE_PROFIT_MARKET,
+     *  TRAILING_STOP_MARKET. Forwarded verbatim, uppercased. */
+    orderType: string;
+    /** Binance's documented enum: NEW, WORKING, TRIGGERED, FINISHED,
+     *  CANCELED, EXPIRED, REJECTED. Forwarded verbatim, uppercased. */
+    status: string;
+    triggerPrice: number | null;
+    quantity: number;
+    reduceOnly: boolean;
+    /** Binance's optional `r` field — string reason on terminal states like
+     *  `CANCELED_BY_EXCHANGE`, `MARGIN_CHECK_FAILED`, etc. Undefined when
+     *  Binance doesn't supply one. Useful for diagnosing auto-cancel. */
+    reason?: string;
+    /** Full raw event for first-N debug logging and for fields we don't model
+     *  yet. Don't read this in production code — add a typed accessor instead. */
+    raw: Record<string, unknown>;
+}
+export declare class UserDataStream extends EventEmitter {
+    private readonly api;
+    private readonly opts;
+    private readonly webSocketFactory;
+    private readonly timers;
+    private readonly listenKeyManager;
+    private readonly translateSymbol;
+    private ws;
+    private status;
+    private reconnectTimer;
+    private watchdogInterval;
+    private lastEventAt;
+    private lastFrameAt;
+    private lastConnectedAt;
+    private consecutiveReconnects;
+    private totalReconnects;
+    private stopRequested;
+    private firstConnect;
+    /** First-N raw ALGO_UPDATE payloads logged at INFO so operators can verify
+     *  the parser against real Binance traffic without scraping the WS at
+     *  TRACE. Capped to avoid log volume; resets per process restart. */
+    private algoUpdateRawLogged;
+    private static readonly ALGO_UPDATE_RAW_LOG_CAP;
+    constructor(api: BinancePrivateApi, options: UserDataStreamOptions);
+    /** Start the stream. Idempotent — returns immediately if already running. */
+    start(): Promise<void>;
+    /** Graceful stop. Closes WS + stops listenKey. Idempotent. */
+    stop(): Promise<void>;
+    /** Current health snapshot for observability. */
+    getHealth(): StreamHealth;
+    /** Whether the stream is currently open. Convenience for tests + callers. */
+    isConnected(): boolean;
+    private openConnection;
+    private attachWsHandlers;
+    private handleFrame;
+    private scheduleReconnect;
+    private computeBackoffMs;
+    private clearReconnectTimer;
+    /** Force a reconnect now — used when the server tells us the key expired
+     *  or when the listenKey keep-alive loop gives up.
+     *
+     *  Invariant: the close handler is responsible for clearing `this.ws`,
+     *  stopping the listenKey loop, and scheduling the reconnect. We only
+     *  trigger close() here and let the handler run. If there's no socket to
+     *  close (manager dropped out-of-band), we schedule directly. */
+    private forceReconnect;
+    private startWatchdog;
+    /** External trigger for a reconnect — used by the active REST probe when
+     *  it detects a fill that the WS missed. Same plumbing as the watchdog
+     *  path; the close handler runs the reconnect schedule. */
+    requestReconnect(reason: string): void;
+    private stopWatchdog;
+    private setStatus;
+}
+export declare function parseAccountUpdate(obj: Record<string, unknown>, translateSymbol?: (id: string) => string): ParsedAccountUpdate | null;
+export declare function parseOrderUpdate(obj: Record<string, unknown>, translateSymbol?: (id: string) => string): ParsedOrderUpdate | null;
+export declare function parseMarginCall(obj: Record<string, unknown>, translateSymbol?: (id: string) => string): ParsedMarginCall | null;
+export declare function parseAlgoUpdate(obj: Record<string, unknown>, translateSymbol?: (id: string) => string): ParsedAlgoUpdate | null;
+export declare function parseAccountConfigUpdate(obj: Record<string, unknown>, translateSymbol?: (id: string) => string): ParsedAccountConfigUpdate | null;