@reefclaw/connect 0.1.10 → 0.1.12

package/assets/plugin/live/exchange-info-cache.d.ts

@@ -1,37 +0,0 @@
-export interface SymbolRules {
-    minNotional: number;
-    minQty: number;
-    stepSize: number;
-    tickSize: number;
-    maxQty: number;
-    pricePrecision: number;
-    amountPrecision: number;
-}
-export interface ValidationResult {
-    valid: boolean;
-    error?: string;
-    roundedAmount: number;
-    roundedPrice?: number;
-}
-/**
- * Normalize symbol format for consistent lookups.
- * Tools use "BTC/USDT", CCXT futures markets are "BTC/USDT:USDT".
- * This function tries both formats to find a match.
- */
-export declare function normalizeSymbol(symbol: string, knownSymbols: Set<string>): string;
-export declare class ExchangeInfoCache {
-    private rules;
-    /** Set of all known symbols for normalization lookups. */
-    private knownSymbols;
-    /** Load market info from CCXT exchange instance. Throws on failure (incl.
-     *  an active ban — the gate short-circuits with zero network so a boot
-     *  during a 418 can't extend it); callers treat a throw as init failure. */
-    load(exchange: any): Promise<void>;
-    /** Get rules for a symbol (tries both BTC/USDT and BTC/USDT:USDT formats). */
-    getRules(symbol: string): SymbolRules | undefined;
-    /** Validate and round order parameters before submission. */
-    validate(symbol: string, amount: number, price?: number, lastPrice?: number): ValidationResult;
-    /** Round value to step size and precision. */
-    private roundToStep;
-    get size(): number;
-}

package/assets/plugin/live/exchange-info-cache.js

