@forgecharts/sdk 1.1.23

package/src/engine/timeframeUtils.ts

@@ -0,0 +1,118 @@
+/**
+ * Timeframe utilities — thin compatibility wrappers over `@forgecharts/shared/time`.
+ *
+ * All bucket-alignment logic now lives in the canonical shared module.
+ * These exports keep the existing `CandleEngine` and `DatafeedConnector` import
+ * surface stable while delegating every calculation to the single source of truth.
+ *
+ * Migration note:
+ *   New code should import directly from `@forgecharts/shared/time`:
+ *     import { getBucketStart, getWeekBucketStart, getMonthBucketStart } from '@forgecharts/shared/time';
+ *
+ *   Legacy imports from this file continue to work unchanged.
+ */
+
+import {
+  getBucketStart   as sharedGetBucketStart,
+  timeframeToMs    as sharedTimeframeToMs,
+} from '@forgecharts/shared/time';
+
+// ─── timeframeToMs ────────────────────────────────────────────────────────────
+
+/**
+ * Convert a timeframe label to its duration in milliseconds.
+ *
+ * Returns `60_000` (1 minute) for calendar timeframes (`1w`, `1M`) and unknown
+ * labels — preserving the previous behaviour that `CandleEngine` depended on.
+ * New code should use `sharedTimeframeToMs` (which returns `null` for those
+ * cases) and handle `null` explicitly.
+ *
+ * @example
+ * timeframeToMs('1m')  // → 60_000
+ * timeframeToMs('4h')  // → 14_400_000
+ * timeframeToMs('1w')  // → 60_000  (calendar — no fixed duration; fallback)
+ */
+export function timeframeToMs(timeframe: string): number {
+  return sharedTimeframeToMs(timeframe) ?? 60_000;
+}
+
+// ─── getBucketStart (interval-based) ─────────────────────────────────────────
+
+/**
+ * Floor a millisecond timestamp to the start of its fixed-interval bucket.
+ *
+ * This overload takes an explicit `intervalMs` and is used internally by
+ * `aggregateToBucket` for sub-daily custom timeframe synthesis.
+ *
+ * For timeframe-label–based alignment (including 1w / 1M calendar logic)
+ * use `getCalendarBucketStart` or import `getBucketStart` from `@forgecharts/shared`.
+ *
+ * @example
+ * getBucketStart(62_000,   60_000)       // → 60_000
+ * getBucketStart(3_720_000, 3_600_000)   // → 3_600_000
+ */
+export function getBucketStart(timeMs: number, intervalMs: number): number {
+  return Math.floor(timeMs / intervalMs) * intervalMs;
+}
+
+// ─── getCalendarBucketStart ───────────────────────────────────────────────────
+
+/**
+ * Floor a millisecond timestamp to the candle-open boundary for the given
+ * timeframe label, with correct calendar alignment:
+ *
+ *   `1w` — Monday-aligned week (ISO 8601, UTC) via `getWeekBucketStart`
+ *   `1M` — first of calendar month, UTC via `getMonthBucketStart`
+ *   all others — plain epoch-floor via `getBucketStart`
+ *
+ * Delegates entirely to the canonical shared module.
+ */
+export function getCalendarBucketStart(timeMs: number, tf: string): number {
+  return sharedGetBucketStart(timeMs, tf);
+}
+
+// ─── aggregateToBucket ────────────────────────────────────────────────────────
+
+/**
+ * Build a custom timeframe by aggregating base-timeframe candles into larger buckets.
+ * Returns the aggregated candles for all buckets covered by `subBars`.
+ *
+ * This is the building block for synthesising e.g. 3m from 1m feeds.
+ *
+ * @param subBars    Candles from the base timeframe, sorted ascending by timeMs.
+ * @param targetMs   Target timeframe duration in ms (e.g. 180_000 for 3m).
+ *
+ * @throws {Error} If `targetMs` corresponds to a calendar-irregular timeframe
+ *   (`1w` / `1M`). Use `getCalendarBucketStart` for those directly.
+ */
+export function aggregateToBucket(
+  subBars: ReadonlyArray<{
+    timeMs: number; open: number; high: number; low: number; close: number; volume: number;
+  }>,
+  targetMs: number,
+): Array<{ timeMs: number; open: number; high: number; low: number; close: number; volume: number }> {
+  // 1w is 7 days exactly; 1M has no fixed duration and can never equal a targetMs.
+  // Guard prevents accidentally using fixed-interval bucketing for weekly candles
+  // where DST can make weeks slightly unequal (though UTC avoids this).
+  const WEEK_MS = 7 * 24 * 60 * 60 * 1000; // 604_800_000
+  if (targetMs === WEEK_MS) {
+    throw new Error('aggregateToBucket: use getCalendarBucketStart for 1w/1M aggregation');
+  }
+
+  const buckets = new Map<number, { timeMs: number; open: number; high: number; low: number; close: number; volume: number }>();
+
+  for (const bar of subBars) {
+    const bucket = getBucketStart(bar.timeMs, targetMs);
+    const existing = buckets.get(bucket);
+    if (!existing) {
+      buckets.set(bucket, { timeMs: bucket, open: bar.open, high: bar.high, low: bar.low, close: bar.close, volume: bar.volume });
+    } else {
+      existing.high   = Math.max(existing.high, bar.high);
+      existing.low    = Math.min(existing.low,  bar.low);
+      existing.close  = bar.close;
+      existing.volume += bar.volume;
+    }
+  }
+
+  return Array.from(buckets.values()).sort((a, b) => a.timeMs - b.timeMs);
+}

