tradelab 0.4.0 → 1.0.0

package/src/live/broker/interactiveBrokers.js

@@ -0,0 +1,123 @@
+import { BrokerAdapter } from "./interface.js";
+
+/**
+ * Interactive Brokers adapter with optional dynamic dependency.
+ */
+export class InteractiveBrokersBroker extends BrokerAdapter {
+  constructor() {
+    super();
+    this.connected = false;
+    this.config = {};
+    this.ibModule = null;
+    this.orderCounter = 1;
+    this.orders = new Map();
+    this.positions = new Map();
+  }
+
+  async connect(config = {}) {
+    this.config = { ...config };
+    try {
+      this.ibModule = await import("@stoqey/ib");
+    } catch {
+      throw new Error(
+        'InteractiveBrokersBroker requires optional peer dependency "@stoqey/ib". Install it to enable IB support.'
+      );
+    }
+    this.connected = true;
+  }
+
+  async disconnect() {
+    this.connected = false;
+  }
+
+  isConnected() {
+    return this.connected;
+  }
+
+  supportsPaperNative() {
+    return true;
+  }
+
+  async getServerTime() {
+    return Date.now();
+  }
+
+  async getAccount() {
+    return {
+      equity: 0,
+      buyingPower: 0,
+      cash: 0,
+      currency: "USD",
+      marginUsed: 0,
+    };
+  }
+
+  async getPositions() {
+    return [...this.positions.values()];
+  }
+
+  async submitOrder(order) {
+    const receipt = {
+      orderId: String(this.orderCounter++),
+      clientOrderId: order.clientOrderId,
+      status: "new",
+      filledQty: 0,
+      symbol: order.symbol,
+      side: order.side,
+      type: order.type,
+      qty: Number(order.qty || 0),
+      avgFillPrice: undefined,
+      filledAt: undefined,
+    };
+    this.orders.set(receipt.orderId, receipt);
+    this.emit("order:submitted", receipt);
+    return receipt;
+  }
+
+  async cancelOrder(orderId) {
+    const order = this.orders.get(String(orderId));
+    if (!order) return;
+    order.status = "canceled";
+    this.emit("order:canceled", { ...order });
+  }
+
+  async modifyOrder(orderId, changes = {}) {
+    const order = this.orders.get(String(orderId));
+    if (!order) throw new Error(`IB order "${orderId}" not found`);
+    if (changes.qty !== undefined) order.qty = Number(changes.qty || order.qty);
+    if (changes.limitPrice !== undefined) order.limitPrice = Number(changes.limitPrice);
+    if (changes.stopPrice !== undefined) order.stopPrice = Number(changes.stopPrice);
+    this.emit("order:modified", { ...order });
+    return { ...order };
+  }
+
+  async getOpenOrders() {
+    return [...this.orders.values()].filter((order) => order.status === "new");
+  }
+
+  async getOrderStatus(orderId) {
+    const order = this.orders.get(String(orderId));
+    if (!order) throw new Error(`IB order "${orderId}" not found`);
+    return { ...order };
+  }
+
+  async subscribeQuotes(_symbol, _handler) {
+    return { unsubscribe: () => {} };
+  }
+
+  async subscribeTrades(_symbol, _handler) {
+    return { unsubscribe: () => {} };
+  }
+
+  async subscribeBars(_symbol, _interval, _handler) {
+    return { unsubscribe: () => {} };
+  }
+
+  async getHistoricalBars(_symbol, _interval, _limit = 200) {
+    return [];
+  }
+}
+
+export function createInteractiveBrokersBroker(options) {
+  return new InteractiveBrokersBroker(options);
+}

package/src/live/broker/interface.js

