@reefclaw/connect 0.1.10 → 0.1.12

package/assets/plugin/live/live-balance-enricher.d.ts

@@ -1,32 +0,0 @@
-import type { CcxtBalance, CcxtPosition } from '../types.js';
-/** UTC date in YYYY-MM-DD form — same shape as `closedAt.slice(0, 10)`. */
-export declare function utcDateString(ms: number): string;
-/** Epoch ms for the most recent 00:00:00 UTC boundary at-or-before `ms`. */
-export declare function utcMidnightMs(ms?: number): number;
-export declare class LiveBalanceEnricher {
-    private sessionStartNav;
-    private fills;
-    private allTimeSeed;
-    private realizedTodaySeed;
-    private realizedTodaySeedDate;
-    setSessionStartNav(nav: number): void;
-    getSessionStartNav(): number;
-    /** Seed all-time realized PnL from Intelligence DB (pre-session history). */
-    seedAllTimeRealized(total: number): void;
-    /** Seed today's realized PnL from Binance's income endpoint. The seed
-     *  represents everything Binance has booked for the current UTC day. The
-     *  webapp dashboard now derives Realized as (totalPnl - unrealizedPnl)
-     *  for guaranteed consistency with Day P&L (see webapp trades.ts), so
-     *  this seed is used only for sessionStartNav anchoring + the
-     *  `realizedPnlToday` field that older consumers may still read. */
-    seedRealizedPnlToday(amount: number, dateUtc?: string): void;
-    /** Record a completed fill for realized PnL tracking. Currently unused in
-     *  production (the income-endpoint seed is the sole source of Realized);
-     *  retained for tests that exercise the accumulator semantics. */
-    recordFill(pnl: number, fee: number): void;
-    /**
-     * Enrich a raw CCXT balance with session PnL, equity, and sessionStartNav.
-     * Uses cached positions from the reconciler (no extra API call).
-     */
-    enrich(rawBalance: CcxtBalance, positions: CcxtPosition[]): CcxtBalance;
-}

package/assets/plugin/live/live-balance-enricher.js

@@ -1,104 +0,0 @@
-// LiveBalanceEnricher — attaches session PnL + equity fields to raw CCXT
-// balance responses from the LiveAdapter, matching the enriched format that
-// ExchangeSimulator.getBalance() produces. This lets the skill's
-// fetchFreshBalance() process live-mode responses identically to paper mode.
-import { getQuoteWalletBalance } from '../balance-utils.js';
-import { logger } from '../logger.js';
-const TAG = 'live-balance-enricher';
-/** UTC date in YYYY-MM-DD form — same shape as `closedAt.slice(0, 10)`. */
-export function utcDateString(ms) {
-    return new Date(ms).toISOString().slice(0, 10);
-}
-/** Epoch ms for the most recent 00:00:00 UTC boundary at-or-before `ms`. */
-export function utcMidnightMs(ms = Date.now()) {
-    return new Date(new Date(ms).toISOString().slice(0, 10) + 'T00:00:00Z').getTime();
-}
-export class LiveBalanceEnricher {
-    sessionStartNav = 0;
-    fills = [];
-    allTimeSeed = 0; // seeded from Intelligence DB
-    // Today's realized P&L seeded from Binance income endpoint at boot. Lets the
-    // dashboard's Realized KPI exactly match Binance's "Today's Realized PNL"
-    // even after a plugin restart (without this, sessionStartNav resets to the
-    // current NAV at boot and the day's realized P&L appears as $0). Reset to 0
-    // when the enricher's day rolls over past midnight UTC; subsequent fills are
-    // accumulated via recordFill() exactly as before.
-    realizedTodaySeed = 0;
-    realizedTodaySeedDate = utcDateString(Date.now());
-    setSessionStartNav(nav) {
-        this.sessionStartNav = nav;
-        logger.info(TAG, `Session-start NAV set: ${nav}`);
-    }
-    getSessionStartNav() {
-        return this.sessionStartNav;
-    }
-    /** Seed all-time realized PnL from Intelligence DB (pre-session history). */
-    seedAllTimeRealized(total) {
-        this.allTimeSeed = total;
-    }
-    /** Seed today's realized PnL from Binance's income endpoint. The seed
-     *  represents everything Binance has booked for the current UTC day. The
-     *  webapp dashboard now derives Realized as (totalPnl - unrealizedPnl)
-     *  for guaranteed consistency with Day P&L (see webapp trades.ts), so
-     *  this seed is used only for sessionStartNav anchoring + the
-     *  `realizedPnlToday` field that older consumers may still read. */
-    seedRealizedPnlToday(amount, dateUtc = utcDateString(Date.now())) {
-        this.realizedTodaySeed = amount;
-        this.realizedTodaySeedDate = dateUtc;
-        logger.info(TAG, `Today's realized PnL seeded from Binance: ${amount.toFixed(4)} (date=${dateUtc})`);
-    }
-    /** Record a completed fill for realized PnL tracking. Currently unused in
-     *  production (the income-endpoint seed is the sole source of Realized);
-     *  retained for tests that exercise the accumulator semantics. */
-    recordFill(pnl, fee) {
-        this.fills.push({
-            realizedPnl: pnl,
-            fee,
-            closedAt: new Date().toISOString(),
-        });
-    }
-    /**
-     * Enrich a raw CCXT balance with session PnL, equity, and sessionStartNav.
-     * Uses cached positions from the reconciler (no extra API call).
-     */
-    enrich(rawBalance, positions) {
-        const quoteTotal = getQuoteWalletBalance(rawBalance);
-        // Compute unrealized P&L from live positions
-        let unrealizedPnl = 0;
-        for (const p of positions) {
-            unrealizedPnl += p.unrealizedPnl ?? 0;
-        }
-        // Live equity = wallet balance + unrealized P&L.
-        // Binance wallet already accounts for margin deductions.
-        const equity = quoteTotal + unrealizedPnl;
-        // Realized P&L from fills accumulated this session
-        const today = utcDateString(Date.now());
-        // UTC rollover: if the seed is from a previous day, drop it. Today's
-        // realized then comes purely from fills the WS has observed since 00:00
-        // UTC (which is correct — anything earlier belongs to yesterday).
-        if (this.realizedTodaySeedDate !== today) {
-            this.realizedTodaySeed = 0;
-            this.realizedTodaySeedDate = today;
-        }
-        let realizedPnlToday = this.realizedTodaySeed;
-        let sessionRealized = 0;
-        let totalFees = 0;
-        for (const f of this.fills) {
-            const net = f.realizedPnl - f.fee;
-            sessionRealized += net;
-            totalFees += f.fee;
-            if (f.closedAt.slice(0, 10) === today) {
-                realizedPnlToday += net;
-            }
-        }
-        const realizedPnlAllTime = this.allTimeSeed + sessionRealized;
-        const round4 = (n) => +n.toFixed(4);
-        const enriched = { ...rawBalance };
-        enriched.realizedPnlAllTime = round4(realizedPnlAllTime);
-        enriched.realizedPnlToday = round4(realizedPnlToday);
-        enriched.totalRoundtripFees = round4(totalFees);
-        enriched.equity = round4(equity);
-        enriched.sessionStartNav = round4(this.sessionStartNav);
-        return enriched;
-    }
-}