package/src/index.ts

@@ -0,0 +1,190 @@
+// ─── Primary entry point ─────────────────────────────────────────────────────
+export { createChart } from './api/createChart';
+export { TChart } from './api/TChart';
+
+// ─── Reference Data API ───────────────────────────────────────────────────────
+export { ReferenceAPI } from './api/ReferenceAPI';
+export type { ReferenceAPIConfig } from './api/ReferenceAPI';
+
+// ─── Datafeed ─────────────────────────────────────────────────────────────────
+export { DatafeedConnector } from './datafeed/DatafeedConnector';
+export type { ConnectorCallbacks } from './datafeed/DatafeedConnector';
+// ─── Indicator engine ─────────────────────────────────────────────────────
+export {
+  computeSMA,
+  computeEMA,
+  computeRSI,
+  computeMACD,
+  computeVolume,
+  // Series-based variants for DAG chaining
+  extractField,
+  computeSMAFromSeries,
+  computeEMAFromSeries,
+  computeWMAFromSeries,
+} from './core/IndicatorEngine';
+export type { IndicatorPoint, MACDPoint } from './core/IndicatorEngine';
+
+// ─── Indicator DAG ────────────────────────────────────────────────────────────
+export { IndicatorDAG } from './api/IndicatorDAG';
+export type { DAGResult } from './api/IndicatorDAG';
+
+// ─── TScript scripting engine ─────────────────────────────────────────────────
+export { TScriptIndicator } from './tscript/TScriptIndicator';
+export { Series as TScriptSeries } from './tscript/series';
+export { TScriptRuntime } from './tscript/runtime';
+export type { TValue, ScriptResult } from './tscript/runtime';
+
+// ─── Pine Script compatibility layer ─────────────────────────────────────────
+export { PineCompiler, DiagnosticBag } from './pine';
+export type { PineCompileResult, Diagnostic, DiagnosticSeverity } from './pine';
+
+// ─── Pane manager ─────────────────────────────────────────────────────────
+export { PaneManager } from './api/PaneManager';
+// ─── Coordinate transform system ─────────────────────────────────────────────
+export { CoordTransform } from './core/CoordTransform';
+export type { PlotArea } from './core/CoordTransform';
+
+// ─── Candle engine ────────────────────────────────────────────────────────────
+export { CandleEngine } from './engine/CandleEngine';
+export type { CandleBar, RawOHLCV, UpdateResult, GapInfo, CandleEngineOptions } from './engine/CandleEngine';
+export { timeframeToMs, getBucketStart } from './engine/timeframeUtils';
+export { getMissingBarCount, mergeBars } from './engine/mergeUtils';
+
+// ─── Trading types & overlay store ───────────────────────────────────────────
+export type {
+  CandleInput,
+  ChartOrder,
+  ChartPosition,
+  ExecutionFill,
+  OrderRole,
+  OrderSide,
+  OrderStatus,
+  PositionSide,
+  PositionStatus,
+  FillSide,
+} from './trading/tradingTypes';
+export { TradingOverlayStore } from './trading/TradingOverlayStore';
+export { UnmanagedIngestion } from './trading/UnmanagedIngestion';
+
+// ─── Managed trading ──────────────────────────────────────────────────────────
+export { ManagedTradingController } from './trading/managed/ManagedTradingController';
+export type {
+  IExecutionProvider,
+  PlaceOrderInput,
+  ModifyOrderInput,
+  PlaceBracketOrderInput,
+  OrderAck,
+  BracketOrderAck,
+  ManagedOrderType,
+  TimeInForce,
+} from './trading/managed/managedTypes';
+export {
+  assertManagedMode,
+  assertCanPlaceOrders,
+  assertCanUseBrackets,
+  assertCanUseDraggableOrders,
+  assertCanUseManagedTrading,
+  isManagedCapable,
+  canPlaceOrders,
+  canPlaceBrackets,
+  canUseDraggable,
+  canUseManagedTradingHook,
+} from './trading/managed/managedCapabilities';
+
+// ─── Licensing ────────────────────────────────────────────────────────────────
+export { LicenseManager } from './licensing/LicenseManager';
+export type { LicenseMode, LicenseFeatures, LicensePayload } from './licensing/licenseTypes';
+
+// ─── Chart runtime resolver ───────────────────────────────────────────────────
+export { ChartRuntimeResolver } from './licensing/ChartRuntimeResolver';
+export type { ChartCapabilities } from './licensing/ChartRuntimeResolver';
+export {
+  // Mode checks
+  isManagedMode,
+  isUnmanagedMode,
+  // Feature-level capability checks
+  canUseExternalIngestion,
+  canRenderOverlays,
+  canUseIndicators,
+  canUseOrderEntry,
+  canUseManagedTrading,
+  canUseDraggableOrders,
+  canUseBracketOrders,
+  getCapabilities,
+  // UI render capability checks
+  canRenderOrderEntry,
+  canRenderBuySellButtons,
+  canRenderOrderTicket,
+  canRenderBracketControls,
+  canRenderOrderModificationControls,
+  canRenderManagedTradingControls,
+  canRenderExternalOverlayOnlyMode,
+  canRenderPositions,
+  canRenderFills,
+  canRenderCandles,
+  canRenderIndicators,
+  canRenderDrawings,
+} from './licensing/ChartRuntimeResolver';
+
+// ─── Shared / public types ────────────────────────────────────────────────────
+export type {
+  // Primitives
+  OHLCV,
+  Bar,
+  Timeframe,
+  ChartOptions,
+  SeriesOptions,
+  SeriesType,
+  ChartTheme,
+  Viewport,
+  TimeRange,
+  PriceRange,
+  Point,
+  Rect,
+  Drawing,
+  DrawingType,
+  DrawingToolType,
+  PointerToolType,
+  DrawingPoint,
+  // Datafeed
+  IDatafeed,
+  MarketType,
+  SymbolInfo,
+  HistoricalBarsResult,
+  // Interaction
+  HitTestResult,
+  ChartKeyAction,
+  KeyModifiers,
+  // Public SDK API types
+  ChartInterval,
+  ChartConfig,
+  ChartLayout,
+  ChartEventMap,
+  IndicatorType,
+  IndicatorParams,
+  IndicatorConfig,
+  IndicatorInstance,
+  PriceField,
+  PaneDescriptor,
+  IPlugin,
+  IPublicChart,
+  // Reference Data Platform
+  RefMarket,
+  RefExchange,
+  RefSymbol,
+  SymbolSearchFilters,
+  SymbolSearchResult,
+} from '@forgecharts/types';
+
+// ─── Pointer tool descriptors & visual constants ──────────────────────────────
+export { cursorTool, CURSOR_LABEL, CURSOR_STYLE }
+  from './api/drawing tools/pointers menu/cursor';
+export { crosshairTool, CROSSHAIR_LABEL, CROSSHAIR_STYLE }
+  from './api/drawing tools/pointers menu/crosshair';
+export { dotTool, DOT_LABEL, DOT_STYLE, DOT_RADIUS, DOT_COLOR }
+  from './api/drawing tools/pointers menu/dot';
+export {
+  demonstrationTool,
+  DEMONSTRATION_LABEL, DEMONSTRATION_STYLE,
+  DEMONSTRATION_RADIUS, DEMONSTRATION_FILL, DEMONSTRATION_STROKE, DEMONSTRATION_COLOR,
+} from './api/drawing tools/pointers menu/demonstration';