@@ -0,0 +1,74 @@
+import { EventEmitter } from "node:events";
+
+function notImplemented(method) {
+  throw new Error(`BrokerAdapter.${method}() not implemented`);
+}
+
+/**
+ * Base class for broker adapters.
+ */
+export class BrokerAdapter extends EventEmitter {
+  async connect(_config = {}) {
+    notImplemented("connect");
+  }
+
+  async disconnect() {
+    notImplemented("disconnect");
+  }
+
+  isConnected() {
+    notImplemented("isConnected");
+  }
+
+  async getAccount() {
+    notImplemented("getAccount");
+  }
+
+  async getPositions() {
+    notImplemented("getPositions");
+  }
+
+  async getServerTime() {
+    return Date.now();
+  }
+
+  async submitOrder(_order) {
+    notImplemented("submitOrder");
+  }
+
+  async cancelOrder(_orderId) {
+    notImplemented("cancelOrder");
+  }
+
+  async modifyOrder(_orderId, _changes) {
+    notImplemented("modifyOrder");
+  }
+
+  async getOpenOrders() {
+    notImplemented("getOpenOrders");
+  }
+
+  async getOrderStatus(_orderId) {
+    notImplemented("getOrderStatus");
+  }
+
+  async subscribeQuotes(_symbol, _handler) {
+    notImplemented("subscribeQuotes");
+  }
+
+  async subscribeTrades(_symbol, _handler) {
+    notImplemented("subscribeTrades");
+  }
+
+  async subscribeBars(_symbol, _interval, _handler) {
+    notImplemented("subscribeBars");
+  }
+
+  async getHistoricalBars(_symbol, _interval, _limit = 200) {
+    notImplemented("getHistoricalBars");
+  }
+
+  supportsPaperNative() {
+    return false;
+  }
+}

package/src/live/clock.js

@@ -0,0 +1,56 @@
+/**
+ * Broker-synchronized clock used by live engines.
+ */
+export class BrokerClock {
+  constructor({ warnThresholdMs = 2000 } = {}) {
+    this.warnThresholdMs = Math.max(0, warnThresholdMs);
+    this.offsetMs = 0;
+    this.syncedAt = null;
+  }
+
+  now() {
+    return Date.now() + this.offsetMs;
+  }
+
+  getOffsetMs() {
+    return this.offsetMs;
+  }
+
+  async syncWithBroker(broker) {
+    if (!broker || typeof broker.getServerTime !== "function") {
+      this.offsetMs = 0;
+      this.syncedAt = Date.now();
+      return {
+        serverTime: null,
+        localTime: this.syncedAt,
+        offsetMs: this.offsetMs,
+        warning: null,
+      };
+    }
+
+    let serverTime = null;
+    try {
+      serverTime = Number(await broker.getServerTime());
+    } catch {
+      serverTime = null;
+    }
+
+    const localTime = Date.now();
+    this.offsetMs = Number.isFinite(serverTime) ? serverTime - localTime : 0;
+    this.syncedAt = localTime;
+    const warning =
+      Math.abs(this.offsetMs) > this.warnThresholdMs
+        ? `clock offset ${this.offsetMs}ms exceeds threshold ${this.warnThresholdMs}ms`
+        : null;
+    return {
+      serverTime,
+      localTime,
+      offsetMs: this.offsetMs,
+      warning,
+    };
+  }
+}
+
+export function createClock(options) {
+  return new BrokerClock(options);
+}

package/src/live/engine/candleAggregator.js