package/assets/plugin/live/live-bracket-api.d.ts

@@ -1,13 +0,0 @@
-import type { BinancePrivateApi } from '../ccxt/binance-private.js';
-import type { CcxtOrder } from '../types.js';
-import type { BracketApi } from './bracket-manager.js';
-import type { BracketLegParams } from './bracket-params.js';
-export declare class LiveBracketApi implements BracketApi {
-    private readonly api;
-    constructor(api: BinancePrivateApi);
-    submitBracketLeg(leg: BracketLegParams): Promise<CcxtOrder>;
-    cancelOrderByClientId(clientOrderId: string, symbol: string): Promise<void>;
-    /** ROOT-CAUSE FIX 2026-05-16: disable the per-symbol countdownCancelAll
-     *  dead-man's-switch before bracket placement (see BinancePrivateApi). */
-    disableCountdownCancelAll(symbol: string): Promise<void>;
-}

package/assets/plugin/live/live-bracket-api.js

@@ -1,20 +0,0 @@
-// Thin BracketApi implementation backed by BinancePrivateApi. Kept separate
-// from BracketManager so tests can mock the minimal surface without pulling
-// in CCXT.
-export class LiveBracketApi {
-    api;
-    constructor(api) {
-        this.api = api;
-    }
-    async submitBracketLeg(leg) {
-        return this.api.createBracketOrder(leg.symbol, leg.type, leg.side, leg.amount, leg.params);
-    }
-    async cancelOrderByClientId(clientOrderId, symbol) {
-        await this.api.cancelOrderByClientId(clientOrderId, symbol);
-    }
-    /** ROOT-CAUSE FIX 2026-05-16: disable the per-symbol countdownCancelAll
-     *  dead-man's-switch before bracket placement (see BinancePrivateApi). */
-    async disableCountdownCancelAll(symbol) {
-        await this.api.disableCountdownCancelAll(symbol);
-    }
-}

package/assets/plugin/live/live-state-store.d.ts