@@ -1,134 +0,0 @@
-// Exchange info cache — caches per-symbol trading rules (min notional, lot sizes, tick sizes).
-// Loaded once on startup from CCXT loadMarkets(), used to validate and round orders before submission.
-import { logger } from '../logger.js';
-import { assertNotBanned, noteBinanceError, noteSuccess } from '../ccxt/binance-ban-gate.js';
-const TAG = 'exchange-info';
-/**
- * Normalize symbol format for consistent lookups.
- * Tools use "BTC/USDT", CCXT futures markets are "BTC/USDT:USDT".
- * This function tries both formats to find a match.
- */
-export function normalizeSymbol(symbol, knownSymbols) {
-    // Exact match first
-    if (knownSymbols.has(symbol))
-        return symbol;
-    // Try adding :USDT suffix (most common futures pattern)
-    const withSuffix = `${symbol}:USDT`;
-    if (knownSymbols.has(withSuffix))
-        return withSuffix;
-    // Try removing :USDT suffix
-    const withoutSuffix = symbol.replace(/:USDT$/, '');
-    if (knownSymbols.has(withoutSuffix))
-        return withoutSuffix;
-    // No match — return as-is (will fail validation with "Unknown symbol")
-    return symbol;
-}
-export class ExchangeInfoCache {
-    rules = new Map();
-    /** Set of all known symbols for normalization lookups. */
-    knownSymbols = new Set();
-    /** Load market info from CCXT exchange instance. Throws on failure (incl.
-     *  an active ban — the gate short-circuits with zero network so a boot
-     *  during a 418 can't extend it); callers treat a throw as init failure. */
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    async load(exchange) {
-        let info;
-        try {
-            // GET /fapi/v1/exchangeInfo via ccxt loadMarkets — IP weight 1
-            // (doc-verified). Ban-gated but never weight-paced (NEVER_PACE):
-            // once-per-boot and required for order validation + emergency close.
-            assertNotBanned('loadMarkets');
-            info = await exchange.loadMarkets(true); // force refresh
-            noteSuccess();
-        }
-        catch (err) {
-            noteBinanceError(err);
-            throw err;
-        }
-        for (const [symbol, market] of Object.entries(info)) {
-            const m = market;
-            // Only cache futures (swap) markets
-            if (m.type !== 'swap')
-                continue;
-            const limits = m.limits;
-            const precision = m.precision;
-            const rules = {
-                minNotional: limits?.cost?.min ?? 5,
-                minQty: limits?.amount?.min ?? 0.001,
-                stepSize: precision?.amount != null ? Math.pow(10, -precision.amount) : 0.001,
-                tickSize: precision?.price != null ? Math.pow(10, -precision.price) : 0.01,
-                maxQty: limits?.amount?.max ?? Infinity,
-                pricePrecision: precision?.price ?? 2,
-                amountPrecision: precision?.amount ?? 3,
-            };
-            // Store under both "BTC/USDT:USDT" and "BTC/USDT" keys for lookup flexibility
-            this.rules.set(symbol, rules);
-            this.knownSymbols.add(symbol);
-            const shortSymbol = symbol.replace(/:USDT$/, '');
-            if (shortSymbol !== symbol && !this.rules.has(shortSymbol)) {
-                this.rules.set(shortSymbol, rules);
-                this.knownSymbols.add(shortSymbol);
-            }
-        }
-        logger.info(TAG, `Loaded exchange rules for ${this.knownSymbols.size} symbols`);
-    }
-    /** Get rules for a symbol (tries both BTC/USDT and BTC/USDT:USDT formats). */
-    getRules(symbol) {
-        return this.rules.get(symbol) ?? this.rules.get(normalizeSymbol(symbol, this.knownSymbols));
-    }
-    /** Validate and round order parameters before submission. */
-    validate(symbol, amount, price, lastPrice) {
-        const normalized = normalizeSymbol(symbol, this.knownSymbols);
-        const rules = this.rules.get(normalized);
-        if (!rules)
-            return { valid: false, error: `Unknown symbol: ${symbol}`, roundedAmount: amount };
-        const roundedAmount = this.roundToStep(amount, rules.stepSize, rules.amountPrecision);
-        const roundedPrice = price != null
-            ? this.roundToStep(price, rules.tickSize, rules.pricePrecision)
-            : undefined;
-        if (roundedAmount < rules.minQty) {
-            // Include the requested amount + the rule context. Without this, sub-step
-            // requests floor to 0 and the agent reads "Amount 0 below min 0.001"
-            // as a validator bug rather than as "your size is below the exchange
-            // minimum". Surface the dollar minimum too when we know the price —
-            // tells the agent exactly how much to size up.
-            const refPrice = roundedPrice ?? price ?? lastPrice;
-            const minNotionalAtPrice = refPrice != null && refPrice > 0
-                ? ` (~$${(rules.minQty * refPrice).toFixed(2)})`
-                : '';
-            const requestedDesc = roundedAmount === amount
-                ? `${roundedAmount}`
-                : `${amount} (rounded to ${roundedAmount} by step ${rules.stepSize})`;
-            return {
-                valid: false,
-                error: `Amount ${requestedDesc} below min ${rules.minQty}${minNotionalAtPrice} for ${symbol}`,
-                roundedAmount,
-            };
-        }
-        if (roundedAmount > rules.maxQty) {
-            return { valid: false, error: `Amount ${roundedAmount} above max ${rules.maxQty} for ${symbol}`, roundedAmount };
-        }
-        // Check min notional (order value)
-        const refPrice = roundedPrice ?? lastPrice;
-        if (refPrice != null && refPrice > 0) {
-            const notional = roundedAmount * refPrice;
-            if (notional < rules.minNotional) {
-                return {
-                    valid: false,
-                    error: `Order notional $${notional.toFixed(2)} below minimum $${rules.minNotional} for ${symbol}`,
-                    roundedAmount,
-                    roundedPrice,
-                };
-            }
-        }
-        return { valid: true, roundedAmount, roundedPrice };
-    }
-    /** Round value to step size and precision. */
-    roundToStep(value, stepSize, precision) {
-        const stepped = Math.floor(value / stepSize) * stepSize;
-        return Number(stepped.toFixed(precision));
-    }
-    get size() {
-        return this.rules.size;
-    }
-}

package/assets/plugin/live/fact-subscriber.d.ts

