@forgecharts/sdk 1.1.23

package/src/licensing/ChartRuntimeResolver.ts

@@ -0,0 +1,380 @@
+/**
+ * ChartRuntimeResolver
+ *
+ * Single source of truth for runtime capability queries.
+ * Mode is always derived from the installed LicenseManager state — it is
+ * never passed in by chart config, ensuring clients cannot bypass the
+ * license-driven mode selection.
+ *
+ * Usage:
+ *   import { ChartRuntimeResolver } from '@forgecharts/sdk';
+ *   const resolver = ChartRuntimeResolver.getInstance();
+ *
+ *   resolver.isManagedMode()           // true when a managed license is active
+ *   resolver.isUnmanagedMode()         // true when no license or unmanaged license
+ *   resolver.canUseOrderEntry()        // built-in order entry UI
+ *   resolver.canUseExternalIngestion() // external data ingestion APIs
+ *   resolver.canRenderOverlays()       // overlay rendering
+ *   resolver.canUseIndicators()        // indicator panel
+ *   resolver.canUseManagedTrading()    // managed broker / execution hooks
+ *   resolver.canUseDraggableOrders()   // drag-to-price order placement
+ *   resolver.canUseBracketOrders()     // bracket / OCO order support
+ *
+ * Capability matrix
+ * ─────────────────────────────────────────────────────
+ * Capability               unmanaged   managed
+ * ─────────────────────────────────────────────────────
+ * externalIngestion          ✓           ✗  (managed feed owns data)
+ * overlays                   ✓           ✓  (both modes render overlays)
+ * indicators                 ✓           ✓
+ * orderEntry                 ✗           ✓  (requires managed license)
+ * managedTrading             ✗           ✓
+ * draggableOrders            ✗           ✓
+ * bracketOrders              ✗           ✓
+ * ─────────────────────────────────────────────────────
+ *
+ * Feature flags in the LicensePayload can further restrict capabilities
+ * within a mode. A managed license with `orderEntry: false` will still
+ * return false from canUseOrderEntry().
+ */
+
+import { LicenseManager } from './LicenseManager';
+import type { LicenseFeatures } from './licenseTypes';
+
+export class ChartRuntimeResolver {
+  private static instance: ChartRuntimeResolver | null = null;
+
+  /** Always read from the singleton LicenseManager — never store a copy. */
+  private get lm(): LicenseManager {
+    return LicenseManager.getInstance();
+  }
+
+  private constructor() {}
+
+  static getInstance(): ChartRuntimeResolver {
+    if (!ChartRuntimeResolver.instance) {
+      ChartRuntimeResolver.instance = new ChartRuntimeResolver();
+    }
+    return ChartRuntimeResolver.instance;
+  }
+
+  // ── Mode checks ─────────────────────────────────────────────────────────────
+
+  /** True when the active license is in managed mode. */
+  isManagedMode(): boolean {
+    return this.lm.getMode() === 'managed';
+  }
+
+  /** True when no license is installed or the license is in unmanaged mode. */
+  isUnmanagedMode(): boolean {
+    return this.lm.getMode() === 'unmanaged';
+  }
+
+  // ── Capability queries ───────────────────────────────────────────────────────
+
+  /**
+   * External data ingestion APIs (e.g. pushing tick data from an external broker).
+   * Available in unmanaged mode only — in managed mode the built-in feed owns data.
+   * Override via `unmanagedIngestion` feature flag on a managed license if needed.
+   */
+  canUseExternalIngestion(): boolean {
+    if (this.isUnmanagedMode()) return true;
+    // A managed license can explicitly opt-in to external ingestion
+    return this.#featureOrDefault('unmanagedIngestion', false);
+  }
+
+  /**
+   * Overlay rendering from external state (price levels, zones, signals).
+   * Enabled in both modes by default; can be restricted via feature flag.
+   */
+  canRenderOverlays(): boolean {
+    return this.#featureOrDefault('overlays', true);
+  }
+
+  /**
+   * Indicator panel / computations.
+   * Enabled in both modes by default; can be restricted via feature flag.
+   */
+  canUseIndicators(): boolean {
+    return this.#featureOrDefault('indicators', true);
+  }
+
+  /**
+   * Built-in order entry UI hooks.
+   * Requires managed mode AND the `orderEntry` feature flag (or no flag restriction).
+   */
+  canUseOrderEntry(): boolean {
+    if (this.isUnmanagedMode()) return false;
+    return this.#featureOrDefault('orderEntry', true);
+  }
+
+  /**
+   * Managed trading service hooks (broker execution, position management).
+   * Requires managed mode AND the `managedTrading` feature flag (or no flag restriction).
+   */
+  canUseManagedTrading(): boolean {
+    if (this.isUnmanagedMode()) return false;
+    return this.#featureOrDefault('managedTrading', true);
+  }
+
+  /**
+   * Drag-to-price order placement.
+   * Requires managed mode AND the `draggableOrders` feature flag (or no flag restriction).
+   */
+  canUseDraggableOrders(): boolean {
+    if (this.isUnmanagedMode()) return false;
+    return this.#featureOrDefault('draggableOrders', true);
+  }
+
+  /**
+   * Bracket / OCO order support.
+   * Requires managed mode AND the `bracketOrders` feature flag (or no flag restriction).
+   */
+  canUseBracketOrders(): boolean {
+    if (this.isUnmanagedMode()) return false;
+    return this.#featureOrDefault('bracketOrders', true);
+  }
+
+  // ── UI render capability checks ──────────────────────────────────────────────
+  // These are component-level gates. They derive from the feature-level checks
+  // above and are the checks that toolbar / panel components should consume.
+
+  /**
+   * Whether to render the order entry tool in the toolbar.
+   * Hidden in unmanaged mode — requires managed license with order entry.
+   */
+  canRenderOrderEntry(): boolean {
+    return this.canUseOrderEntry();
+  }
+
+  /**
+   * Whether to render Buy / Sell action buttons on the chart or toolbar.
+   * Hidden in unmanaged mode — order placement requires managed license.
+   */
+  canRenderBuySellButtons(): boolean {
+    return this.canUseOrderEntry();
+  }
+
+  /**
+   * Whether to render the order ticket panel (entry form / DOM entry).
+   * Requires managed mode with order entry enabled.
+   */
+  canRenderOrderTicket(): boolean {
+    return this.canUseOrderEntry();
+  }
+
+  /**
+   * Whether to render bracket order controls (TP, SL, OCO).
+   * Requires managed mode with order entry AND the bracketOrders feature flag.
+   * If order entry itself is disabled, bracket controls are also hidden.
+   */
+  canRenderBracketControls(): boolean {
+    if (!this.canUseOrderEntry()) return false;
+    return this.canUseBracketOrders();
+  }
+
+  /**
+   * Whether to render order modification controls (drag-to-modify, edit panel).
+   * Requires managed mode with order entry AND the draggableOrders feature flag.
+   * If order entry itself is disabled, modification controls are also hidden.
+   */
+  canRenderOrderModificationControls(): boolean {
+    if (!this.canUseOrderEntry()) return false;
+    return this.canUseDraggableOrders();
+  }
+
+  /**
+   * Whether to render the managed trading control panel as a whole.
+   * Guards the container that holds buy/sell, order ticket, bracket controls, etc.
+   */
+  canRenderManagedTradingControls(): boolean {
+    return this.canUseManagedTrading();
+  }
+
+  /**
+   * True when the chart is in external-overlay-only (unmanaged) mode.
+   * Drives rendering of the external data overlay panel while suppressing
+   * all order entry UI elements.
+   */
+  canRenderExternalOverlayOnlyMode(): boolean {
+    return this.isUnmanagedMode();
+  }
+
+  /**
+   * Positions are always rendered regardless of license mode.
+   * Data flows from TradingOverlayStore (host-pushed in unmanaged,
+   * ManagedTradingController-driven in managed).
+   */
+  canRenderPositions(): boolean {
+    return true;
+  }
+
+  /**
+   * Execution fills are always rendered regardless of license mode.
+   */
+  canRenderFills(): boolean {
+    return true;
+  }
+
+  /**
+   * Candles are always rendered — unaffected by license mode.
+   * The RapidAPI datafeed remains active in all modes.
+   */
+  canRenderCandles(): boolean {
+    return true;
+  }
+
+  /**
+   * Indicator panel follows the `indicators` feature flag.
+   * Enabled in both modes by default.
+   */
+  canRenderIndicators(): boolean {
+    return this.canUseIndicators();
+  }
+
+  /**
+   * Drawing tools are always available regardless of license mode.
+   */
+  canRenderDrawings(): boolean {
+    return true;
+  }
+
+  // ── Convenience snapshot ────────────────────────────────────────────────────
+
+  /**
+   * Returns the full capability set as a plain object — useful for logging,
+   * debug panels, or passing state to React context in one call.
+   */
+  getCapabilities(): ChartCapabilities {
+    return {
+      // ── Mode & feature-level flags ──────────────────────────────────────
+      mode:                this.lm.getMode(),
+      externalIngestion:   this.canUseExternalIngestion(),
+      overlays:            this.canRenderOverlays(),
+      indicators:          this.canUseIndicators(),
+      orderEntry:          this.canUseOrderEntry(),
+      managedTrading:      this.canUseManagedTrading(),
+      draggableOrders:     this.canUseDraggableOrders(),
+      bracketOrders:       this.canUseBracketOrders(),
+      // ── UI render flags ─────────────────────────────────────────────────
+      renderOrderEntry:                this.canRenderOrderEntry(),
+      renderBuySellButtons:            this.canRenderBuySellButtons(),
+      renderOrderTicket:               this.canRenderOrderTicket(),
+      renderBracketControls:           this.canRenderBracketControls(),
+      renderOrderModificationControls: this.canRenderOrderModificationControls(),
+      renderManagedTradingControls:    this.canRenderManagedTradingControls(),
+      renderExternalOverlayOnly:       this.canRenderExternalOverlayOnlyMode(),
+      renderPositions:                 this.canRenderPositions(),
+      renderFills:                     this.canRenderFills(),
+      renderCandles:                   this.canRenderCandles(),
+      renderIndicators:                this.canRenderIndicators(),
+      renderDrawings:                  this.canRenderDrawings(),
+    };
+  }
+
+  // ── Private helpers ─────────────────────────────────────────────────────────
+
+  /**
+   * If the active license has an explicit feature flag, use it.
+   * Otherwise fall back to `defaultValue` (allows capability even without an
+   * explicit flag, matching the "omitted = allowed" convention).
+   */
+  #featureOrDefault(name: keyof LicenseFeatures, defaultValue: boolean): boolean {
+    const features = this.lm.getFeatures();
+    const flag = features[name];
+    return flag === undefined ? defaultValue : flag === true;
+  }
+}
+
+// ── Capability snapshot type ─────────────────────────────────────────────────
+
+export interface ChartCapabilities {
+  // ── Mode & feature-level flags ────────────────────────────────────────────
+  mode:              'managed' | 'unmanaged';
+  externalIngestion: boolean;
+  overlays:          boolean;
+  indicators:        boolean;
+  orderEntry:        boolean;
+  managedTrading:    boolean;
+  draggableOrders:   boolean;
+  bracketOrders:     boolean;
+  // ── UI render flags ───────────────────────────────────────────────────────
+  /** Show the order entry tool in toolbars (managed only). */
+  renderOrderEntry:                boolean;
+  /** Show Buy / Sell action buttons (managed only). */
+  renderBuySellButtons:            boolean;
+  /** Show the order ticket / entry form (managed only). */
+  renderOrderTicket:               boolean;
+  /** Show bracket order controls — TP, SL, OCO (managed + bracketOrders). */
+  renderBracketControls:           boolean;
+  /** Show order modification controls — drag handles, edit panel (managed + draggableOrders). */
+  renderOrderModificationControls: boolean;
+  /** Show the entire managed trading panel as a composite gate. */
+  renderManagedTradingControls:    boolean;
+  /** True when operating in external-overlay-only (unmanaged) mode. */
+  renderExternalOverlayOnly:       boolean;
+  /** Positions always rendered — data controlled by TradingOverlayStore. */
+  renderPositions:                 boolean;
+  /** Execution fills always rendered. */
+  renderFills:                     boolean;
+  /** Candles always rendered — RapidAPI datafeed unaffected by mode. */
+  renderCandles:                   boolean;
+  /** Indicators follow the `indicators` feature flag (both modes). */
+  renderIndicators:                boolean;
+  /** Drawing tools always available regardless of license mode. */
+  renderDrawings:                  boolean;
+}
+
+// ── Module-level convenience functions ───────────────────────────────────────
+// These mirror the instance methods and are the recommended import style for
+// non-class consumers.
+
+const resolver = () => ChartRuntimeResolver.getInstance();
+
+/** True when a managed license is active. */
+export const isManagedMode           = (): boolean => resolver().isManagedMode();
+/** True when no license or unmanaged license is active (safe default). */
+export const isUnmanagedMode         = (): boolean => resolver().isUnmanagedMode();
+/** External data ingestion APIs (unmanaged mode only by default). */
+export const canUseExternalIngestion = (): boolean => resolver().canUseExternalIngestion();
+/** Overlay rendering — enabled in both modes. */
+export const canRenderOverlays       = (): boolean => resolver().canRenderOverlays();
+/** Indicator computations — enabled in both modes. */
+export const canUseIndicators        = (): boolean => resolver().canUseIndicators();
+/** Built-in order entry UI — managed mode only. */
+export const canUseOrderEntry        = (): boolean => resolver().canUseOrderEntry();
+/** Managed trading service hooks — managed mode only. */
+export const canUseManagedTrading    = (): boolean => resolver().canUseManagedTrading();
+/** Drag-to-price order placement — managed mode only. */
+export const canUseDraggableOrders   = (): boolean => resolver().canUseDraggableOrders();
+/** Bracket / OCO order support — managed mode only. */
+export const canUseBracketOrders     = (): boolean => resolver().canUseBracketOrders();
+/** Full capability snapshot as a plain object. */
+export const getCapabilities         = (): ChartCapabilities => resolver().getCapabilities();
+
+// ── UI render convenience functions ──────────────────────────────────────────
+
+/** Whether to render the order entry tool in toolbars (managed only). */
+export const canRenderOrderEntry                = (): boolean => resolver().canRenderOrderEntry();
+/** Whether to render Buy/Sell buttons (managed only). */
+export const canRenderBuySellButtons            = (): boolean => resolver().canRenderBuySellButtons();
+/** Whether to render the order ticket panel (managed only). */
+export const canRenderOrderTicket               = (): boolean => resolver().canRenderOrderTicket();
+/** Whether to render bracket / OCO controls (managed + bracketOrders feature). */
+export const canRenderBracketControls           = (): boolean => resolver().canRenderBracketControls();
+/** Whether to render drag/edit order modification controls (managed + draggableOrders). */
+export const canRenderOrderModificationControls = (): boolean => resolver().canRenderOrderModificationControls();
+/** Whether to render the managed trading control panel (managed only). */
+export const canRenderManagedTradingControls    = (): boolean => resolver().canRenderManagedTradingControls();
+/** True when in external-overlay-only (unmanaged) mode — hides all order-entry UI. */
+export const canRenderExternalOverlayOnlyMode   = (): boolean => resolver().canRenderExternalOverlayOnlyMode();
+/** Positions always rendered regardless of mode. */
+export const canRenderPositions                 = (): boolean => resolver().canRenderPositions();
+/** Execution fills always rendered regardless of mode. */
+export const canRenderFills                     = (): boolean => resolver().canRenderFills();
+/** Candles always rendered — RapidAPI datafeed unaffected by mode. */
+export const canRenderCandles                   = (): boolean => resolver().canRenderCandles();
+/** Indicators follow the indicators feature flag (both modes by default). */
+export const canRenderIndicators                = (): boolean => resolver().canRenderIndicators();
+/** Drawing tools always available regardless of license mode. */
+export const canRenderDrawings                  = (): boolean => resolver().canRenderDrawings();