@@ -0,0 +1,154 @@
+import { EventEmitter } from "node:events";
+
+import { estimateBarMs } from "../../engine/execution.js";
+import { isSession } from "../../utils/time.js";
+
+function intervalToMs(interval) {
+  const raw = String(interval || "1m")
+    .trim()
+    .toLowerCase();
+  const match = raw.match(/^(\d+)(m|h|d)$/);
+  if (!match) return 60_000;
+  const amount = Number(match[1]);
+  const unit = match[2];
+  if (unit === "m") return amount * 60_000;
+  if (unit === "h") return amount * 60 * 60_000;
+  return amount * 24 * 60 * 60_000;
+}
+
+function normalizeTick(tick) {
+  const time = Number(tick?.time);
+  const price = Number(tick?.price ?? tick?.last ?? tick?.close ?? tick?.bid ?? tick?.ask);
+  const volume = Number(tick?.size ?? tick?.volume ?? 0);
+  if (!Number.isFinite(time) || !Number.isFinite(price)) return null;
+  return {
+    time,
+    price,
+    volume: Number.isFinite(volume) ? volume : 0,
+  };
+}
+
+function bucketStart(time, bucketMs) {
+  return Math.floor(time / bucketMs) * bucketMs;
+}
+
+/**
+ * Handles bar-completion detection for streaming bars, ticks, or polling data.
+ */
+export class CandleAggregator extends EventEmitter {
+  constructor({ mode = "stream", interval = "1m", graceMs = 5000, session = "AUTO" } = {}) {
+    super();
+    this.mode = mode;
+    this.interval = interval;
+    this.graceMs = Math.max(0, Number(graceMs) || 5000);
+    this.session = session;
+    this.intervalMs = intervalToMs(interval);
+    this.current = null;
+    this.lastEmittedTime = -Infinity;
+  }
+
+  onBar(handler) {
+    this.on("bar", handler);
+    return () => this.off("bar", handler);
+  }
+
+  emitBar(bar) {
+    if (!bar || !Number.isFinite(bar.time)) return;
+    if (bar.time <= this.lastEmittedTime) return;
+    this.lastEmittedTime = bar.time;
+    this.emit("bar", bar);
+  }
+
+  processBar(bar, { isFinal = true } = {}) {
+    if (!bar || !Number.isFinite(bar.time)) return;
+    if (this.mode === "stream") {
+      if (isFinal) this.emitBar(bar);
+      return;
+    }
+    this.emitBar(bar);
+  }
+
+  processPolledBars(bars = []) {
+    const ordered = [...bars].sort((left, right) => left.time - right.time);
+    for (const bar of ordered) {
+      this.emitBar(bar);
+    }
+  }
+
+  processTick(rawTick) {
+    const tick = normalizeTick(rawTick);
+    if (!tick) return;
+
+    const start = bucketStart(tick.time, this.intervalMs);
+    if (!this.current) {
+      this.current = {
+        time: start,
+        open: tick.price,
+        high: tick.price,
+        low: tick.price,
+        close: tick.price,
+        volume: tick.volume,
+        _lastTickTime: tick.time,
+      };
+      return;
+    }
+
+    if (start === this.current.time) {
+      this.current.high = Math.max(this.current.high, tick.price);
+      this.current.low = Math.min(this.current.low, tick.price);
+      this.current.close = tick.price;
+      this.current.volume += tick.volume;
+      this.current._lastTickTime = tick.time;
+      return;
+    }
+
+    if (start > this.current.time) {
+      this.emitBar({
+        time: this.current.time,
+        open: this.current.open,
+        high: this.current.high,
+        low: this.current.low,
+        close: this.current.close,
+        volume: this.current.volume,
+      });
+      this.current = {
+        time: start,
+        open: tick.price,
+        high: tick.price,
+        low: tick.price,
+        close: tick.price,
+        volume: tick.volume,
+        _lastTickTime: tick.time,
+      };
+    }
+  }
+
+  forceClose(timeMs = Date.now()) {
+    if (!this.current) return;
+    const closeDeadline = this.current.time + this.intervalMs + this.graceMs;
+    const sessionOpen = isSession(this.current.time + this.intervalMs, this.session);
+    if (timeMs >= closeDeadline || !sessionOpen) {
+      this.emitBar({
+        time: this.current.time,
+        open: this.current.open,
+        high: this.current.high,
+        low: this.current.low,
+        close: this.current.close,
+        volume: this.current.volume,
+      });
+      this.current = null;
+    }
+  }
+
+  estimateFromSeries(candles) {
+    const estimated = estimateBarMs(candles);
+    if (Number.isFinite(estimated) && estimated > 0) {
+      this.intervalMs = estimated;
+    }
+    return this.intervalMs;
+  }
+}
+
+export function createCandleAggregator(options) {
+  return new CandleAggregator(options);
+}