@@ -1,78 +0,0 @@
-import type { MarketContext } from '@reefclaw/shared';
-export interface ParsedEvent {
-    id?: number;
-    event: string;
-    data: string;
-}
-/**
- * Incremental SSE parser. Feed raw text; returns the complete events plus the
- * unparsed remainder (a partial event still arriving at the buffer tail). Pure.
- */
-export declare function parseSse(buffer: string): {
-    events: ParsedEvent[];
-    remainder: string;
-};
-export interface FactSubscriberOptions {
-    /** Intel base URL, e.g. https://intel.reefclaw.com */
-    baseUrl: string;
-    /** rc_ connection token. */
-    token: string;
-    symbols: string[];
-    /** Injected for tests; defaults to global fetch. */
-    fetchImpl?: typeof fetch;
-    /** Base reconnect delay (ms). Doubles per consecutive failure with ±20%
-     *  jitter up to reconnectCapMs — a fixed delay would hard-loop a 401/404
-     *  (token misconfig / stream disabled) at max rate forever. */
-    reconnectDelayMs?: number;
-    /** Reconnect backoff cap (ms, default 60s). */
-    reconnectCapMs?: number;
-    /** Abort + reconnect when a LIVE connection delivers no bytes for this
-     *  long (default 30s = 6× the broadcaster's 5s cadence). Without this, a
-     *  silently stalled stream (no close, no RST) leaves `reader.read()`
-     *  pending forever while the evaluator keeps serving ever-staler facts —
-     *  same class as the user-data-stream / routed-WS staleness watchdogs. */
-    stallThresholdMs?: number;
-    /** Injected for tests. */
-    now?: () => number;
-}
-export declare class FactSubscriber {
-    private readonly opts;
-    private readonly latest;
-    /** Per-symbol wall-clock receipt time of the latest fact (now()-based). */
-    private readonly latestAt;
-    private buffer;
-    private lastEventId;
-    private running;
-    private controller;
-    private applied;
-    private errors;
-    private stalls;
-    private consecutiveFailures;
-    /** 0 = no live connection; otherwise last byte-activity time. */
-    private lastChunkAt;
-    private watchdog;
-    private readonly now;
-    constructor(opts: FactSubscriberOptions);
-    /** Latest streamed context for a symbol — what the evaluator reads. */
-    getLatest(symbol: string): MarketContext | null;
-    /** When the latest fact for a symbol ARRIVED (receipt clock, not the
-     *  context's own timestamp). Null when no fact has ever arrived. Callers
-     *  use this to refuse stale facts (LocalSignalService.getSnapshot). */
-    getLatestFactAt(symbol: string): number | null;
-    getStats(): {
-        applied: number;
-        errors: number;
-        stalls: number;
-        lastEventId: number | undefined;
-        symbols: number;
-    };
-    /** Apply one parsed event: deserialize a `fact` and store it as the latest
-     *  context for its symbol. No I/O — exposed for tests. */
-    applyEvent(ev: ParsedEvent): void;
-    /** Feed a raw text chunk; handles events split across chunk boundaries. */
-    ingest(chunk: string): void;
-    start(): void;
-    stop(): void;
-    private backoffMs;
-    private loop;
-}

package/assets/plugin/live/fact-subscriber.js

