@reefclaw/openclaw-plugin 0.1.0

package/live/user-data-stream.js

@@ -0,0 +1,704 @@
+// 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)';
+}