@forgecharts/sdk 1.1.23

package/src/tools/barDivergenceCheck.ts

@@ -0,0 +1,305 @@
+/**
+ * First-Divergence Bar Comparison Tool
+ *
+ * Compares OHLCV bars from multiple data sources (provider REST, database,
+ * aggregated from 1m, SDK engine) and reports the **first** mismatch found.
+ *
+ * Usage:
+ *
+ *   import { compareSources, checkAllSources, formatReport } from '@forgecharts/sdk/tools/barDivergenceCheck';
+ *
+ *   const report = compareSources(
+ *     { source: 'provider',   bars: providerBars   },
+ *     { source: 'database',   bars: databaseBars   },
+ *     '1h',
+ *     'BINANCE:BTCUSDT',
+ *     from,
+ *     to,
+ *   );
+ *
+ *   if (report.diverged) console.log(formatReport(report));
+ *
+ * All bar arrays are expected to contain Unix **second** timestamps in the
+ * `time` field (matching the CandleBar.time convention).  Use `from`/`to`
+ * as Unix seconds to scope the comparison window.
+ */
+
+import { getBucketStart } from '@forgecharts/shared';
+
+// ─── Public types ─────────────────────────────────────────────────────────────
+
+/** Identifies which pipeline stage produced a bar array. */
+export type BarSource = 'provider' | 'database' | 'aggregated' | 'sdk';
+
+/** Minimal OHLCV shape accepted by the divergence checker. */
+export interface OhlcvBar {
+  /** Unix seconds (same as CandleBar.time). */
+  time: number;
+  open: number;
+  high: number;
+  low: number;
+  close: number;
+  volume?: number;
+}
+
+/** A labelled set of bars from one pipeline source. */
+export interface SourceBars {
+  source: BarSource;
+  bars: readonly OhlcvBar[];
+}
+
+/** A single field-level difference between two bars at the same timestamp. */
+export interface FieldDiff {
+  field: 'open' | 'high' | 'low' | 'close' | 'volume';
+  valueA: number;
+  valueB: number;
+  /** valueA − valueB */
+  delta: number;
+}
+
+/** Full description of a single mismatched candle. */
+export interface BarMismatch {
+  /** Unix seconds — the candle open time where divergence was first detected. */
+  time: number;
+  /** Canonical candle-open boundary in milliseconds for the given timeframe. */
+  bucketStartMs: number;
+  sourceA: BarSource;
+  sourceB: BarSource;
+  /** OHLCV field deltas — empty when the only problem is a missing bar. */
+  differences: FieldDiff[];
+  /**
+   * True when the two bars carry the same `time` but their canonical
+   * `bucketStart` values differ — indicates a misaligned timestamp on one side.
+   */
+  bucketMismatch: boolean;
+  /** Human-readable diagnostic notes. */
+  notes: string[];
+}
+
+/** Summary of a pairwise source comparison. */
+export interface DivergenceReport {
+  symbol: string;
+  timeframe: string;
+  /** Unix seconds — inclusive window start. */
+  from: number;
+  /** Unix seconds — inclusive window end. */
+  to: number;
+  diverged: boolean;
+  /** The first mismatch found, or null when the sources are identical. */
+  firstMismatch: BarMismatch | null;
+  totalMismatches: number;
+  /** Number of bars from source A inside [from, to]. */
+  sourceACount: number;
+  /** Number of bars from source B inside [from, to]. */
+  sourceBCount: number;
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Index bars by their Unix-second open time for O(1) lookup. */
+function indexByTime(bars: readonly OhlcvBar[]): Map<number, OhlcvBar> {
+  const map = new Map<number, OhlcvBar>();
+  for (const bar of bars) {
+    // Last-write-wins if the source has duplicate timestamps
+    map.set(bar.time, bar);
+  }
+  return map;
+}
+
+/**
+ * Compare two numeric values with a floating-point epsilon tolerance.
+ * Returns true when they differ by more than the tolerance.
+ */
+function differ(a: number, b: number, eps = 1e-9): boolean {
+  return Math.abs(a - b) > eps;
+}
+
+// ─── Core comparison ──────────────────────────────────────────────────────────
+
+/**
+ * Compare all timestamps from both sources inside [from, to] and return the
+ * first mismatch found, scanning oldest-first.
+ *
+ * Mismatch criteria (any one triggers a report):
+ *   1. Bar present in one source but absent in the other.
+ *   2. OHLCV field values differ by more than floating-point epsilon.
+ *   3. Canonical `getBucketStart` for the bar's time differs between sources
+ *      (indicates one source has a misaligned timestamp).
+ *
+ * @param a          Source A bars.
+ * @param b          Source B bars.
+ * @param timeframe  Canonical timeframe label (e.g. `'1h'`, `'1w'`).
+ * @param symbol     Symbol string — stored in the report for identification.
+ * @param from       Window start, Unix seconds (inclusive).
+ * @param to         Window end, Unix seconds (inclusive).
+ */
+export function compareSources(
+  a: SourceBars,
+  b: SourceBars,
+  timeframe: string,
+  symbol: string,
+  from: number,
+  to: number,
+): DivergenceReport {
+  const aIndex = indexByTime(a.bars);
+  const bIndex = indexByTime(b.bars);
+
+  // All timestamps seen in either source, filtered to the requested window
+  const allTimes = new Set([...aIndex.keys(), ...bIndex.keys()]);
+  const sortedTimes = Array.from(allTimes)
+    .filter(t => t >= from && t <= to)
+    .sort((x, y) => x - y);
+
+  let totalMismatches = 0;
+  let firstMismatch: BarMismatch | null = null;
+
+  const countA = a.bars.filter(bar => bar.time >= from && bar.time <= to).length;
+  const countB = b.bars.filter(bar => bar.time >= from && bar.time <= to).length;
+
+  for (const time of sortedTimes) {
+    const barA = aIndex.get(time);
+    const barB = bIndex.get(time);
+
+    // ── Missing bar ────────────────────────────────────────────────────────
+    if (!barA || !barB) {
+      totalMismatches++;
+      if (!firstMismatch) {
+        const notes: string[] = [];
+        if (!barA) notes.push(`${a.source} is missing bar at time=${time}`);
+        if (!barB) notes.push(`${b.source} is missing bar at time=${time}`);
+        firstMismatch = {
+          time,
+          bucketStartMs: getBucketStart(time * 1000, timeframe),
+          sourceA: a.source,
+          sourceB: b.source,
+          differences: [],
+          bucketMismatch: false,
+          notes,
+        };
+      }
+      continue;
+    }
+
+    // ── OHLCV field comparison ─────────────────────────────────────────────
+    const diffs: FieldDiff[] = [];
+    const OHLCV_FIELDS: Array<'open' | 'high' | 'low' | 'close' | 'volume'> = [
+      'open', 'high', 'low', 'close', 'volume',
+    ];
+    for (const field of OHLCV_FIELDS) {
+      const vA = barA[field] ?? 0;
+      const vB = barB[field] ?? 0;
+      if (differ(vA, vB)) {
+        diffs.push({ field, valueA: vA, valueB: vB, delta: vA - vB });
+      }
+    }
+
+    // ── Bucket alignment comparison ────────────────────────────────────────
+    const bucketA = getBucketStart(barA.time * 1000, timeframe);
+    const bucketB = getBucketStart(barB.time * 1000, timeframe);
+    const bucketMismatch = bucketA !== bucketB;
+
+    const notes: string[] = [];
+    if (bucketMismatch) {
+      notes.push(
+        `bucket start mismatch: ${a.source}=${bucketA}ms vs ${b.source}=${bucketB}ms ` +
+        `(delta=${bucketA - bucketB} ms)`,
+      );
+    }
+    for (const diff of diffs) {
+      notes.push(
+        `${diff.field}: ${a.source}=${diff.valueA} vs ${b.source}=${diff.valueB} ` +
+        `(delta=${diff.delta.toPrecision(6)})`,
+      );
+    }
+
+    if (diffs.length > 0 || bucketMismatch) {
+      totalMismatches++;
+      if (!firstMismatch) {
+        firstMismatch = {
+          time,
+          bucketStartMs: bucketA,
+          sourceA: a.source,
+          sourceB: b.source,
+          differences: diffs,
+          bucketMismatch,
+          notes,
+        };
+      }
+    }
+  }
+
+  return {
+    symbol,
+    timeframe,
+    from,
+    to,
+    diverged: totalMismatches > 0,
+    firstMismatch,
+    totalMismatches,
+    sourceACount: countA,
+    sourceBCount: countB,
+  };
+}
+
+/**
+ * Run all pairwise comparisons across every combination of the provided sources.
+ *
+ * For N sources this produces N*(N-1)/2 reports.  Use `formatReport` to render
+ * each one for console output.
+ */
+export function checkAllSources(
+  sources: SourceBars[],
+  symbol: string,
+  timeframe: string,
+  from: number,
+  to: number,
+): DivergenceReport[] {
+  const reports: DivergenceReport[] = [];
+  for (let i = 0; i < sources.length; i++) {
+    for (let j = i + 1; j < sources.length; j++) {
+      reports.push(compareSources(sources[i]!, sources[j]!, timeframe, symbol, from, to));
+    }
+  }
+  return reports;
+}
+
+// ─── Formatter ───────────────────────────────────────────────────────────────
+
+/**
+ * Render a `DivergenceReport` as a multi-line human-readable string suitable
+ * for console output or log files.
+ *
+ * @example
+ * const report = compareSources(a, b, '1h', 'BINANCE:BTCUSDT', from, to);
+ * console.log(formatReport(report));
+ */
+export function formatReport(report: DivergenceReport): string {
+  const lines: string[] = [];
+
+  const status = report.diverged
+    ? `DIVERGED (${report.totalMismatches} mismatch${report.totalMismatches === 1 ? '' : 'es'})`
+    : 'IDENTICAL';
+
+  lines.push('─'.repeat(72));
+  lines.push(`Bar Divergence Report — ${status}`);
+  lines.push(`  Symbol    : ${report.symbol}`);
+  lines.push(`  Timeframe : ${report.timeframe}`);
+  lines.push(`  Window    : ${report.from} → ${report.to} (Unix seconds)`);
+  lines.push(`  Bars      : sourceA=${report.sourceACount}  sourceB=${report.sourceBCount}`);
+
+  if (report.firstMismatch) {
+    const m = report.firstMismatch;
+    lines.push('');
+    lines.push(`  First mismatch at time=${m.time} (bucketStart=${m.bucketStartMs} ms)`);
+    lines.push(`  Sources  : ${m.sourceA}  vs  ${m.sourceB}`);
+    if (m.bucketMismatch) {
+      lines.push(`  ✗ Bucket alignment differs`);
+    }
+    for (const note of m.notes) {
+      lines.push(`  · ${note}`);
+    }
+  }
+
+  lines.push('─'.repeat(72));
+  return lines.join('\n');
+}

package/src/trading/TradingOverlayStore.ts

@@ -0,0 +1,161 @@
+/**
+ * TradingOverlayStore
+ *
+ * Shared, mode-agnostic store for trade overlay state.
+ * Used by both unmanaged mode (externally supplied data) and managed mode
+ * (internally generated data from the managed trading service).
+ *
+ * Supports:
+ *   - Full replace  (setOrders / setPositions)
+ *   - Incremental   (upsertOrder / upsertPosition / pushExecution)
+ *   - Remove by id  (removeOrder / removePosition)
+ *
+ * Subscribers are notified via callbacks registered with onChange().
+ * The store is intentionally free of React/DOM dependencies so it can be
+ * consumed from any rendering layer (canvas, React, etc.).
+ *
+ * @example
+ * ```ts
+ * const store = new TradingOverlayStore();
+ *
+ * // Subscribe to changes (e.g. trigger a canvas repaint)
+ * store.onChange(() => chart.markDirty());
+ *
+ * // Feed data
+ * store.setOrders([...]);
+ * store.upsertOrder({ id: 'o1', role: 'entry', side: 'buy', ... });
+ * store.removeOrder('o1');
+ * ```
+ */
+
+import type { ChartOrder, ChartPosition, ExecutionFill } from './tradingTypes';
+
+type ChangeListener = () => void;
+
+export class TradingOverlayStore {
+  private _orders    = new Map<string, ChartOrder>();
+  private _positions = new Map<string, ChartPosition>();
+  private _fills:      ExecutionFill[] = [];
+
+  private _listeners: ChangeListener[] = [];
+
+  // ── Change subscription ──────────────────────────────────────────────────────
+
+  /**
+   * Register a callback that fires whenever any state changes.
+   * Returns an unsubscribe function.
+   */
+  onChange(listener: ChangeListener): () => void {
+    this._listeners.push(listener);
+    return () => {
+      this._listeners = this._listeners.filter(l => l !== listener);
+    };
+  }
+
+  private _notify(): void {
+    for (const l of this._listeners) l();
+  }
+
+  // ── Orders ───────────────────────────────────────────────────────────────────
+
+  /** Replace the entire order set. */
+  setOrders(orders: ChartOrder[]): void {
+    this._orders.clear();
+    for (const o of orders) this._orders.set(o.id, o);
+    this._notify();
+  }
+
+  /**
+   * Insert or replace a single order.
+   * Matching is done by `order.id`.
+   */
+  upsertOrder(order: ChartOrder): void {
+    this._orders.set(order.id, order);
+    this._notify();
+  }
+
+  /** Remove an order by id. Silent no-op if not found. */
+  removeOrder(orderId: string): void {
+    if (this._orders.delete(orderId)) this._notify();
+  }
+
+  /** Returns a snapshot of all orders as an array (insertion order). */
+  getOrders(): ChartOrder[] {
+    return Array.from(this._orders.values());
+  }
+
+  /** Returns orders that share the given `groupId`. */
+  getOrdersByGroup(groupId: string): ChartOrder[] {
+    return this.getOrders().filter(o => o.groupId === groupId);
+  }
+
+  // ── Positions ────────────────────────────────────────────────────────────────
+
+  /** Replace the entire position set. */
+  setPositions(positions: ChartPosition[]): void {
+    this._positions.clear();
+    for (const p of positions) this._positions.set(p.id, p);
+    this._notify();
+  }
+
+  /**
+   * Insert or replace a single position.
+   * Matching is done by `position.id`.
+   */
+  upsertPosition(position: ChartPosition): void {
+    this._positions.set(position.id, position);
+    this._notify();
+  }
+
+  /** Remove a position by id. Silent no-op if not found. */
+  removePosition(positionId: string): void {
+    if (this._positions.delete(positionId)) this._notify();
+  }
+
+  /** Returns a snapshot of all positions as an array (insertion order). */
+  getPositions(): ChartPosition[] {
+    return Array.from(this._positions.values());
+  }
+
+  // ── Fills ────────────────────────────────────────────────────────────────────
+
+  /**
+   * Append an execution fill to the fill log.
+   * Fills are append-only — they are never updated or removed.
+   */
+  pushExecution(fill: ExecutionFill): void {
+    this._fills.push(fill);
+    this._notify();
+  }
+
+  /** Returns all fills in insertion (chronological) order. */
+  getFills(): readonly ExecutionFill[] {
+    return this._fills;
+  }
+
+  /** Returns fills associated with a specific order id. */
+  getFillsByOrder(orderId: string): ExecutionFill[] {
+    return this._fills.filter(f => f.orderId === orderId);
+  }
+
+  // ── Bulk clear ───────────────────────────────────────────────────────────────
+
+  /** Wipes all overlay state (orders, positions, fills). */
+  clear(): void {
+    this._orders.clear();
+    this._positions.clear();
+    this._fills = [];
+    this._notify();
+  }
+
+  // ── Snapshot ─────────────────────────────────────────────────────────────────
+
+  /** Returns the full overlay state as a plain object — useful for debug / serialisation. */
+  snapshot(): { orders: ChartOrder[]; positions: ChartPosition[]; fills: readonly ExecutionFill[] } {
+    return {
+      orders:    this.getOrders(),
+      positions: this.getPositions(),
+      fills:     this.getFills(),
+    };
+  }
+}

package/src/trading/UnmanagedIngestion.ts

@@ -0,0 +1,156 @@
+/**
+ * UnmanagedIngestion
+ *
+ * External candle data ingestion for unmanaged mode.
+ *
+ * In unmanaged mode the client owns their data pipeline. They pass
+ * normalised candle data to us; this layer validates the license gate,
+ * delegates to the existing CandleEngine for bucket management, and
+ * notifies callers via callbacks mirroring the CandleEngine contract.
+ *
+ * Critical constraint: the default RapidAPI-backed datafeed is completely
+ * untouched. UnmanagedIngestion is an additive, opt-in path.
+ *
+ * Candle rules (matches CandleEngine behaviour):
+ *   same timeMs   → update current candle
+ *   newer timeMs  → append / new bucket
+ *   older timeMs  → silently ignored (logged in debug mode)
+ *
+ * @example
+ * ```ts
+ * const ingestion = new UnmanagedIngestion('1m', {
+ *   onBarUpdated: (bar) => series.update(bar),
+ *   onResync:     (bars) => series.setData(bars),
+ * });
+ *
+ * // Feed a full history snapshot first
+ * ingestion.setHistory(historicalBars);
+ *
+ * // Then stream live ticks
+ * ingestion.pushCandle(latestBar);
+ * ```
+ */
+
+import { CandleEngine } from '../engine/CandleEngine';
+import type { CandleBar, UpdateResult, GapInfo } from '../engine/CandleEngine';
+import { isUnmanagedMode } from '../licensing/ChartRuntimeResolver';
+import type { CandleInput } from './tradingTypes';
+import type { Timeframe } from '@forgecharts/types';
+
+export interface UnmanagedIngestionOptions {
+  /** Enable debug logging on the underlying CandleEngine. */
+  debug?: boolean;
+
+  /**
+   * Fired after every bar mutation (update or append from a live push).
+   * Corresponds to CandleEngine.onBarUpdated.
+   */
+  onBarUpdated?: (bar: CandleBar, result: UpdateResult) => void;
+
+  /**
+   * Fired when the full bar array changes (after setHistory or gap backfill).
+   * The chart adapter should call `series.setData(bars)`.
+   */
+  onResync?: (bars: readonly CandleBar[]) => void;
+
+  /** Fired when a candle bucket closes. */
+  onBarClosed?: (bar: CandleBar) => void;
+
+  /** Fired when the engine detects skipped buckets in the live stream. */
+  onGapDetected?: (info: GapInfo) => void;
+}
+
+export class UnmanagedIngestion {
+  private readonly _engine: CandleEngine;
+  private readonly _opts: UnmanagedIngestionOptions;
+  private _timeframe: Timeframe;
+
+  constructor(timeframe: Timeframe, opts: UnmanagedIngestionOptions = {}) {
+    this._opts      = opts;
+    this._timeframe = timeframe;
+    this._engine    = new CandleEngine({
+      ...(opts.debug         !== undefined ? { debug:         opts.debug         } : {}),
+      ...(opts.onBarUpdated  !== undefined ? { onBarUpdated:  opts.onBarUpdated  } : {}),
+      ...(opts.onBarClosed   !== undefined ? { onBarClosed:   opts.onBarClosed   } : {}),
+      ...(opts.onGapDetected !== undefined ? { onGapDetected: opts.onGapDetected } : {}),
+      ...(opts.onResync      !== undefined ? { onResync:      opts.onResync      } : {}),
+    });
+    // Prime the engine so it knows its timeframe before any data arrives
+    this._engine.initialize([], timeframe);
+  }
+
+  // ── Guard ────────────────────────────────────────────────────────────────────
+
+  private _assertUnmanaged(): void {
+    if (!isUnmanagedMode()) {
+      throw new Error(
+        '[ForgeCharts] External data ingestion is only available in unmanaged mode. ' +
+        'The active license is in managed mode.',
+      );
+    }
+  }
+
+  // ── History ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Load a full historical bar snapshot.
+   * Replaces the engine's bar array and triggers `onResync` so the chart
+   * series is fully redrawn.
+   *
+   * Call this once at startup (or on symbol/interval change) before
+   * streaming live candles via `pushCandle`.
+   *
+   * @throws If the active license is not in unmanaged mode.
+   */
+  setHistory(bars: CandleInput[]): void {
+    this._assertUnmanaged();
+
+    // Sort ascending — initialize expects oldest → newest
+    const sorted = [...bars].sort((a, b) => a.time - b.time);
+    this._engine.initialize(sorted, this._timeframe);
+    // CandleEngine.initialize() does not fire onResync — invoke it explicitly
+    this._opts.onResync?.(this._engine.getBars());
+  }
+
+  // ── Live push ────────────────────────────────────────────────────────────────
+
+  /**
+   * Push a single live candle tick.
+   *
+   * Behaviour follows CandleEngine rules:
+   *   - same bucket  → updates existing bar (OHLCV merging)
+   *   - new bucket   → appends a new bar (previous bar is finalised)
+   *   - older bucket → silently ignored; debug-logged when `debug: true`
+   *
+   * @throws If the active license is not in unmanaged mode.
+   */
+  pushCandle(bar: CandleInput): UpdateResult {
+    this._assertUnmanaged();
+    return this._engine.applyLiveUpdate(bar);
+  }
+
+  // ── Accessors ────────────────────────────────────────────────────────────────
+
+  /** Returns the current bar array (chronological, ascending). */
+  getBars(): readonly CandleBar[] {
+    return this._engine.getBars();
+  }
+
+  /** Returns the latest candle, or null if no data has been loaded. */
+  getLatestBar(): CandleBar | null {
+    const bars = this._engine.getBars();
+    return bars.length > 0 ? bars[bars.length - 1]! : null;
+  }
+
+  /** Changes the active timeframe and clears all bar data. */
+  setTimeframe(timeframe: Timeframe): void {
+    this._timeframe = timeframe;
+    // Re-initialise with empty history — caller must follow up with setHistory()
+    this._engine.initialize([], timeframe);
+  }
+
+  /** Clears all bars (e.g. on symbol change before calling setHistory again). */
+  reset(): void {
+    this._engine.reset();
+  }
+}