@@ -1,182 +0,0 @@
-// Plugin-side fact stream subscriber — facts-out (docs/FACTS_OUT_ARCHITECTURE.md)
-// step 4. Connects to the intel broadcaster's SSE endpoint
-// (/api/facts/subscribe), maintains the latest MarketContext per symbol, and
-// feeds it to the LocalStrategyEvaluator (PR #45). Reconnects with Last-Event-ID.
-//
-// Uses the SAME matched (de)serializer the broadcaster uses (shared via the sync
-// manifest), so the wire round-trip is byte-identical — the Date fields are
-// rehydrated rather than left as strings.
-//
-// NOT wired into the heartbeat yet — built + tested standalone. The parse /
-// apply core is pure and unit-tested; the fetch loop is thin plumbing.
-import { deserializeContext } from '../signals/serialize-context.js';
-/**
- * Incremental SSE parser. Feed raw text; returns the complete events plus the
- * unparsed remainder (a partial event still arriving at the buffer tail). Pure.
- */
-export function parseSse(buffer) {
-    const events = [];
-    let sep;
-    // Events are terminated by a blank line ("\n\n").
-    while ((sep = buffer.indexOf('\n\n')) !== -1) {
-        const raw = buffer.slice(0, sep);
-        buffer = buffer.slice(sep + 2);
-        let id;
-        let event = 'message';
-        const dataLines = [];
-        for (const line of raw.split('\n')) {
-            if (line.startsWith('id:')) {
-                const v = Number(line.slice(3).trim());
-                if (Number.isFinite(v))
-                    id = v;
-            }
-            else if (line.startsWith('event:')) {
-                event = line.slice(6).trim();
-            }
-            else if (line.startsWith('data:')) {
-                dataLines.push(line.slice(5).replace(/^ /, ''));
-            }
-            // ":" comment lines and unknown fields are ignored, per the SSE spec.
-        }
-        events.push({ id, event, data: dataLines.join('\n') });
-    }
-    return { events, remainder: buffer };
-}
-export class FactSubscriber {
-    opts;
-    latest = new Map();
-    /** Per-symbol wall-clock receipt time of the latest fact (now()-based). */
-    latestAt = new Map();
-    buffer = '';
-    lastEventId;
-    running = false;
-    controller = null;
-    applied = 0;
-    errors = 0;
-    stalls = 0;
-    consecutiveFailures = 0;
-    /** 0 = no live connection; otherwise last byte-activity time. */
-    lastChunkAt = 0;
-    watchdog = null;
-    now;
-    constructor(opts) {
-        this.opts = opts;
-        this.now = opts.now ?? Date.now;
-    }
-    /** Latest streamed context for a symbol — what the evaluator reads. */
-    getLatest(symbol) {
-        return this.latest.get(symbol) ?? null;
-    }
-    /** When the latest fact for a symbol ARRIVED (receipt clock, not the
-     *  context's own timestamp). Null when no fact has ever arrived. Callers
-     *  use this to refuse stale facts (LocalSignalService.getSnapshot). */
-    getLatestFactAt(symbol) {
-        return this.latestAt.get(symbol) ?? null;
-    }
-    getStats() {
-        return {
-            applied: this.applied,
-            errors: this.errors,
-            stalls: this.stalls,
-            lastEventId: this.lastEventId,
-            symbols: this.latest.size,
-        };
-    }
-    /** Apply one parsed event: deserialize a `fact` and store it as the latest
-     *  context for its symbol. No I/O — exposed for tests. */
-    applyEvent(ev) {
-        if (ev.id !== undefined)
-            this.lastEventId = ev.id;
-        if (ev.event !== 'fact')
-            return;
-        try {
-            const ctx = deserializeContext(ev.data);
-            this.latest.set(ctx.symbol, ctx);
-            this.latestAt.set(ctx.symbol, this.now());
-            this.applied++;
-        }
-        catch {
-            this.errors++;
-        }
-    }
-    /** Feed a raw text chunk; handles events split across chunk boundaries. */
-    ingest(chunk) {
-        this.buffer += chunk;
-        const { events, remainder } = parseSse(this.buffer);
-        this.buffer = remainder;
-        for (const ev of events)
-            this.applyEvent(ev);
-    }
-    start() {
-        if (this.running)
-            return;
-        this.running = true;
-        const stallMs = this.opts.stallThresholdMs ?? 30_000;
-        this.watchdog = setInterval(() => {
-            if (!this.running || this.lastChunkAt === 0)
-                return;
-            if (this.now() - this.lastChunkAt > stallMs) {
-                this.stalls++;
-                this.lastChunkAt = 0; // one abort per stall — reset until reconnect
-                this.controller?.abort();
-            }
-        }, Math.max(1_000, Math.floor(stallMs / 3)));
-        this.watchdog.unref?.();
-        void this.loop();
-    }
-    stop() {
-        this.running = false;
-        if (this.watchdog) {
-            clearInterval(this.watchdog);
-            this.watchdog = null;
-        }
-        this.controller?.abort();
-    }
-    backoffMs() {
-        const base = this.opts.reconnectDelayMs ?? 3_000;
-        const cap = this.opts.reconnectCapMs ?? 60_000;
-        const exp = Math.min(base * 2 ** Math.min(this.consecutiveFailures, 10), cap);
-        return Math.round(exp * (0.8 + Math.random() * 0.4)); // ±20% jitter
-    }
-    async loop() {
-        const doFetch = this.opts.fetchImpl ?? fetch;
-        const url = `${this.opts.baseUrl}/api/facts/subscribe?symbols=${encodeURIComponent(this.opts.symbols.join(','))}`;
-        while (this.running) {
-            this.controller = new AbortController();
-            let gotData = false;
-            try {
-                const headers = {
-                    Authorization: `Bearer ${this.opts.token}`,
-                    Accept: 'text/event-stream',
-                };
-                if (this.lastEventId !== undefined)
-                    headers['Last-Event-ID'] = String(this.lastEventId);
-                const resp = await doFetch(url, { headers, signal: this.controller.signal });
-                if (!resp.ok || !resp.body)
-                    throw new Error(`fact stream HTTP ${resp.status}`);
-                this.buffer = '';
-                this.lastChunkAt = this.now(); // arm the stall watchdog
-                const reader = resp.body.getReader();
-                const decoder = new TextDecoder();
-                while (this.running) {
-                    const { done, value } = await reader.read();
-                    if (done)
-                        break;
-                    this.lastChunkAt = this.now();
-                    gotData = true;
-                    this.ingest(decoder.decode(value, { stream: true }));
-                }
-            }
-            catch {
-                if (!this.running)
-                    return;
-                this.errors++;
-            }
-            this.lastChunkAt = 0; // no live connection — watchdog idle
-            if (!this.running)
-                return;
-            this.consecutiveFailures = gotData ? 0 : this.consecutiveFailures + 1;
-            await new Promise((r) => setTimeout(r, this.backoffMs()));
-        }
-    }
-}

