@forgecharts/sdk 1.1.23

package/src/api/LayoutManager.ts

@@ -0,0 +1,72 @@
+import type {
+  ChartLayout,
+  ChartInterval,
+  ChartTheme,
+  IndicatorInstance,
+  Drawing,
+  Viewport,
+  PaneDescriptor,
+} from '@forgecharts/types';
+
+/**
+ * LayoutManager — pure serialisation / deserialisation of chart state.
+ * No side effects; state mutations are the caller's responsibility.
+ */
+export class LayoutManager {
+  /**
+   * Produces a serialisable snapshot of the current chart state.
+   */
+  static save(params: {
+    symbol: string;
+    interval: ChartInterval;
+    theme: ChartTheme;
+    indicators: readonly IndicatorInstance[];
+    drawings: readonly Drawing[];
+    viewport?: Viewport;
+    panes?: readonly PaneDescriptor[];
+  }): ChartLayout {
+    return {
+      symbol: params.symbol,
+      interval: params.interval,
+      theme: params.theme,
+      indicators: [...params.indicators],
+      drawings: [...params.drawings],
+      ...(params.viewport !== undefined ? { viewport: params.viewport } : {}),
+      ...(params.panes !== undefined && params.panes.length > 0 ? { panes: [...params.panes] } : {}),
+      savedAt: Date.now(),
+    };
+  }
+
+  /**
+   * Serialises a layout to a JSON string safe for `localStorage` / remote persistence.
+   */
+  static toJSON(layout: ChartLayout): string {
+    return JSON.stringify(layout);
+  }
+
+  /**
+   * Parses a JSON string back into a ChartLayout.
+   * Throws if the string is malformed.
+   */
+  static fromJSON(raw: string): ChartLayout {
+    const parsed: unknown = JSON.parse(raw);
+    if (!LayoutManager._isLayout(parsed)) {
+      throw new Error('[ForgeCharts] LayoutManager.fromJSON: invalid layout schema');
+    }
+    return parsed;
+  }
+
+  private static _isLayout(v: unknown): v is ChartLayout {
+    if (typeof v !== 'object' || v === null) return false;
+    const l = v as Record<string, unknown>;
+    return (
+      typeof l['symbol'] === 'string' &&
+      typeof l['interval'] === 'string' &&
+      typeof l['theme'] === 'string' &&
+      Array.isArray(l['indicators']) &&
+      Array.isArray(l['drawings']) &&
+      typeof l['savedAt'] === 'number' &&
+      (l['panes'] === undefined || Array.isArray(l['panes']))
+    );
+  }
+}

package/src/api/PaneManager.ts