package/src/licensing/LicenseManager.ts

@@ -0,0 +1,131 @@
+import type { LicenseFeatures, LicenseMode, LicensePayload } from './licenseTypes';
+
+const DEFAULT_MODE: LicenseMode = 'unmanaged';
+const DEFAULT_FEATURES: LicenseFeatures = {};
+
+/**
+ * LicenseManager — single source of truth for chart mode and feature access.
+ *
+ * Usage:
+ *   const lm = LicenseManager.getInstance();
+ *   await lm.validateLicense('my-key');
+ *   lm.getMode();          // 'managed' | 'unmanaged'
+ *   lm.hasFeature('orderEntry');
+ */
+export class LicenseManager {
+  private static instance: LicenseManager | null = null;
+
+  private payload: LicensePayload | null = null;
+  private readonly subscribers: Set<() => void> = new Set();
+
+  private constructor() {}
+
+  /**
+   * Subscribe to license state changes (loadLicense, validateLicense, clear).
+   * Returns an unsubscribe function — call it to stop receiving notifications.
+   *
+   * @example
+   *   const unsub = LicenseManager.getInstance().subscribe(() => {
+   *     console.log('license changed', lm.getMode());
+   *   });
+   *   // later:
+   *   unsub();
+   */
+  subscribe(cb: () => void): () => void {
+    this.subscribers.add(cb);
+    return () => this.subscribers.delete(cb);
+  }
+
+  private notify(): void {
+    this.subscribers.forEach((cb) => {
+      try { cb(); } catch { /* subscriber errors must not affect license state */ }
+    });
+  }
+
+  static getInstance(): LicenseManager {
+    if (!LicenseManager.instance) {
+      LicenseManager.instance = new LicenseManager();
+    }
+    return LicenseManager.instance;
+  }
+
+  /**
+   * Validate a license key against the licensing endpoint.
+   *
+   * @param key       The raw license key entered by the user.
+   * @param verifyUrl Full URL of the forgecharts-admin verify endpoint,
+   *                  e.g. "http://licenses.example.com:4100/api/public/license/verify"
+   */
+  async validateLicense(key: string, verifyUrl: string): Promise<LicensePayload> {
+    if (!key || !key.trim()) {
+      throw new Error('LicenseManager: license key must not be empty');
+    }
+    if (!verifyUrl) {
+      throw new Error('LicenseManager: verifyUrl is required');
+    }
+
+    const res = await fetch(verifyUrl, {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body:    JSON.stringify({ licenseKey: key.trim().toUpperCase() }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`License server error: ${res.status} ${res.statusText}`);
+    }
+
+    const data = await res.json() as { valid: boolean; reason?: string; licenseKey?: string; mode?: string; plan?: string; expiresAt?: string | null; features?: Record<string, boolean> };
+
+    if (!data.valid) {
+      throw new Error(data.reason ?? 'License invalid');
+    }
+
+    const payload: LicensePayload = {
+      licenseKey: data.licenseKey ?? key.trim().toUpperCase(),
+      mode:       (data.mode ?? 'unmanaged') as LicensePayload['mode'],
+      ...(data.plan      != null && { plan:     data.plan }),
+      ...(data.expiresAt != null && { expires:  data.expiresAt }),
+      ...(data.features  != null && { features: data.features as LicenseFeatures }),
+    };
+
+    this.payload = payload;
+    this.notify();
+    return payload;
+  }
+
+  /** Load a pre-validated payload (e.g. from cache / localStorage). */
+  loadLicense(payload: LicensePayload): void {
+    this.payload = payload;
+    this.notify();
+  }
+
+  /** Return the currently loaded payload, or null if none. */
+  getLicense(): LicensePayload | null {
+    return this.payload;
+  }
+
+  /**
+   * The chart mode driven by the active license.
+   * Defaults to 'unmanaged' so no managed features appear without a valid
+   * managed license.
+   */
+  getMode(): LicenseMode {
+    return this.payload?.mode ?? DEFAULT_MODE;
+  }
+
+  /** Return the feature flags for the active license. */
+  getFeatures(): LicenseFeatures {
+    return this.payload?.features ?? DEFAULT_FEATURES;
+  }
+
+  /** Check whether a specific feature is enabled on the active license. */
+  hasFeature(name: keyof LicenseFeatures): boolean {
+    return this.getFeatures()[name] === true;
+  }
+
+  /** Clear the current license state (returns to safe unmanaged defaults). */
+  clear(): void {
+    this.payload = null;
+    this.notify();
+  }
+}