package/assets/plugin/live/intent-journal.d.ts

@@ -1,42 +0,0 @@
-export interface OrderIntent {
-    clientOrderId: string;
-    symbol: string;
-    side: 'buy' | 'sell';
-    type: 'market' | 'limit';
-    amount: number;
-    price?: number;
-    createdAt: string;
-    status: 'pending' | 'submitted' | 'confirmed' | 'failed';
-    exchangeOrderId?: string;
-    error?: string;
-    resolvedAt?: string;
-}
-export declare class IntentJournal {
-    private readonly filePath;
-    private intents;
-    /** `basePath` overrides the storage root (default `~/.openclaw/plugins`).
-     *  Tests pass a temp dir to keep runs hermetic; production omits it.
-     *  `OPENCLAW_HOME` env var, when set, also reroutes the default base. */
-    constructor(pluginId?: string, opts?: {
-        basePath?: string;
-    });
-    /** Record a new order intent BEFORE submitting to exchange. */
-    recordIntent(intent: Omit<OrderIntent, 'createdAt' | 'status'>): OrderIntent;
-    /** Update intent status after exchange response. */
-    updateIntent(clientOrderId: string, update: Partial<Pick<OrderIntent, 'status' | 'exchangeOrderId' | 'error'>>): void;
-    /** Get all unresolved intents (pending or submitted). */
-    getUnresolved(): OrderIntent[];
-    /** Get intent by clientOrderId. */
-    getIntent(clientOrderId: string): OrderIntent | undefined;
-    /** Get the journal file path. */
-    getFilePath(): string;
-    /** Load existing intents from JSONL file. Later entries override earlier ones (last-write-wins). */
-    private loadExisting;
-    /** Append a line to the JSONL file. */
-    private appendLine;
-    /**
-     * Compact the journal — rewrite with only the latest state of each intent.
-     * Call periodically (e.g., daily) to prevent unbounded file growth.
-     */
-    compact(): void;
-}

package/assets/plugin/live/intent-journal.js

