@forgecharts/sdk 1.1.23

package/src/trading/__tests__/UnmanagedIngestion.test.ts

@@ -0,0 +1,205 @@
+/**
+ * UnmanagedIngestion — unit tests
+ *
+ * Covers:
+ *   - setHistory loads bars in ascending order
+ *   - pushCandle appends a new bar
+ *   - pushCandle updates the current bar when same bucket
+ *   - getLatestBar returns correct data
+ *   - getBars() returns the full bar array
+ *   - setTimeframe clears bars and resets engine
+ *   - reset() wipes all bars
+ *   - Throws when called in managed mode
+ *   - onBarUpdated / onResync callbacks fire correctly
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { LicenseManager } from '../../licensing/LicenseManager';
+import { UnmanagedIngestion } from '../UnmanagedIngestion';
+import type { CandleInput } from '../tradingTypes';
+import type { CandleBar, UpdateResult } from '../../engine/CandleEngine';
+
+// ─── License helpers ──────────────────────────────────────────────────────────
+
+function installUnmanaged() {
+  LicenseManager.getInstance().loadLicense({ licenseKey: 'u', mode: 'unmanaged' });
+}
+
+function installManaged() {
+  LicenseManager.getInstance().loadLicense({ licenseKey: 'm', mode: 'managed' });
+}
+
+function clearLicense() {
+  LicenseManager.getInstance().clear();
+}
+
+// ─── Bar builders ─────────────────────────────────────────────────────────────
+
+// 2024-01-02 00:00:00 UTC in seconds
+const BASE_SEC = 1_704_153_600;
+const MIN      = 60; // seconds per minute
+
+function bar(offsetMinutes: number, close = 100, extra?: Partial<CandleInput>): CandleInput {
+  return {
+    time:  BASE_SEC + offsetMinutes * MIN,
+    open:  100,
+    high:  105,
+    low:   95,
+    close,
+    ...extra,
+  };
+}
+
+// ─── Mode gate ────────────────────────────────────────────────────────────────
+
+describe('UnmanagedIngestion — mode gate', () => {
+  afterEach(clearLicense);
+
+  it('setHistory() throws in managed mode', () => {
+    installManaged();
+    const ing = new UnmanagedIngestion('1m');
+    expect(() => ing.setHistory([bar(0)])).toThrow(/unmanaged/i);
+  });
+
+  it('pushCandle() throws in managed mode', () => {
+    installManaged();
+    const ing = new UnmanagedIngestion('1m');
+    expect(() => ing.pushCandle(bar(0))).toThrow(/unmanaged/i);
+  });
+
+  it('setHistory() works when no license is installed (defaults to unmanaged)', () => {
+    clearLicense();
+    const ing = new UnmanagedIngestion('1m');
+    expect(() => ing.setHistory([bar(0)])).not.toThrow();
+  });
+
+  it('pushCandle() works when no license is installed', () => {
+    clearLicense();
+    const ing = new UnmanagedIngestion('1m');
+    expect(() => ing.pushCandle(bar(0))).not.toThrow();
+  });
+});
+
+// ─── setHistory ───────────────────────────────────────────────────────────────
+
+describe('UnmanagedIngestion — setHistory', () => {
+  beforeEach(installUnmanaged);
+  afterEach(clearLicense);
+
+  it('loads bars and getBars() returns them', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.setHistory([bar(0), bar(1), bar(2)]);
+    expect(ing.getBars()).toHaveLength(3);
+  });
+
+  it('sorts bars ascending by time (even if fed out of order)', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.setHistory([bar(2), bar(0), bar(1)]);
+    const times = ing.getBars().map(b => b.time);
+    expect(times).toEqual([...times].sort((a, b) => a - b));
+  });
+
+  it('replaces previous history on second call', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.setHistory([bar(0), bar(1), bar(2)]);
+    ing.setHistory([bar(5), bar(6)]);
+    expect(ing.getBars()).toHaveLength(2);
+  });
+
+  it('getLatestBar() returns the newest bar after loading', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.setHistory([bar(0, 100), bar(1, 200), bar(2, 300)]);
+    expect(ing.getLatestBar()!.close).toBe(300);
+  });
+
+  it('fires onResync with the loaded bars', () => {
+    const onResync = vi.fn<(bars: readonly CandleBar[]) => void>();
+    const ing = new UnmanagedIngestion('1m', { onResync });
+    ing.setHistory([bar(0), bar(1)]);
+    expect(onResync).toHaveBeenCalledTimes(1);
+    const passed = onResync.mock.calls[0]![0];
+    expect(passed).toHaveLength(2);
+  });
+});
+
+// ─── pushCandle ───────────────────────────────────────────────────────────────
+
+describe('UnmanagedIngestion — pushCandle', () => {
+  beforeEach(installUnmanaged);
+  afterEach(clearLicense);
+
+  it('appends a new bar when pushing beyond current candle', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.setHistory([bar(0), bar(1)]);
+    const result = ing.pushCandle(bar(2));
+    expect(result.type).toBe('append');
+    expect(ing.getBars()).toHaveLength(3);
+  });
+
+  it('updates the current bar when pushing same bucket', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.setHistory([bar(0)]);
+    ing.pushCandle(bar(0, 110));  // same timestamp, new close
+    expect(ing.getBars()).toHaveLength(1);
+    expect(ing.getLatestBar()!.close).toBe(110);
+  });
+
+  it('high is never lowered within a candle', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.pushCandle(bar(0, 100, { high: 120 }));
+    ing.pushCandle(bar(0, 90,  { high: 80  }));  // high 80 < 120
+    expect(ing.getLatestBar()!.high).toBe(120);
+  });
+
+  it('low is never raised within a candle', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.pushCandle(bar(0, 100, { low: 80 }));
+    ing.pushCandle(bar(0, 95,  { low: 90 }));  // low 90 > 80
+    expect(ing.getLatestBar()!.low).toBe(80);
+  });
+
+  it('fires onBarUpdated for every push', () => {
+    const onBarUpdated = vi.fn<(bar: CandleBar, result: UpdateResult) => void>();
+    const ing = new UnmanagedIngestion('1m', { onBarUpdated });
+    ing.pushCandle(bar(0));
+    ing.pushCandle(bar(0, 110));
+    ing.pushCandle(bar(1));
+    expect(onBarUpdated).toHaveBeenCalledTimes(3);
+  });
+
+  it('getLatestBar() returns null before any data', () => {
+    const ing = new UnmanagedIngestion('1m');
+    expect(ing.getLatestBar()).toBeNull();
+  });
+});
+
+// ─── setTimeframe & reset ─────────────────────────────────────────────────────
+
+describe('UnmanagedIngestion — setTimeframe and reset', () => {
+  beforeEach(installUnmanaged);
+  afterEach(clearLicense);
+
+  it('setTimeframe clears all existing bars', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.setHistory([bar(0), bar(1), bar(2)]);
+    ing.setTimeframe('5m');
+    expect(ing.getBars()).toHaveLength(0);
+  });
+
+  it('reset() clears all bars', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.setHistory([bar(0), bar(1)]);
+    ing.reset();
+    expect(ing.getBars()).toHaveLength(0);
+    expect(ing.getLatestBar()).toBeNull();
+  });
+
+  it('new history can be loaded after setTimeframe', () => {
+    const ing = new UnmanagedIngestion('1m');
+    ing.setHistory([bar(0), bar(1)]);
+    ing.setTimeframe('5m');
+    // 5-minute bars (offset in multiples of 5)
+    ing.setHistory([bar(0), bar(5)]);
+    expect(ing.getBars()).toHaveLength(2);
+  });
+});

package/src/trading/managed/ManagedTradingController.ts

@@ -0,0 +1,292 @@
+/**
+ * ManagedTradingController
+ *
+ * The single managed-mode entry point for order routing.
+ *
+ * Responsibilities:
+ *  1. Enforce license/capability gates before any action.
+ *  2. Delegate execution to the registered IExecutionProvider.
+ *  3. Write results (orders, fills, positions) into the shared TradingOverlayStore
+ *     so managed and unmanaged modes share one visual layer.
+ *
+ * STUB STATUS
+ * ──────────────────────────────────────────────────────────────────────────────
+ * All execution methods are implemented as stubs that:
+ *   a) enforce license gates (will throw today if called without managed mode)
+ *   b) throw NotImplementedError when no provider is registered
+ *   c) are annotated with TODO markers for the implementation phase
+ *
+ * To implement a real provider, create a class implementing IExecutionProvider
+ * and call:
+ *   controller.registerProvider(new MyBrokerProvider(...));
+ *
+ * The controller will then delegate to it automatically.
+ * ──────────────────────────────────────────────────────────────────────────────
+ */
+
+import type { TradingOverlayStore } from '../TradingOverlayStore';
+import type { ChartOrder, ExecutionFill } from '../tradingTypes';
+import type {
+  IExecutionProvider,
+  PlaceOrderInput,
+  ModifyOrderInput,
+  PlaceBracketOrderInput,
+  OrderAck,
+  BracketOrderAck,
+} from './managedTypes';
+import {
+  assertCanPlaceOrders,
+  assertCanUseBrackets,
+  assertCanUseManagedTrading,
+} from './managedCapabilities';
+
+// ── Internal helpers ──────────────────────────────────────────────────────────
+
+function notImplemented(method: string): never {
+  throw new Error(
+    `[ForgeCharts:ManagedTrading] ${method} — no execution provider is registered. ` +
+    'Call controller.registerProvider(provider) before using managed trading methods.',
+  );
+}
+
+function makeId(): string {
+  return `order_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// ── Controller ────────────────────────────────────────────────────────────────
+
+export class ManagedTradingController {
+
+  private _provider: IExecutionProvider | null = null;
+  private readonly _store: TradingOverlayStore;
+
+  constructor(store: TradingOverlayStore) {
+    this._store = store;
+  }
+
+  // ── Provider registration ─────────────────────────────────────────────────
+
+  /**
+   * Register the execution provider that will handle order routing.
+   *
+   * Call this before any order placement methods.  Only one provider may be
+   * active at a time — calling this again replaces the previous provider.
+   *
+   * @example
+   * ```ts
+   * import { RithmicProvider } from '@forgecharts/rithmic';
+   * controller.registerProvider(new RithmicProvider(credentials));
+   * ```
+   */
+  registerProvider(provider: IExecutionProvider): void {
+    assertCanUseManagedTrading();
+    this._provider = provider;
+  }
+
+  /** Returns the id of the currently registered provider, or null if none. */
+  getProviderId(): string | null {
+    return this._provider?.providerId ?? null;
+  }
+
+  /** True when a provider is registered and managed trading is licensed. */
+  isReady(): boolean {
+    return this._provider !== null;
+  }
+
+  // ── Order placement ───────────────────────────────────────────────────────
+
+  /**
+   * Place a single order via the registered execution provider.
+   *
+   * On success:
+   *   - Upserts a ChartOrder into the overlay store (status: 'pending' → 'open').
+   *   - Returns the provider acknowledgement.
+   *
+   * @throws If not in managed mode, orderEntry feature is off, or no provider.
+   *
+   * TODO: After provider.placeOrder resolves, subscribe to order status updates
+   *       (provider event stream) and call _store.upsertOrder() as status changes.
+   */
+  async placeOrder(input: PlaceOrderInput): Promise<OrderAck> {
+    assertCanPlaceOrders();
+    if (!this._provider) notImplemented('placeOrder');
+
+    // Create an optimistic overlay entry immediately
+    const clientId = makeId();
+    const overlayOrder: ChartOrder = {
+      id:        clientId,
+      role:      input.type === 'stop_market' || input.type === 'stop_limit' ? 'stop' : 'entry',
+      side:      input.side,
+      status:    'pending',
+      price:     input.limitPrice ?? input.stopPrice ?? 0,
+      qty:       input.qty,
+      timestamp: Date.now(),
+      ...(input.groupId !== undefined ? { groupId: input.groupId } : {}),
+      ...(input.label   !== undefined ? { label:   input.label   } : {}),
+      ...(input.meta    !== undefined ? { meta:    input.meta    } : {}),
+    };
+    this._store.upsertOrder(overlayOrder);
+
+    try {
+      // TODO: provider.placeOrder should also start streaming status updates
+      const ack = await this._provider.placeOrder(input);
+
+      // Update overlay with provider-assigned id
+      this._store.upsertOrder({ ...overlayOrder, id: ack.orderId, status: 'open' });
+      // Remove the optimistic entry now the real id is known
+      if (ack.orderId !== clientId) this._store.removeOrder(clientId);
+
+      return ack;
+    } catch (err) {
+      // Roll back optimistic entry on placement failure
+      this._store.upsertOrder({ ...overlayOrder, status: 'rejected' });
+      throw err;
+    }
+  }
+
+  /**
+   * Cancel a working order by its provider-assigned id.
+   *
+   * On success:
+   *   - Updates the order status in the overlay store to 'cancelled'.
+   *
+   * @throws If not in managed mode, orderEntry feature is off, or no provider.
+   *
+   * TODO: Remove the overlay entry after a configurable delay (so the line
+   *       visually fades out rather than disappearing instantly).
+   */
+  async cancelOrder(orderId: string): Promise<void> {
+    assertCanPlaceOrders();
+    if (!this._provider) notImplemented('cancelOrder');
+
+    await this._provider.cancelOrder(orderId);
+
+    // Reflect cancellation in overlay
+    const existing = this._store.getOrders().find(o => o.id === orderId);
+    if (existing) {
+      this._store.upsertOrder({ ...existing, status: 'cancelled' });
+    }
+  }
+
+  /**
+   * Modify a working order in place.
+   *
+   * On success:
+   *   - Updates the ChartOrder price/qty in the overlay store.
+   *
+   * @throws If not in managed mode, orderEntry feature is off, or no provider.
+   *
+   * TODO: Validate that the modified price is within instrument tick constraints
+   *       before forwarding to the provider.
+   */
+  async modifyOrder(orderId: string, updates: ModifyOrderInput): Promise<OrderAck> {
+    assertCanPlaceOrders();
+    if (!this._provider) notImplemented('modifyOrder');
+
+    const ack = await this._provider.modifyOrder(orderId, updates);
+
+    // Reflect modifications in overlay
+    const existing = this._store.getOrders().find(o => o.id === orderId);
+    if (existing) {
+      this._store.upsertOrder({
+        ...existing,
+        ...(updates.limitPrice !== undefined ? { price: updates.limitPrice } : {}),
+        ...(updates.qty        !== undefined ? { qty:   updates.qty        } : {}),
+        ...(updates.label      !== undefined ? { label: updates.label      } : {}),
+      });
+    }
+
+    return ack;
+  }
+
+  /**
+   * Place a bracket order: entry + stop-loss + optional take-profit.
+   *
+   * On success:
+   *   - Upserts all bracket legs as ChartOrders sharing the same groupId.
+   *   - Returns acknowledgements for each leg.
+   *
+   * @throws If not in managed mode, bracketOrders feature is off, or no provider.
+   *
+   * TODO: Expose drag handles for each bracket leg in the chart overlay so
+   *       users can adjust prices before confirming.
+   */
+  async placeBracketOrder(input: PlaceBracketOrderInput): Promise<BracketOrderAck> {
+    assertCanUseBrackets();
+    if (!this._provider) notImplemented('placeBracketOrder');
+
+    const groupId = input.entry.groupId ?? makeId();
+
+    const ack = await this._provider.placeBracketOrder({
+      ...input,
+      entry: { ...input.entry, groupId },
+    });
+
+    // Upsert all bracket legs into the overlay store
+    this._store.upsertOrder({
+      id:       ack.entry.orderId,
+      role:     'entry',
+      side:     input.entry.side,
+      status:   'open',
+      price:    input.entry.limitPrice ?? input.entry.stopPrice ?? 0,
+      qty:      input.entry.qty,
+      groupId,
+      label:    input.entry.label ?? 'Entry',
+      timestamp: ack.entry.timestamp,
+    });
+
+    this._store.upsertOrder({
+      id:       ack.stopLoss.orderId,
+      role:     'stop_loss',
+      side:     input.entry.side === 'buy' ? 'sell' : 'buy',
+      status:   'open',
+      price:    input.stopLossPrice,
+      qty:      input.entry.qty,
+      groupId,
+      label:    'Stop Loss',
+      timestamp: ack.stopLoss.timestamp,
+    });
+
+    if (ack.takeProfit && input.takeProfitPrice !== undefined) {
+      this._store.upsertOrder({
+        id:       ack.takeProfit.orderId,
+        role:     'take_profit',
+        side:     input.entry.side === 'buy' ? 'sell' : 'buy',
+        status:   'open',
+        price:    input.takeProfitPrice,
+        qty:      input.entry.qty,
+        groupId,
+        label:    'Take Profit',
+        timestamp: ack.takeProfit.timestamp,
+      });
+    }
+
+    return ack;
+  }
+
+  // ── Fill reporting ─────────────────────────────────────────────────────────
+
+  /**
+   * Report an execution fill received from the provider's event stream.
+   *
+   * Writes the fill into the overlay store and updates the parent order status.
+   * Called by the provider adapter whenever a fill notification arrives.
+   *
+   * TODO: Also update the related ChartPosition (create new or update qty/avgPrice).
+   */
+  reportFill(fill: ExecutionFill): void {
+    assertCanUseManagedTrading();
+    this._store.pushExecution(fill);
+
+    // Update parent order status if fill is total
+    if (fill.orderId) {
+      const order = this._store.getOrders().find(o => o.id === fill.orderId);
+      if (order) {
+        // TODO: track partially-filled qty; use 'partial' when qty > fill.qty
+        this._store.upsertOrder({ ...order, status: 'filled' });
+      }
+    }
+
+    // TODO: upsert ChartPosition based on fill side/qty/price
+  }
+}

package/src/trading/managed/managedCapabilities.ts

@@ -0,0 +1,98 @@
+/**
+ * managedCapabilities.ts
+ *
+ * Feature-gate helpers specific to managed trading.
+ * Thin wrappers around ChartRuntimeResolver that produce clear, actionable
+ * error messages when a managed method is called without a suitable license.
+ *
+ * Usage (inside a managed trading method):
+ *
+ *   assertManagedMode();              // throws if not in managed mode
+ *   assertCanPlaceOrders();           // throws if orderEntry flag is off
+ *   assertCanUseBrackets();           // throws if bracketOrders flag is off
+ *   assertCanUseDraggableOrders();    // throws if draggableOrders flag is off
+ */
+
+import { ChartRuntimeResolver } from '../../licensing/ChartRuntimeResolver';
+
+const resolver = () => ChartRuntimeResolver.getInstance();
+
+// ── Guard helpers (throw on failure) ─────────────────────────────────────────
+
+/**
+ * Asserts that the active license is in managed mode.
+ * @throws {Error} with a clear message if mode is unmanaged.
+ */
+export function assertManagedMode(): void {
+  if (!resolver().isManagedMode()) {
+    throw new Error(
+      '[ForgeCharts] This feature requires a managed-mode license. ' +
+      'The current license is in unmanaged mode (or no license is installed). ' +
+      'Install a managed license via LicenseManager.validateLicense().',
+    );
+  }
+}
+
+/**
+ * Asserts that the license permits order placement (orderEntry feature).
+ * Implicitly checks managed mode first.
+ */
+export function assertCanPlaceOrders(): void {
+  assertManagedMode();
+  if (!resolver().canUseOrderEntry()) {
+    throw new Error(
+      '[ForgeCharts] Order entry is not enabled on the active license. ' +
+      'Contact your license provider to enable the orderEntry feature.',
+    );
+  }
+}
+
+/**
+ * Asserts that the license permits bracket / OCO orders.
+ * Implicitly checks managed mode and order entry first.
+ */
+export function assertCanUseBrackets(): void {
+  assertCanPlaceOrders();
+  if (!resolver().canUseBracketOrders()) {
+    throw new Error(
+      '[ForgeCharts] Bracket orders are not enabled on the active license. ' +
+      'Contact your license provider to enable the bracketOrders feature.',
+    );
+  }
+}
+
+/**
+ * Asserts that the license permits drag-to-price order placement.
+ * Implicitly checks managed mode and order entry first.
+ */
+export function assertCanUseDraggableOrders(): void {
+  assertCanPlaceOrders();
+  if (!resolver().canUseDraggableOrders()) {
+    throw new Error(
+      '[ForgeCharts] Draggable orders are not enabled on the active license. ' +
+      'Contact your license provider to enable the draggableOrders feature.',
+    );
+  }
+}
+
+/**
+ * Asserts that the license permits the managed trading service hooks.
+ * Implicitly checks managed mode first.
+ */
+export function assertCanUseManagedTrading(): void {
+  assertManagedMode();
+  if (!resolver().canUseManagedTrading()) {
+    throw new Error(
+      '[ForgeCharts] Managed trading is not enabled on the active license. ' +
+      'Contact your license provider to enable the managedTrading feature.',
+    );
+  }
+}
+
+// ── Boolean helpers (for conditional rendering, no throw) ────────────────────
+
+export const isManagedCapable         = (): boolean => resolver().isManagedMode();
+export const canPlaceOrders           = (): boolean => resolver().isManagedMode() && resolver().canUseOrderEntry();
+export const canPlaceBrackets         = (): boolean => canPlaceOrders() && resolver().canUseBracketOrders();
+export const canUseDraggable          = (): boolean => canPlaceOrders() && resolver().canUseDraggableOrders();
+export const canUseManagedTradingHook = (): boolean => resolver().isManagedMode() && resolver().canUseManagedTrading();