@reefclaw/connect 0.1.11 → 0.1.12

package/assets/plugin/live/user-data-stream.js

@@ -1,704 +0,0 @@
-// UserDataStream — the authenticated Binance Futures user-data WebSocket.
-//
-// What it does:
-//   1. Mints a listenKey (via ListenKeyManager) and opens a WebSocket to
-//      `wss://fstream.binance.com/private/ws/<listenKey>` (testnet: `stream.binancefuture.com`).
-//   2. Parses incoming frames into typed events (ACCOUNT_UPDATE,
-//      ORDER_TRADE_UPDATE, ALGO_UPDATE, MARGIN_CALL, ACCOUNT_CONFIG_UPDATE,
-//      listenKeyExpired).
-//   3. Emits those events for the parent (typically LiveStateStore +
-//      LiveAdapter) to apply.
-//   4. Handles reconnects with exponential backoff + jitter, staleness
-//      watchdog, graduated alert thresholds, and listenKey rotation.
-//
-// What it does NOT do:
-//   - No state management. The store (`LiveStateStore`) applies events.
-//   - No REST snapshot logic. The parent calls its own REST on
-//     `'reconnect'` / `'connected'` so the store can re-seed.
-//   - No 60s reconciler. That lives separately (see PositionReconciler).
-//
-// Testability:
-//   - `webSocketFactory` is injectable → tests use a mock WebSocket.
-//   - `timers` is injectable → fake-timer tests drive backoff + watchdog.
-//   - `listenKeyManager` is injectable → tests don't hit the network.
-//
-// Rule of thumb: this class is a thin, well-logged translator from Binance
-// framing to our domain events. All business logic belongs upstream.
-import { EventEmitter } from 'node:events';
-import { ListenKeyManager } from './listen-key-manager.js';
-import { logger, formatError } from '../logger.js';
-const TAG = 'user-data-stream';
-const REAL_TIMERS = {
-    setTimeout: (fn, ms) => setTimeout(fn, ms),
-    clearTimeout: (h) => clearTimeout(h),
-    setInterval: (fn, ms) => setInterval(fn, ms),
-    clearInterval: (h) => clearInterval(h),
-    now: () => Date.now(),
-    random: () => Math.random(),
-};
-// ---- The class ----
-export class UserDataStream extends EventEmitter {
-    api;
-    opts;
-    webSocketFactory;
-    timers;
-    listenKeyManager;
-    translateSymbol;
-    ws = null;
-    status = 'stopped';
-    reconnectTimer = null;
-    watchdogInterval = null;
-    lastEventAt = null;
-    lastFrameAt = null;
-    lastConnectedAt = null;
-    consecutiveReconnects = 0;
-    totalReconnects = 0;
-    stopRequested = false;
-    firstConnect = true;
-    /** 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. */
-    algoUpdateRawLogged = 0;
-    static ALGO_UPDATE_RAW_LOG_CAP = 20;
-    constructor(api, options) {
-        super();
-        this.api = api;
-        this.opts = {
-            wsBaseUrl: options.wsBaseUrl,
-            reconnectBaseMs: options.reconnectBaseMs ?? 1_000,
-            reconnectCapMs: options.reconnectCapMs ?? 60_000,
-            reconnectJitterPct: options.reconnectJitterPct ?? 0.2,
-            staleEventWatchdogMs: options.staleEventWatchdogMs ?? 6 * 60_000,
-            warnThreshold: options.warnThreshold ?? 3,
-            errorThreshold: options.errorThreshold ?? 10,
-            fatalThreshold: options.fatalThreshold ?? 30,
-        };
-        this.webSocketFactory = options.webSocketFactory;
-        this.timers = {
-            setTimeout: options.timers?.setTimeout ?? REAL_TIMERS.setTimeout,
-            clearTimeout: options.timers?.clearTimeout ?? REAL_TIMERS.clearTimeout,
-            setInterval: options.timers?.setInterval ?? REAL_TIMERS.setInterval,
-            clearInterval: options.timers?.clearInterval ?? REAL_TIMERS.clearInterval,
-            now: options.timers?.now ?? REAL_TIMERS.now,
-            random: options.timers?.random ?? REAL_TIMERS.random,
-        };
-        const makeListenKeyMgr = options.listenKeyManagerFactory
-            ?? ((a, o) => new ListenKeyManager(a, o));
-        this.listenKeyManager = makeListenKeyMgr(api, options.listenKey);
-        this.translateSymbol = options.symbolTranslator
-            ?? ((id) => api.symbolFromMarketId(id));
-        this.listenKeyManager.on('keyKeepAliveFailed', (reason) => {
-            logger.warn(TAG, `listenKey keep-alive failed — forcing reconnect: ${reason}`);
-            // Forcing a reconnect will re-mint a fresh key as part of start().
-            this.forceReconnect('listen_key_keepalive_failed');
-        });
-    }
-    /** Start the stream. Idempotent — returns immediately if already running. */
-    async start() {
-        if (this.status !== 'stopped') {
-            logger.warn(TAG, `start() called while status=${this.status} — ignored`);
-            return;
-        }
-        this.stopRequested = false;
-        this.consecutiveReconnects = 0;
-        this.firstConnect = true;
-        await this.openConnection();
-        this.startWatchdog();
-    }
-    /** Graceful stop. Closes WS + stops listenKey. Idempotent. */
-    async stop() {
-        this.stopRequested = true;
-        this.clearReconnectTimer();
-        this.stopWatchdog();
-        if (this.ws) {
-            try {
-                this.ws.close(1000, 'client shutdown');
-            }
-            catch { /* best-effort */ }
-            this.ws = null;
-        }
-        try {
-            await this.listenKeyManager.stop();
-        }
-        catch (err) {
-            logger.warn(TAG, `listenKey stop failed (non-fatal): ${formatError(err)}`);
-        }
-        this.setStatus('stopped');
-    }
-    /** Current health snapshot for observability. */
-    getHealth() {
-        return {
-            status: this.status,
-            currentListenKey: this.listenKeyManager.getKey(),
-            lastEventAt: this.lastEventAt,
-            lastFrameAt: this.lastFrameAt,
-            lastConnectedAt: this.lastConnectedAt,
-            consecutiveReconnectAttempts: this.consecutiveReconnects,
-            totalReconnects: this.totalReconnects,
-        };
-    }
-    /** Whether the stream is currently open. Convenience for tests + callers. */
-    isConnected() {
-        return this.status === 'open';
-    }
-    // ---- Internal: connection lifecycle ----
-    async openConnection() {
-        if (this.stopRequested)
-            return;
-        this.setStatus('connecting');
-        let key;
-        try {
-            key = await this.listenKeyManager.start();
-        }
-        catch (err) {
-            logger.error(TAG, `listenKey mint failed: ${formatError(err)}`);
-            this.scheduleReconnect('listen_key_mint_failed');
-            return;
-        }
-        const url = `${this.opts.wsBaseUrl}/${key}`;
-        logger.info(TAG, `Opening WS to ${this.opts.wsBaseUrl}/<listenKey> (hash=${hash8(key)})`);
-        let socket;
-        try {
-            socket = this.webSocketFactory(url);
-        }
-        catch (err) {
-            logger.error(TAG, `webSocketFactory threw: ${formatError(err)}`);
-            this.scheduleReconnect('ws_factory_failed');
-            return;
-        }
-        this.ws = socket;
-        this.attachWsHandlers(socket);
-    }
-    attachWsHandlers(socket) {
-        socket.on('open', () => {
-            if (this.ws !== socket)
-                return; // stale
-            this.lastConnectedAt = this.timers.now();
-            this.lastEventAt = this.lastConnectedAt;
-            this.lastFrameAt = this.lastConnectedAt;
-            this.consecutiveReconnects = 0;
-            this.setStatus('open');
-            logger.info(TAG, 'WS connected');
-            this.emit('connected');
-            if (!this.firstConnect) {
-                this.emit('resyncRequired', 'reconnect');
-            }
-            this.firstConnect = false;
-        });
-        socket.on('message', (data) => {
-            if (this.ws !== socket)
-                return;
-            const now = this.timers.now();
-            this.lastEventAt = now; // data event — drives the active probe's freshness check
-            this.lastFrameAt = now; // any frame — drives the dead-socket watchdog
-            this.handleFrame(data);
-        });
-        socket.on('ping', (payload) => {
-            if (this.ws !== socket)
-                return;
-            // Server ping = liveness signal even on a fully-idle account. Binance
-            // documents these every 3 min on the user-data stream, so counting them
-            // toward `lastFrameAt` keeps the watchdog quiet between data frames.
-            // Note: `lastEventAt` is intentionally NOT updated — pings carry no data
-            // so the active REST probe still sees them as silence (correct, the probe
-            // is checking for missed FILLS not missed liveness).
-            this.lastFrameAt = this.timers.now();
-            // Most `ws` clients pong automatically; in case a custom factory doesn't,
-            // reply here. Binance closes the socket if no pong arrives within 10 min.
-            try {
-                socket.pong?.(payload);
-            }
-            catch { /* best-effort */ }
-        });
-        socket.on('pong', () => {
-            if (this.ws !== socket)
-                return;
-            // Server-sent pong (in response to a client-initiated ping if any). Same
-            // liveness role as `ping` above. Kept for observability symmetry.
-            this.lastFrameAt = this.timers.now();
-        });
-        socket.on('error', (err) => {
-            if (this.ws !== socket)
-                return;
-            logger.warn(TAG, `WS error: ${formatError(err)}`);
-            // 'close' will follow. Don't schedule reconnect here to avoid double-firing.
-        });
-        socket.on('close', (code, reason) => {
-            if (this.ws !== socket)
-                return;
-            let reasonStr;
-            if (reason == null)
-                reasonStr = '';
-            else if (typeof reason === 'string')
-                reasonStr = reason;
-            else
-                reasonStr = reason.toString('utf-8');
-            logger.warn(TAG, `WS closed code=${code ?? '?'} reason=${reasonStr || '(none)'}`);
-            this.ws = null;
-            // Stop the keep-alive loop WITHOUT DELETEing the key; the next connect
-            // re-POSTs. Binance's re-POST returns the SAME active key (doc-verified),
-            // so the previous un-awaited DELETE here could land AFTER the reconnect's
-            // POST and invalidate the key the fresh socket just authenticated with.
-            // The graceful path (stop() below / UserDataStream.stop()) still DELETEs —
-            // no reconnect follows there.
-            this.listenKeyManager.stopKeepAlive();
-            if (this.stopRequested) {
-                this.setStatus('stopped');
-                this.emit('disconnected', reasonStr || 'client stop', false);
-                return;
-            }
-            this.emit('disconnected', reasonStr || `code=${code ?? '?'}`, true);
-            this.scheduleReconnect(reasonStr || 'ws_close');
-        });
-    }
-    handleFrame(raw) {
-        let parsed;
-        try {
-            const text = typeof raw === 'string' ? raw : raw.toString('utf-8');
-            parsed = JSON.parse(text);
-        }
-        catch (err) {
-            logger.warn(TAG, `frame parse failed (ignored): ${formatError(err)}`);
-            return;
-        }
-        if (!parsed || typeof parsed !== 'object')
-            return;
-        const obj = parsed;
-        const eventType = typeof obj.e === 'string' ? obj.e : null;
-        if (!eventType) {
-            // Binance occasionally sends pong-like keepalive frames w/o 'e'. Swallow.
-            return;
-        }
-        try {
-            switch (eventType) {
-                case 'ACCOUNT_UPDATE': {
-                    const ev = parseAccountUpdate(obj, this.translateSymbol);
-                    if (ev)
-                        this.emit('accountUpdate', ev);
-                    break;
-                }
-                case 'ORDER_TRADE_UPDATE': {
-                    const ev = parseOrderUpdate(obj, this.translateSymbol);
-                    if (ev)
-                        this.emit('orderUpdate', ev);
-                    break;
-                }
-                case 'ALGO_UPDATE': {
-                    // Binance fires this for STOP_MARKET / TAKE_PROFIT_MARKET /
-                    // TRAILING_STOP_MARKET conditional orders. Pre-2026-05-15 we
-                    // swallowed this at the default branch — that left the plugin
-                    // blind to exchange-side bracket cancellation, which is the
-                    // root cause of the bracket-spiral class of bug. We now parse +
-                    // emit; the downstream listener (controller + LiveAdapter) is
-                    // responsible for the action.
-                    const ev = parseAlgoUpdate(obj, this.translateSymbol);
-                    if (ev) {
-                        if (this.algoUpdateRawLogged < UserDataStream.ALGO_UPDATE_RAW_LOG_CAP) {
-                            // Capped to avoid flooding the journal under heavy bracket
-                            // traffic. Operators read these first-N samples once after
-                            // deploy to verify the parser matches Binance's actual shape.
-                            logger.info(TAG, `ALGO_UPDATE raw (${this.algoUpdateRawLogged + 1}/` +
-                                `${UserDataStream.ALGO_UPDATE_RAW_LOG_CAP}): ${JSON.stringify(obj)}`);
-                            this.algoUpdateRawLogged++;
-                        }
-                        this.emit('algoUpdate', ev);
-                    }
-                    break;
-                }
-                case 'TRADE_LITE': {
-                    // Binance's newer lightweight fill notification (late-2024 addition).
-                    // Same information as ORDER_TRADE_UPDATE but sent earlier for lower
-                    // fill-latency. ORDER_TRADE_UPDATE follows with the canonical state
-                    // transition, so we deliberately don't double-apply — TRADE_LITE is
-                    // informational here. Log at debug-ish level (info) so operators
-                    // can confirm Binance is sending it.
-                    logger.info(TAG, 'TRADE_LITE received (canonical state follows in ORDER_TRADE_UPDATE)');
-                    break;
-                }
-                case 'MARGIN_CALL': {
-                    const ev = parseMarginCall(obj, this.translateSymbol);
-                    if (ev)
-                        this.emit('marginCall', ev);
-                    break;
-                }
-                case 'ACCOUNT_CONFIG_UPDATE': {
-                    const ev = parseAccountConfigUpdate(obj, this.translateSymbol);
-                    if (ev)
-                        this.emit('accountConfigUpdate', ev);
-                    break;
-                }
-                case 'listenKeyExpired': {
-                    logger.warn(TAG, 'listenKey expired notice from Binance — forcing reconnect');
-                    this.emit('listenKeyExpired');
-                    this.forceReconnect('listen_key_expired');
-                    break;
-                }
-                default:
-                    // Unknown event type. Binance adds new types over time; swallow at
-                    // WARN so we notice but don't crash.
-                    logger.warn(TAG, `unknown event type=${eventType} — swallowed`);
-            }
-        }
-        catch (err) {
-            logger.warn(TAG, `event handler for ${eventType} threw: ${formatError(err)}`);
-        }
-    }
-    // ---- Internal: reconnect + watchdog ----
-    scheduleReconnect(reason) {
-        this.clearReconnectTimer();
-        if (this.stopRequested)
-            return;
-        this.consecutiveReconnects += 1;
-        this.totalReconnects += 1;
-        // Graduated alerts — easier to tune alerting later.
-        if (this.consecutiveReconnects >= this.opts.fatalThreshold) {
-            logger.error(TAG, `RECONNECT-FATAL attempt=${this.consecutiveReconnects} reason=${reason}`);
-        }
-        else if (this.consecutiveReconnects >= this.opts.errorThreshold) {
-            logger.error(TAG, `RECONNECT-ERROR attempt=${this.consecutiveReconnects} reason=${reason}`);
-        }
-        else if (this.consecutiveReconnects >= this.opts.warnThreshold) {
-            logger.warn(TAG, `RECONNECT-WARN attempt=${this.consecutiveReconnects} reason=${reason}`);
-        }
-        const delay = this.computeBackoffMs(this.consecutiveReconnects);
-        logger.info(TAG, `reconnect attempt=${this.consecutiveReconnects} delayMs=${delay} reason=${reason}`);
-        this.setStatus('reconnecting');
-        this.emit('reconnecting', this.consecutiveReconnects, delay);
-        this.reconnectTimer = this.timers.setTimeout(() => {
-            this.reconnectTimer = null;
-            void this.openConnection();
-        }, delay);
-    }
-    computeBackoffMs(attempt) {
-        // Exponential: base * 2^(attempt-1). Capped. Then ± jitterPct.
-        const exp = this.opts.reconnectBaseMs * 2 ** Math.min(attempt - 1, 20);
-        const capped = Math.min(exp, this.opts.reconnectCapMs);
-        const jitterRange = capped * this.opts.reconnectJitterPct;
-        const jitter = (this.timers.random() * 2 - 1) * jitterRange;
-        return Math.max(0, Math.round(capped + jitter));
-    }
-    clearReconnectTimer() {
-        if (this.reconnectTimer) {
-            this.timers.clearTimeout(this.reconnectTimer);
-            this.reconnectTimer = null;
-        }
-    }
-    /** 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. */
-    forceReconnect(reason) {
-        if (this.stopRequested)
-            return;
-        if (this.ws) {
-            // The socket is PRESUMED DEAD here (staleness watchdog fired, listenKey
-            // expired, keep-alive gave up, or the active REST probe asked for a
-            // resync). Prefer terminate() over close(): `ws.close(4001)` starts a
-            // closing HANDSHAKE and the `ws` library waits up to ~30s for the
-            // server's reciprocal close frame before it emits 'close' — on a truly
-            // dead TCP path that stalls the whole reconnect for the timeout.
-            // terminate() drops the socket immediately (emits 'close' with code
-            // 1006), so the reconnect fires right away. Same reasoning as the
-            // intel-side routed-WS watchdog (binance-routed-ws.ts:
-            // `ws.terminate()`). Fall back to close() when the socket doesn't
-            // expose terminate() (a browser/test socket without it).
-            const sock = this.ws;
-            try {
-                if (typeof sock.terminate === 'function')
-                    sock.terminate();
-                else
-                    sock.close(4001, reason);
-            }
-            catch { /* best-effort — the 'close' handler still runs cleanup once */ }
-            // Do NOT null this.ws here — the close handler needs it to pass the
-            // `ws === socket` identity check and run cleanup exactly once.
-            return;
-        }
-        // No socket in hand — schedule reconnect directly.
-        if (this.status !== 'reconnecting') {
-            this.scheduleReconnect(reason);
-        }
-    }
-    startWatchdog() {
-        // Fire the check every 30s — a 6-min threshold doesn't need finer
-        // resolution, and a less chatty interval cuts log noise during the steady
-        // state where the watchdog should never fire.
-        this.stopWatchdog();
-        this.watchdogInterval = this.timers.setInterval(() => {
-            if (this.status !== 'open' || this.stopRequested)
-                return;
-            const now = this.timers.now();
-            // Compare against `lastFrameAt` — the most recent INCOMING FRAME of any
-            // kind, including server pings (every 3 min on the Binance user-data
-            // stream). The earlier design compared against `lastEventAt` (message
-            // frames only) and false-fired ~200×/day on idle accounts because
-            // Binance pushes no message frames between events on a quiet position.
-            const last = this.lastFrameAt ?? this.lastConnectedAt ?? now;
-            const idle = now - last;
-            if (idle > this.opts.staleEventWatchdogMs) {
-                logger.warn(TAG, `staleness watchdog fired: idleMs=${idle} > ${this.opts.staleEventWatchdogMs} (no frames — likely dead socket)`);
-                this.emit('staleForcedReconnect', idle);
-                this.forceReconnect('stale_event_watchdog');
-            }
-        }, 30_000);
-    }
-    /** 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) {
-        this.forceReconnect(reason);
-    }
-    stopWatchdog() {
-        if (this.watchdogInterval) {
-            this.timers.clearInterval(this.watchdogInterval);
-            this.watchdogInterval = null;
-        }
-    }
-    setStatus(next) {
-        this.status = next;
-    }
-}
-// ---- Frame parsers ----
-function num(v) {
-    if (typeof v === 'number' && Number.isFinite(v))
-        return v;
-    if (typeof v === 'string') {
-        const n = Number(v);
-        if (Number.isFinite(n))
-            return n;
-    }
-    return 0;
-}
-function str(v) {
-    return typeof v === 'string' ? v : String(v ?? '');
-}
-function optStr(v) {
-    if (v == null)
-        return undefined;
-    return typeof v === 'string' ? v : String(v);
-}
-const IDENTITY = (s) => s;
-export function parseAccountUpdate(obj, translateSymbol = IDENTITY) {
-    const a = obj.a;
-    if (!a)
-        return null;
-    const positionsRaw = Array.isArray(a.P) ? a.P : [];
-    const balancesRaw = Array.isArray(a.B) ? a.B : [];
-    const positions = positionsRaw.map((p) => {
-        const qtySigned = num(p.pa);
-        const positionSide = str(p.ps);
-        // In one-way mode, side is derived from the sign of pa.
-        // In hedge mode, ps is LONG or SHORT directly.
-        let side;
-        if (positionSide === 'LONG')
-            side = qtySigned > 0 ? 'long' : 'flat';
-        else if (positionSide === 'SHORT')
-            side = qtySigned < 0 ? 'short' : 'flat';
-        else {
-            if (qtySigned > 0)
-                side = 'long';
-            else if (qtySigned < 0)
-                side = 'short';
-            else
-                side = 'flat';
-        }
-        const mtRaw = str(p.mt).toLowerCase();
-        const marginType = mtRaw === 'isolated' ? 'isolated' : 'cross';
-        return {
-            symbol: translateSymbol(str(p.s)),
-            side,
-            quantity: Math.abs(qtySigned),
-            entryPrice: num(p.ep),
-            unrealizedPnl: num(p.up),
-            marginType,
-            positionSide,
-        };
-    });
-    const balances = balancesRaw.map((b) => ({
-        asset: str(b.a),
-        walletBalance: num(b.wb),
-        crossWallet: num(b.cw),
-        balanceChange: num(b.bc),
-    }));
-    return {
-        eventTime: num(obj.E),
-        transactionTime: num(obj.T),
-        reason: str(a.m),
-        positions,
-        balances,
-    };
-}
-export function parseOrderUpdate(obj, translateSymbol = IDENTITY) {
-    const o = obj.o;
-    if (!o)
-        return null;
-    const orderStatus = str(o.X);
-    let status;
-    switch (orderStatus) {
-        case 'NEW':
-        case 'PARTIALLY_FILLED':
-            status = 'open';
-            break;
-        case 'FILLED':
-            status = 'closed';
-            break;
-        case 'CANCELED':
-        case 'EXPIRED':
-        case 'REJECTED':
-        case 'EXPIRED_IN_MATCH':
-            status = 'canceled';
-            break;
-        default:
-            status = 'open';
-    }
-    const typeRaw = str(o.o).toUpperCase();
-    let type;
-    switch (typeRaw) {
-        case 'LIMIT':
-            type = 'limit';
-            break;
-        case 'MARKET':
-            type = 'market';
-            break;
-        case 'STOP_MARKET':
-            type = 'stop_market';
-            break;
-        case 'TAKE_PROFIT_MARKET':
-            type = 'take_profit_market';
-            break;
-        default: type = 'other';
-    }
-    const sideRaw = str(o.S).toUpperCase();
-    const side = sideRaw === 'SELL' ? 'sell' : 'buy';
-    const origPrice = o.p != null && str(o.p) !== '' ? num(o.p) : null;
-    const avgPrice = o.ap != null && num(o.ap) > 0 ? num(o.ap) : null;
-    const lastFillPrice = o.L != null && num(o.L) > 0 ? num(o.L) : null;
-    // Audit-trail fields. `o.t` is Binance's stable trade id, present only on
-    // executionType='TRADE' (fill events); for NEW / CANCELED / EXPIRED it's
-    // either absent or 0. We store null in those cases so callers don't
-    // accidentally upsert with a meaningless id.
-    const tradeIdRaw = o.t;
-    const tradeId = tradeIdRaw != null && str(tradeIdRaw) !== '' && str(tradeIdRaw) !== '0'
-        ? str(tradeIdRaw)
-        : null;
-    return {
-        eventTime: num(obj.E),
-        transactionTime: num(obj.T),
-        symbol: translateSymbol(str(o.s)),
-        orderId: str(o.i),
-        clientOrderId: optStr(o.c),
-        side,
-        type,
-        status,
-        executionType: str(o.x),
-        origQuantity: num(o.q),
-        cumulativeFilled: num(o.z),
-        lastFilledQty: num(o.l),
-        avgPrice,
-        origPrice,
-        lastFillPrice,
-        commission: num(o.n),
-        commissionAsset: str(o.N),
-        timeInForce: str(o.f),
-        tradeId,
-        reduceOnly: o.R === true,
-        maker: o.m === true,
-        realizedPnl: num(o.rp),
-    };
-}
-export function parseMarginCall(obj, translateSymbol = IDENTITY) {
-    const positionsRaw = Array.isArray(obj.p) ? obj.p : [];
-    return {
-        eventTime: num(obj.E),
-        crossWallet: num(obj.cw),
-        positions: positionsRaw.map((p) => ({
-            symbol: translateSymbol(str(p.s)),
-            positionSide: str(p.ps),
-            positionAmt: num(p.pa),
-            marginType: str(p.mt).toLowerCase() === 'isolated' ? 'isolated' : 'cross',
-            isolatedWallet: num(p.iw),
-            markPrice: num(p.mp),
-            unrealizedPnl: num(p.up),
-            maintMargin: num(p.mm),
-        })),
-    };
-}
-export function parseAlgoUpdate(obj, translateSymbol = IDENTITY) {
-    // Field shape verified 2026-05-15 against the authoritative Binance doc
-    // (developers.binance.com → USD-M Futures → User Data Streams → Event
-    // Algo Order Update) AND a raw prod ALGO_UPDATE capture. The earlier
-    // implementation guessed `ao`/`a` wrapper + `c`/`sp`/`as`/`r` keys — ALL
-    // wrong; it parsed nothing. Binance wraps the algo-order detail under `o`:
-    //   { "e":"ALGO_UPDATE","T","E","o":{ caid, aid, at, o, s, S, ps, f, q,
-    //     X, ai, ap, aq, act, tp, p, V, wt, pm, cp, pP, R, tt, gtd, rm } }
-    // where (doc-exact):
-    //   caid = Client Algo Id    aid = Algo Id        s = Symbol
-    //   S = Side                 o   = Order Type     X = Algo Status
-    //   tp = Trigger Price       q   = Quantity       R = Reduce Only
-    //   f = Time In Force        V   = STP Mode       rm = Failure Reason
-    //   ai = Order Id (matching-engine order id, NOT the algo id)
-    const o = obj.o;
-    if (!o)
-        return null;
-    const rawSym = optStr(o.s);
-    if (!rawSym)
-        return null;
-    const sideRaw = str(o.S).toUpperCase();
-    const side = sideRaw === 'SELL' ? 'sell' : 'buy';
-    // Algo Status `X`: NEW / TRIGGERING / TRIGGERED / FINISHED / CANCELED /
-    // REJECTED / EXPIRED. Semantics that matter downstream (doc-confirmed):
-    //   CANCELED = MANUALLY canceled (an explicit cancelOrder from us)
-    //   EXPIRED  = SYSTEM-canceled (e.g. GTE_GTC conditional + position closed
-    //              → Binance auto-cancels the surviving sibling). EXPECTED.
-    const statusRaw = str(o.X).toUpperCase();
-    // Trigger price is `tp` (doc-exact). `p` is the (limit) order price, 0 for
-    // market-type triggers.
-    const trigRaw = o.tp;
-    const triggerPrice = trigRaw != null && num(trigRaw) > 0 ? num(trigRaw) : null;
-    return {
-        eventTime: num(obj.E),
-        transactionTime: num(obj.T),
-        symbol: translateSymbol(rawSym),
-        algoId: str(o.aid ?? ''),
-        clientAlgoId: optStr(o.caid) ?? null,
-        side,
-        orderType: str(o.o ?? '').toUpperCase(),
-        status: statusRaw,
-        triggerPrice,
-        quantity: num(o.q),
-        reduceOnly: o.R === true,
-        // `rm` = Failure Reason (doc-exact). Present on REJECTED/EXPIRED.
-        reason: optStr(o.rm),
-        raw: obj,
-    };
-}
-export function parseAccountConfigUpdate(obj, translateSymbol = IDENTITY) {
-    const ac = obj.ac; // leverage
-    const ai = obj.ai; // multi-asset mode
-    if (ac) {
-        const rawSym = optStr(ac.s);
-        return {
-            eventTime: num(obj.E),
-            kind: 'leverage',
-            symbol: rawSym ? translateSymbol(rawSym) : undefined,
-            leverage: num(ac.l),
-        };
-    }
-    if (ai) {
-        return {
-            eventTime: num(obj.E),
-            kind: 'multi_asset_mode',
-            multiAssetMode: Boolean(ai.j),
-        };
-    }
-    return {
-        eventTime: num(obj.E),
-        kind: 'other',
-    };
-}
-function hash8(key) {
-    return key.length > 8 ? key.slice(0, 8) : '(short)';
-}