@@ -1,194 +0,0 @@
-import { EventEmitter } from 'node:events';
-import type { CcxtPosition, CcxtBalance, CcxtOrder } from '../types.js';
-/** A single position line in an ACCOUNT_UPDATE event. */
-export interface ParsedPositionUpdate {
-    symbol: string;
-    /** 'long' | 'short' — collapsed from Binance's {LONG, SHORT, BOTH} where
-     *  BOTH is resolved from the sign of `quantity` (positive = long, negative = short).
-     *  Zero quantity → 'flat', meaning the position should be removed. */
-    side: 'long' | 'short' | 'flat';
-    quantity: number;
-    entryPrice: number;
-    unrealizedPnl: number;
-    marginType?: 'cross' | 'isolated';
-    /** Raw positionSide from Binance — used to sanity-check one-way mode.
-     *  On a one-way account, this is always 'BOTH'. */
-    positionSide?: 'LONG' | 'SHORT' | 'BOTH';
-}
-/** A single balance line in an ACCOUNT_UPDATE event. */
-export interface ParsedBalanceUpdate {
-    asset: string;
-    walletBalance: number;
-    crossWallet: number;
-    balanceChange: number;
-}
-/** The full payload of an ACCOUNT_UPDATE event (after parsing). */
-export interface ParsedAccountUpdate {
-    eventTime: number;
-    transactionTime: number;
-    reason: string;
-    positions: ParsedPositionUpdate[];
-    balances: ParsedBalanceUpdate[];
-}
-/** The payload of an ORDER_TRADE_UPDATE event (after parsing). */
-export interface ParsedOrderUpdate {
-    eventTime: number;
-    transactionTime: number;
-    symbol: string;
-    orderId: string;
-    clientOrderId?: string;
-    side: 'buy' | 'sell';
-    type: 'market' | 'limit' | 'stop_market' | 'take_profit_market' | 'other';
-    status: 'open' | 'closed' | 'canceled';
-    executionType: string;
-    origQuantity: number;
-    cumulativeFilled: number;
-    lastFilledQty: number;
-    avgPrice: number | null;
-    origPrice: number | null;
-    lastFillPrice: number | null;
-    commission: number;
-    commissionAsset: string;
-    /** Raw Binance timeInForce (GTC, IOC, etc.) — preserved for round-trip. */
-    timeInForce: string;
-    /** Stable Binance trade id from `o.t`. The idempotency key for the audit
-     *  trail. Present only on executionType='TRADE'; null on NEW/CANCELED. */
-    tradeId: string | null;
-    /** Reduce-only flag from `o.R`. True for bracket SL/TP fills + manual
-     *  reduce-only orders. */
-    reduceOnly: boolean;
-    /** Maker flag from `o.m`. True if this fill matched a resting order. */
-    maker: boolean;
-    /** Realised PnL on this specific fill, from `o.rp`. Negative on losses. */
-    realizedPnl: number;
-}
-/** A REST snapshot used to seed the store on connect + reconcile drift. */
-export interface RestSnapshot {
-    timestamp: number;
-    positions: CcxtPosition[];
-    balance: CcxtBalance | null;
-    openOrders: CcxtOrder[];
-}
-export type DriftSeverity = 'none' | 'minor' | 'major';
-export interface PositionDriftDetail {
-    symbol: string;
-    localContracts: number;
-    restContracts: number;
-    localSide: string | null;
-    restSide: string | null;
-    kind: 'new' | 'closed' | 'size_changed' | 'side_changed';
-}
-export interface BalanceDriftDetail {
-    asset: string;
-    localTotal: number;
-    restTotal: number;
-    deltaBps: number;
-}
-export interface OrderDriftDetail {
-    orderId: string;
-    symbol: string;
-    kind: 'missing_locally' | 'missing_on_rest';
-}
-export interface StateDrift {
-    severity: DriftSeverity;
-    positions: PositionDriftDetail[];
-    balance: BalanceDriftDetail[];
-    orders: OrderDriftDetail[];
-    summary: string;
-}
-/** Thresholds for drift classification. All tuned conservatively — minor
- *  drifts are expected background noise (in-flight events); major drifts
- *  are structural and trigger a forced resync. */
-export interface DriftThresholds {
-    /** Balance delta below this (basis points of the REST value) is minor. */
-    balanceMinorBps: number;
-    /** Position contract delta below this is minor. */
-    positionMinorContracts: number;
-}
-export type LiveStateStoreEvents = {
-    /** Emitted on every successful apply. Useful for observability / push-to-skill. */
-    stateChanged: (kind: 'snapshot' | 'account_update' | 'order_update' | 'algo_refresh' | 'mark_refresh') => void;
-    /** Emitted when apply fails (parse error, hedge-mode event, etc.). */
-    applyError: (kind: string, reason: string) => void;
-};
-export declare class LiveStateStore extends EventEmitter {
-    private positions;
-    private balances;
-    private orders;
-    private lastSnapshotAt;
-    private lastAccountUpdateAt;
-    private lastOrderUpdateAt;
-    private readonly thresholds;
-    constructor(thresholds?: Partial<DriftThresholds>);
-    /** Get positions, optionally filtered by symbol. Returns clones. */
-    getPositions(symbol?: string): CcxtPosition[];
-    /** Get the current balance view. Matches the CCXT shape. */
-    getBalance(): CcxtBalance;
-    /** Get open orders, optionally filtered by symbol. Returns clones. */
-    getOpenOrders(symbol?: string): CcxtOrder[];
-    /** Observability — last-apply timestamps for each write path. */
-    getHealth(): {
-        lastSnapshotAt: number | null;
-        lastAccountUpdateAt: number | null;
-        lastOrderUpdateAt: number | null;
-        positionCount: number;
-        orderCount: number;
-        balanceAssetCount: number;
-    };
-    /** Replace state with a REST snapshot. Called on connect + reconnect + forced resync.
-     *  Idempotent: a duplicate snapshot produces identical state. */
-    applySnapshot(snap: RestSnapshot): void;
-    /** Replace the algo-order subset of the store with a fresh REST list.
-     *
-     *  Binance's user-data WS does NOT emit ORDER_TRADE_UPDATE for algo orders
-     *  (STOP_MARKET / TAKE_PROFIT_MARKET) until they trigger — only the resulting
-     *  regular order fires the event. As a result, the store cannot observe algo
-     *  add/cancel/modify events via WS alone and diverges from REST whenever
-     *  brackets are touched.
-     *
-     *  This method closes that gap: callers (the controller's refresh loop) hand
-     *  it the current REST view of algo orders, and we swap them in wholesale
-     *  while leaving regular orders (WS-tracked) untouched. An order is classed
-     *  as "algo" iff its clientOrderId parses as a reefclaw bracket cid with
-     *  role stop or target. External algo orders (manual STOP_MARKET placed via
-     *  Binance UI with no rc- prefix) are NOT tracked by this path — the 60s
-     *  reconciler snapshot still covers them. */
-    replaceAlgoOrders(freshAlgoOrders: CcxtOrder[]): void;
-    /** Refresh ONLY the mark-derived soft fields (markPrice + unrealizedPnl) of
-     *  positions that already exist in the store, from a fresh REST snapshot.
-     *
-     *  Why this exists: Binance's user-data `ACCOUNT_UPDATE` is event-driven
-     *  (fills / funding / transfers) and carries NO per-tick mark price, so a
-     *  quiet open position's `unrealizedPnl` in this store is FROZEN at the last
-     *  event's value while the Binance app recomputes uPnl every mark tick. In
-     *  enforce/observe mode this store is the authoritative read path, so the
-     *  dashboard's Unrealized cell froze between events ("close but lags/frozen"
-     *  — 2026-05-16). The controller's 60s truth-check already fetches a fresh
-     *  REST snapshot (with live uPnl + mark) but DISCARDS it unless position
-     *  structure drifts (diffPositions ignores uPnl entirely). This method lets
-     *  the truth-check spend that already-paid REST read on a uPnl refresh
-     *  instead of throwing it away — bounding uPnl staleness to the 60s interval
-     *  rather than "until the next trade/funding event".
-     *
-     *  Strictly bounded — this is NOT applySnapshot:
-     *   - only mutates positions present in BOTH the store and the fresh REST
-     *     list with the SAME symbol AND side (structural changes are the
-     *     truth-check's job, not this method's);
-     *   - never adds, never removes, never touches balance or orders;
-     *   - so it cannot reintroduce the null≠empty / stale-as-truth collapse
-     *     class (callers only reach here with a non-null REST snapshot anyway —
-     *     buildSnapshot throws UntrustedSnapshotError on a failed fetch). */
-    refreshDerivedMarkFields(restPositions: CcxtPosition[]): void;
-    /** Apply an ACCOUNT_UPDATE event (positions + balance deltas). */
-    applyAccountUpdate(ev: ParsedAccountUpdate): void;
-    /** Apply an ORDER_TRADE_UPDATE event (single order state transition). */
-    applyOrderUpdate(ev: ParsedOrderUpdate): void;
-    /** Clear all state. Used on shutdown/reset. */
-    reset(): void;
-    /** Diff local state vs a fresh REST snapshot. Classifies drifts by severity
-     *  so the parent reconciler can decide: log-only (minor) vs forced resync (major). */
-    diffAgainstSnapshot(rest: RestSnapshot): StateDrift;
-    private diffPositions;
-    private diffBalance;
-    private diffOrders;
-}