package/src/internal.ts

@@ -0,0 +1,41 @@
+/**
+ * @forgecharts/sdk/internal
+ *
+ * Internal SDK engine exports — for ForgeCharts package layer use only.
+ * Do NOT import from this path in host applications or external integrations.
+ * No semver stability guarantee applies to this entry point.
+ *
+ * Direct internal consumers:
+ *   - @forgecharts/chart-components (canvas rendering layer)
+ *   - ForgeCharts platform app layer (engine-level customization)
+ *
+ * Exports in this file are the raw canvas engine primitives that underpin
+ * TChart. Host applications should use TChart via createChart() instead.
+ */
+
+// Re-export the full public API so this is a superset.
+export * from './index';
+
+// ─── Raw engine layer ─────────────────────────────────────────────────────────
+// Direct chart/series/scale primitives beneath TChart.
+// Use TChart.getChart() / TChart.getSeries() to access these from outside the SDK.
+export { Chart } from './core/Chart';
+export { Series } from './core/Series';
+export { TimeScale } from './core/TimeScale';
+export { PriceScale } from './core/PriceScale';
+export { Crosshair } from './core/Crosshair';
+
+// ─── GPU acceleration layer (PixiJS) ─────────────────────────────────────────
+// Implementation details of the rendering pipeline.
+export { PixiChart } from './pixi/PixiChart';
+export { PixiLayerManager, DirtyFlags } from './pixi/PixiLayerManager';
+export { LayerName } from './pixi/LayerName';
+
+// ─── Interaction layer ────────────────────────────────────────────────────────
+export { InteractionManager } from './core/InteractionManager';
+export type { InteractionHandlers, InteractionOptions } from './core/InteractionManager';
+
+// ─── Internal engine interfaces ───────────────────────────────────────────────
+export type { IChart, IChartPlugin } from './types/IChart';
+export type { ISeries } from './types/ISeries';
+export type { IRenderer } from './types/IRenderer';