@@ -0,0 +1,129 @@
+import type { PaneDescriptor } from '@forgecharts/types';
+
+let _paneId = 0;
+function _nextId(): string {
+  return `pane-${(++_paneId).toString()}`;
+}
+
+/**
+ * PaneManager — manages the collection of sub-pane (indicator panel) descriptors.
+ *
+ * Each `PaneDescriptor` carries:
+ *  - a stable `id`
+ *  - a `heightFraction` (0–1, all panes sum to 1)
+ *  - the `indicatorIds` assigned to that pane
+ *
+ * Height redistribution is proportional: when a pane is added/removed/resized,
+ * the remaining panes absorb or donate height proportionally to their current sizes.
+ */
+export class PaneManager {
+  private _panes: PaneDescriptor[] = [];
+
+  getPanes(): readonly PaneDescriptor[] {
+    return this._panes;
+  }
+
+  /**
+   * Creates a new pane, distributing total height evenly across all panes.
+   * @returns The new pane's id.
+   */
+  createPane(label?: string): string {
+    const id = _nextId();
+    const newFraction = 1 / (this._panes.length + 1);
+    // Shrink existing panes proportionally
+    this._panes = this._panes.map((p) => ({
+      ...p,
+      heightFraction: p.heightFraction * (1 - newFraction),
+    }));
+    this._panes.push({
+      id,
+      heightFraction: newFraction,
+      indicatorIds: [],
+      ...(label !== undefined ? { label } : {}),
+    });
+    return id;
+  }
+
+  /**
+   * Removes a pane and redistributes its height fraction to remaining panes.
+   */
+  removePane(id: string): void {
+    const idx = this._panes.findIndex((p) => p.id === id);
+    if (idx === -1) return;
+    const freed = this._panes[idx]!.heightFraction;
+    this._panes.splice(idx, 1);
+    if (this._panes.length > 0) {
+      const total = this._panes.reduce((s, p) => s + p.heightFraction, 0);
+      if (total > 0) {
+        this._panes = this._panes.map((p) => ({
+          ...p,
+          heightFraction: p.heightFraction + freed * (p.heightFraction / total),
+        }));
+      } else {
+        const even = 1 / this._panes.length;
+        this._panes = this._panes.map((p) => ({ ...p, heightFraction: even }));
+      }
+    }
+  }
+
+  /**
+   * Assigns an indicator to a pane, removing it from any previous pane first.
+   */
+  assignIndicator(indicatorId: string, paneId: string): void {
+    // Remove from every pane first (mutual exclusion)
+    this._panes = this._panes.map((p) => ({
+      ...p,
+      indicatorIds: p.indicatorIds.filter((iid) => iid !== indicatorId),
+    }));
+    const idx = this._panes.findIndex((p) => p.id === paneId);
+    if (idx === -1) return;
+    const pane = this._panes[idx]!;
+    this._panes[idx] = { ...pane, indicatorIds: [...pane.indicatorIds, indicatorId] };
+  }
+
+  /**
+   * Unassigns an indicator from whichever pane currently holds it.
+   */
+  unassignIndicator(indicatorId: string): void {
+    this._panes = this._panes.map((p) => ({
+      ...p,
+      indicatorIds: p.indicatorIds.filter((iid) => iid !== indicatorId),
+    }));
+  }
+
+  /**
+   * Resizes a pane by setting its `heightFraction`, clamped to [0.05, 0.9].
+   * Remaining panes absorb the difference proportionally.
+   */
+  resizePane(id: string, newFraction: number): void {
+    const clamped = Math.min(Math.max(newFraction, 0.05), 0.9);
+    const idx = this._panes.findIndex((p) => p.id === id);
+    if (idx === -1) return;
+    const old = this._panes[idx]!.heightFraction;
+    const delta = clamped - old;
+    const othersTotal = this._panes.reduce(
+      (s, p, i) => (i !== idx ? s + p.heightFraction : s),
+      0,
+    );
+    this._panes = this._panes.map((p, i) => {
+      if (i === idx) return { ...p, heightFraction: clamped };
+      const share =
+        othersTotal > 0
+          ? p.heightFraction / othersTotal
+          : 1 / Math.max(1, this._panes.length - 1);
+      return { ...p, heightFraction: Math.max(0.05, p.heightFraction - delta * share) };
+    });
+  }
+
+  serialize(): readonly PaneDescriptor[] {
+    return [...this._panes];
+  }
+
+  restore(panes: readonly PaneDescriptor[]): void {
+    this._panes = [...panes];
+  }
+
+  clear(): void {
+    this._panes = [];
+  }
+}

package/src/api/ReferenceAPI.ts