@@ -1,122 +0,0 @@
-// Order intent journal — append-only JSONL file for crash recovery and idempotency.
-// Every live order intent is written BEFORE submission. On network timeout,
-// check exchange by clientOrderId before retry. On restart, resolve all pending intents.
-import { appendFileSync, readFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-import { logger, formatError } from '../logger.js';
-import { resolvePluginsBaseDir } from '../util/plugin-paths.js';
-const TAG = 'intent-journal';
-export class IntentJournal {
-    filePath;
-    intents = new Map();
-    /** `basePath` overrides the storage root (default `~/.openclaw/plugins`).
-     *  Tests pass a temp dir to keep runs hermetic; production omits it.
-     *  `OPENCLAW_HOME` env var, when set, also reroutes the default base. */
-    constructor(pluginId, opts) {
-        const base = resolvePluginsBaseDir(opts?.basePath);
-        const dir = join(base, pluginId ?? 'reefclaw-paper-trading');
-        if (!existsSync(dir)) {
-            mkdirSync(dir, { recursive: true });
-        }
-        this.filePath = join(dir, 'order-intents.jsonl');
-        this.loadExisting();
-    }
-    /** Record a new order intent BEFORE submitting to exchange. */
-    recordIntent(intent) {
-        const full = {
-            ...intent,
-            createdAt: new Date().toISOString(),
-            status: 'pending',
-        };
-        this.intents.set(full.clientOrderId, full);
-        this.appendLine(full);
-        logger.info(TAG, `Intent recorded: ${full.clientOrderId} ${full.side} ${full.amount} ${full.symbol}`);
-        return full;
-    }
-    /** Update intent status after exchange response. */
-    updateIntent(clientOrderId, update) {
-        const intent = this.intents.get(clientOrderId);
-        if (!intent) {
-            logger.warn(TAG, `Intent not found for update: ${clientOrderId}`);
-            return;
-        }
-        if (update.status)
-            intent.status = update.status;
-        if (update.exchangeOrderId)
-            intent.exchangeOrderId = update.exchangeOrderId;
-        if (update.error)
-            intent.error = update.error;
-        if (update.status === 'confirmed' || update.status === 'failed') {
-            intent.resolvedAt = new Date().toISOString();
-        }
-        this.appendLine(intent);
-    }
-    /** Get all unresolved intents (pending or submitted). */
-    getUnresolved() {
-        return Array.from(this.intents.values()).filter(i => i.status === 'pending' || i.status === 'submitted');
-    }
-    /** Get intent by clientOrderId. */
-    getIntent(clientOrderId) {
-        return this.intents.get(clientOrderId);
-    }
-    /** Get the journal file path. */
-    getFilePath() {
-        return this.filePath;
-    }
-    // ---- Internal ----
-    /** Load existing intents from JSONL file. Later entries override earlier ones (last-write-wins). */
-    loadExisting() {
-        if (!existsSync(this.filePath))
-            return;
-        try {
-            const content = readFileSync(this.filePath, 'utf-8');
-            const lines = content.split('\n').filter(l => l.trim());
-            for (const line of lines) {
-                try {
-                    const intent = JSON.parse(line);
-                    if (intent.clientOrderId) {
-                        this.intents.set(intent.clientOrderId, intent);
-                    }
-                }
-                catch {
-                    // Skip malformed lines
-                }
-            }
-            const unresolved = this.getUnresolved();
-            if (unresolved.length > 0) {
-                logger.warn(TAG, `Loaded ${this.intents.size} intents, ${unresolved.length} unresolved`);
-            }
-            else {
-                logger.info(TAG, `Loaded ${this.intents.size} intents, all resolved`);
-            }
-        }
-        catch (err) {
-            logger.error(TAG, `Failed to load intent journal: ${formatError(err)}`);
-        }
-    }
-    /** Append a line to the JSONL file. */
-    appendLine(intent) {
-        try {
-            appendFileSync(this.filePath, JSON.stringify(intent) + '\n');
-        }
-        catch (err) {
-            logger.error(TAG, `Failed to write intent: ${formatError(err)}`);
-        }
-    }
-    /**
-     * Compact the journal — rewrite with only the latest state of each intent.
-     * Call periodically (e.g., daily) to prevent unbounded file growth.
-     */
-    compact() {
-        try {
-            const lines = Array.from(this.intents.values())
-                .map(i => JSON.stringify(i))
-                .join('\n') + '\n';
-            writeFileSync(this.filePath, lines);
-            logger.info(TAG, `Compacted journal: ${this.intents.size} intents`);
-        }
-        catch (err) {
-            logger.error(TAG, `Failed to compact journal: ${formatError(err)}`);
-        }
-    }
-}

package/assets/plugin/live/listen-key-manager.d.ts

@@ -1,70 +0,0 @@
-import { EventEmitter } from 'node:events';
-import type { BinancePrivateApi } from '../ccxt/binance-private.js';
-/** Injectable timer/clock deps — makes fake-timer tests trivial. */
-export interface ListenKeyTimerDeps {
-    setTimeout: (fn: () => void, ms: number) => ReturnType<typeof setTimeout>;
-    clearTimeout: (handle: ReturnType<typeof setTimeout>) => void;
-    now: () => number;
-}
-export interface ListenKeyManagerOptions {
-    /** Defaults to 25 * 60_000 (25 min). */
-    refreshIntervalMs?: number;
-    /** How many consecutive keep-alive failures before emitting 'keyKeepAliveFailed'.
-     *  Defaults to 3 — transient network failures self-recover; a sustained
-     *  failure probably means the key is gone and the parent must reconnect. */
-    maxConsecutiveFailures?: number;
-    /** Timer injection for tests. Defaults to real setTimeout/Date. */
-    timers?: Partial<ListenKeyTimerDeps>;
-}
-/** Emitted events. Callers should treat 'keyKeepAliveFailed' as "drop the WS
- *  and restart from scratch" — the current key is presumed dead. */
-export type ListenKeyEvents = {
-    /** Fresh key minted via POST /fapi/v1/listenKey. Fires on start() and
-     *  after every successful re-mint. */
-    keyMinted: (listenKey: string) => void;
-    /** A keep-alive (PUT) succeeded. Informational — mostly for observability. */
-    keyRefreshed: () => void;
-    /** Consecutive keep-alive failures reached `maxConsecutiveFailures`. The
-     *  parent should treat the stream as dead and reconnect from scratch. */
-    keyKeepAliveFailed: (reason: string) => void;
-};
-/** Lightweight typed emitter — EventEmitter with a phantom type. */
-export declare class ListenKeyManager extends EventEmitter {
-    private readonly api;
-    private readonly refreshIntervalMs;
-    private readonly maxConsecutiveFailures;
-    private readonly timers;
-    private currentKey;
-    private keyMintedAt;
-    private refreshTimer;
-    private consecutiveFailures;
-    private running;
-    constructor(api: BinancePrivateApi, options?: ListenKeyManagerOptions);
-    /** Mint a listenKey and start the refresh loop. Returns the minted key.
-     *  Throws if the first POST fails — caller decides how to back off. */
-    start(): Promise<string>;
-    /** Stop the refresh loop and best-effort close the key. Idempotent.
-     *  For GRACEFUL shutdown only — a reconnect-driven teardown must use
-     *  `stopKeepAlive()` instead (see below). */
-    stop(): Promise<void>;
-    /** Stop the refresh loop WITHOUT the DELETE — for reconnect-driven closes.
-     *  Binance returns the SAME active listenKey on a re-POST and merely
-     *  extends its validity (doc-verified 2026-07-02: "Doing a POST on an
-     *  account with an active listenKey will return the currently active
-     *  listenKey and extend its validity for 60 minutes"), so an in-flight
-     *  DELETE racing the reconnect's POST can land AFTER it and invalidate the
-     *  key the fresh socket just authenticated with — a silent dead stream.
-     *  Skipping the DELETE is safe: an unused key expires on its own after
-     *  60 min of no keep-alive. Synchronous + idempotent. */
-    stopKeepAlive(): void;
-    /** Current listenKey, or null if stopped. */
-    getKey(): string | null;
-    /** Age in ms since the key was last minted. Null if stopped. Useful for
-     *  observability dashboards — a key far beyond refreshIntervalMs but still
-     *  alive means Binance is tolerating us past the nominal window. */
-    getKeyAge(): number | null;
-    /** Number of consecutive failed keep-alive probes. Exposed for diagnostics. */
-    getConsecutiveFailures(): number;
-    private scheduleRefresh;
-    private refresh;
-}