@reefclaw/connect 0.1.10 → 0.1.12

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

@@ -1,243 +0,0 @@
-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;