@@ -0,0 +1,195 @@
+import type {
+  RefMarket,
+  RefExchange,
+  RefSymbol,
+  SymbolSearchFilters,
+  SymbolSearchResult,
+} from '@forgecharts/types';
+
+export type ReferenceAPIConfig = {
+  /** Base URL of the ForgeCharts API server (e.g. "https://charts.myapp.com"). Defaults to current origin. */
+  apiUrl?: string;
+  /** Called to retrieve a Bearer token for authenticated endpoints. Falls back to localStorage['forgecharts-token']. */
+  getAuthToken?: () => string | Promise<string>;
+};
+
+type ProviderMapping = {
+  providerCode: string;
+  providerSymbol: string;
+  providerExchange: string | null;
+  metadata: unknown;
+};
+
+/**
+ * ReferenceAPI — headless SDK client for the Global Reference Data Platform.
+ *
+ * Provides symbol lookup, search, market/exchange browsing,
+ * provider mapping resolution, plus per-user favorites and recents.
+ *
+ * @example
+ * ```ts
+ * const ref = new ReferenceAPI();
+ * const { symbols } = await ref.searchSymbols('BTC');
+ * const popular = await ref.getPopularSymbols('crypto', 10);
+ * ```
+ */
+export class ReferenceAPI {
+  private readonly _base: string;
+  private readonly _getToken: (() => string | Promise<string>) | undefined;
+
+  constructor(config: ReferenceAPIConfig = {}) {
+    this._base     = (config.apiUrl ?? '').replace(/\/$/, '') + '/api/reference';
+    this._getToken = config.getAuthToken;
+  }
+
+  // ── Internals ──────────────────────────────────────────────────────────────
+
+  private async _authHeaders(): Promise<Record<string, string>> {
+    const h: Record<string, string> = { 'Content-Type': 'application/json' };
+    let token: string | null = null;
+
+    if (this._getToken) {
+      token = await this._getToken();
+    } else if (typeof localStorage !== 'undefined') {
+      token = localStorage.getItem('forgecharts-token');
+    }
+
+    if (token) h['Authorization'] = `Bearer ${token}`;
+    return h;
+  }
+
+  private async _get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T> {
+    let url = this._base + path;
+    if (params) {
+      const qs = new URLSearchParams();
+      for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined) qs.set(k, String(v));
+      }
+      const str = qs.toString();
+      if (str) url += '?' + str;
+    }
+    const res = await fetch(url, { headers: await this._authHeaders() });
+    if (!res.ok) throw new Error(`ReferenceAPI GET ${path} → HTTP ${res.status}`);
+    return res.json() as Promise<T>;
+  }
+
+  private async _post(path: string, body: unknown): Promise<void> {
+    const res = await fetch(this._base + path, {
+      method:  'POST',
+      headers: await this._authHeaders(),
+      body:    JSON.stringify(body),
+    });
+    if (!res.ok && res.status !== 204) {
+      throw new Error(`ReferenceAPI POST ${path} → HTTP ${res.status}`);
+    }
+  }
+
+  private async _delete(path: string): Promise<void> {
+    const res = await fetch(this._base + path, {
+      method:  'DELETE',
+      headers: await this._authHeaders(),
+    });
+    if (!res.ok && res.status !== 204) {
+      throw new Error(`ReferenceAPI DELETE ${path} → HTTP ${res.status}`);
+    }
+  }
+
+  // ── Markets & Exchanges ────────────────────────────────────────────────────
+
+  /** Returns all active market categories (crypto, stocks, forex, …). */
+  async getMarkets(): Promise<RefMarket[]> {
+    return this._get<RefMarket[]>('/markets');
+  }
+
+  /** Returns all active exchanges / venues. */
+  async getExchanges(): Promise<RefExchange[]> {
+    return this._get<RefExchange[]>('/exchanges');
+  }
+
+  // ── Symbol catalogue ───────────────────────────────────────────────────────
+
+  /**
+   * Full-text search across symbol tickers, names, and aliases.
+   * @param query   Search term (minimum 1 character).
+   * @param filters Optional market / exchange / limit / offset filters.
+   */
+  async searchSymbols(query: string, filters?: SymbolSearchFilters): Promise<SymbolSearchResult> {
+    return this._get<SymbolSearchResult>('/symbols/search', {
+      q:        query,
+      market:   filters?.market,
+      exchange: filters?.exchange,
+      limit:    filters?.limit,
+      offset:   filters?.offset,
+    });
+  }
+
+  /**
+   * Browse the symbol catalogue with optional filters.
+   * Returns symbols ordered alphabetically.
+   */
+  async getSymbols(filters?: SymbolSearchFilters): Promise<SymbolSearchResult> {
+    return this._get<SymbolSearchResult>('/symbols', {
+      market:    filters?.market,
+      exchange:  filters?.exchange,
+      assetType: (filters as Record<string, unknown>)?.['assetType'] as string | undefined,
+      limit:     filters?.limit,
+      offset:    filters?.offset,
+    });
+  }
+
+  /**
+   * Returns the most popular / trending symbols.
+   * @param market  Optional market code to restrict results (e.g. "crypto").
+   * @param limit   Maximum results to return. Defaults to 20.
+   */
+  async getPopularSymbols(market?: string, limit = 20): Promise<RefSymbol[]> {
+    return this._get<RefSymbol[]>('/symbols/popular', { market, limit });
+  }
+
+  /**
+   * Fetches full metadata for a single symbol by its global symbol key.
+   * @param symbolKey  e.g. "CRYPTO:BINANCE:BTCUSDT"
+   */
+  async getSymbol(symbolKey: string): Promise<RefSymbol> {
+    return this._get<RefSymbol>(`/symbols/${encodeURIComponent(symbolKey)}`);
+  }
+
+  /**
+   * Returns all provider-specific mappings for a symbol.
+   * Useful for resolving the correct datafeed symbol string at runtime.
+   */
+  async getProviderMapping(symbolKey: string): Promise<ProviderMapping[]> {
+    return this._get<ProviderMapping[]>(
+      `/symbols/${encodeURIComponent(symbolKey)}/provider-mapping`,
+    );
+  }
+
+  // ── User: Recents (requires auth) ─────────────────────────────────────────
+
+  /** Returns the authenticated user's recently viewed symbols (newest first). */
+  async getRecentSymbols(): Promise<RefSymbol[]> {
+    return this._get<RefSymbol[]>('/me/recents');
+  }
+
+  /** Records a symbol as recently viewed for the authenticated user. */
+  async recordRecentSymbol(symbolKey: string): Promise<void> {
+    return this._post('/me/recents', { symbolKey });
+  }
+
+  // ── User: Favorites (requires auth) ───────────────────────────────────────
+
+  /** Returns the authenticated user's favorite symbols. */
+  async getFavoriteSymbols(): Promise<RefSymbol[]> {
+    return this._get<RefSymbol[]>('/me/favorites');
+  }
+
+  /** Adds a symbol to the authenticated user's favorites. */
+  async addFavoriteSymbol(symbolKey: string): Promise<void> {
+    return this._post('/me/favorites', { symbolKey });
+  }
+
+  /** Removes a symbol from the authenticated user's favorites. */
+  async removeFavoriteSymbol(symbolKey: string): Promise<void> {
+    return this._delete(`/me/favorites/${encodeURIComponent(symbolKey)}`);
+  }
+}