@supersolutions/super-chart-superscript 0.0.0 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,354 @@
+import { Series } from '@supersolutions/super-chart-core';
+
+/**
+ * SuperScript diagnostics: every problem has a severity, a code, a message and
+ * a 1-based position, so a person, an editor or an AI repair loop can act on
+ * it. Part of Super Chart.
+ */
+export type DiagnosticSeverity = "error" | "warning";
+/**
+ * Codes are stable; messages may be reworded.
+ *
+ * Errors (the script does not compile):
+ * UNEXPECTED_CHAR, UNTERMINATED_STRING, UNEXPECTED_TOKEN, TRAILING_TOKENS,
+ * UNBALANCED, REASSIGNMENT (`:=`, `+=`, …), CONTROL_FLOW (`if`, `for`, …),
+ * FUNCTION_DEF (`f(x) => …`), BUILTIN_REASSIGNED, UNKNOWN_IDENTIFIER,
+ * UNKNOWN_FUNCTION, ARITY, UNKNOWN_ARGUMENT, DUPLICATE_ARGUMENT,
+ * EXPECTED_CONSTANT, BAD_LENGTH, BAD_OFFSET, TYPE, PINE_MISMATCH,
+ * UNSUPPORTED, STATEMENT (`plot()` inside an expression).
+ *
+ * Warnings (the script compiles; the part named is ignored):
+ * IGNORED_STATEMENT (plotshape, bgcolor, strategy.*, …), UNUSED_EXPRESSION,
+ * IGNORED_KEYWORD (var, float, …), UNKNOWN_KEYWORD (an unknown plot()
+ * keyword), NO_PLOTS.
+ */
+export type DiagnosticCode = "UNEXPECTED_CHAR" | "UNTERMINATED_STRING" | "UNEXPECTED_TOKEN" | "TRAILING_TOKENS" | "UNBALANCED" | "REASSIGNMENT" | "CONTROL_FLOW" | "FUNCTION_DEF" | "BUILTIN_REASSIGNED" | "UNKNOWN_IDENTIFIER" | "UNKNOWN_FUNCTION" | "ARITY" | "UNKNOWN_ARGUMENT" | "DUPLICATE_ARGUMENT" | "EXPECTED_CONSTANT" | "BAD_LENGTH" | "BAD_OFFSET" | "TYPE" | "PINE_MISMATCH" | "UNSUPPORTED" | "STATEMENT" | "IGNORED_STATEMENT" | "UNUSED_EXPRESSION" | "IGNORED_KEYWORD" | "UNKNOWN_KEYWORD" | "NO_PLOTS";
+export interface Diagnostic {
+	severity: DiagnosticSeverity;
+	code: DiagnosticCode;
+	message: string;
+	/** 1-based line. */
+	line: number;
+	/** 1-based column of the first character. */
+	col: number;
+	/** 1-based column just past the last character. */
+	endCol: number;
+	/** A suggested fix, when there is one. */
+	hint?: string;
+}
+/**
+ * Thrown by `compile()` for the first error (all diagnostics are on
+ * `diagnostics`) and by `run()` for a problem that only shows with real
+ * parameters. Identify it with `isSuperScriptError(e)`: the `.` and `./lite`
+ * CommonJS/UMD builds each carry their own copy of this class, so
+ * `instanceof` can miss.
+ */
+export declare class SuperScriptError extends Error {
+	readonly code: DiagnosticCode;
+	readonly line: number;
+	readonly col: number;
+	readonly endCol: number;
+	readonly hint?: string;
+	readonly diagnostics: Diagnostic[];
+	constructor(diagnostic: Diagnostic, diagnostics?: Diagnostic[]);
+}
+/** True for a SuperScriptError from any copy of this package. */
+export declare function isSuperScriptError(e: unknown): e is SuperScriptError;
+/**
+ * Diagnostics as text, one per problem, each with its source line and a caret
+ * under the span: what a model needs to repair its script.
+ */
+export declare function formatDiagnostics(diagnostics: readonly Diagnostic[], source?: string): string;
+export interface Bar {
+	timestamp: number;
+	open: number;
+	high: number;
+	low: number;
+	close: number;
+	volume?: number;
+}
+export interface PlotStyle {
+	color?: string;
+	lineWidth?: number;
+	type?: "line" | "histogram" | "circle";
+	/** Where a histogram's bars start (default 0). On a log- or percentage-scaled
+	 *  price pane 0 is off the scale and the bars vanish: set it to a price there. */
+	histbase?: number;
+	/** Line dash; hline() levels are dashed. */
+	lineStyle?: "solid" | "dashed" | "dotted";
+}
+export interface Plot {
+	id: string;
+	title: string;
+	values: Series;
+	style?: PlotStyle;
+	/** "hline" for a constant level drawn with hline(). */
+	kind?: "plot" | "hline";
+}
+/** One `input()` of a script: what a settings form or an agent can change. */
+export interface ScriptInput {
+	/** The name it is bound to (`len = input(14)` → "len"), else "in<index>". */
+	id: string;
+	title: string;
+	defval: number;
+	min?: number;
+	max?: number;
+	step?: number;
+	type: "int" | "float";
+}
+/** Input values for `run()`: by position (the order of `meta.inputs`) or by input id. */
+export type ScriptParams = ReadonlyArray<number | null | undefined> | Readonly<Record<string, number | null | undefined>>;
+export interface ScriptMeta {
+	title: string;
+	/** The script's inputs in source order (SuperScript). */
+	inputs?: ScriptInput[];
+	/** True when the script declares `// @overlay` (it plots on the price scale). */
+	overlay?: boolean;
+}
+export interface ScriptResult {
+	meta: ScriptMeta;
+	plots: Plot[];
+	/** Warnings from compiling the script (SuperScript). */
+	diagnostics?: Diagnostic[];
+}
+/** A pluggable script language (SuperScript, JavaScript, …). */
+export interface ScriptLanguage {
+	id: string;
+	name: string;
+	compile(source: string): CompiledScript;
+}
+export interface CompiledScript {
+	meta: ScriptMeta;
+	/** Evaluate over bars. `params` overrides the inputs (clamped to their minval/maxval). */
+	run(bars: Bar[], params?: ScriptParams): ScriptResult;
+	/** Warnings (a script with errors does not compile). */
+	diagnostics?: Diagnostic[];
+}
+export interface CompileOptions {
+	/** Throw on warnings too (ignored statements, unknown plot keywords, …). */
+	strict?: boolean;
+}
+/**
+ * Every problem in a SuperScript source, errors and warnings, each with its
+ * line, column and (often) a hint. Never throws; an empty list means the
+ * script compiles cleanly. This is what an editor or an AI repair loop reads.
+ */
+export declare function checkSuperScript(source: string): Diagnostic[];
+export declare const SuperScriptLanguage: ScriptLanguage & {
+	compile: (source: string, options?: CompileOptions) => CompiledScript;
+};
+/** JavaScript language adapter — the script body is `(ctx) => ScriptResult`.
+ * Not registered by default: `registerLanguage(JavaScriptLanguage)` opts in.
+ * It evaluates the source with `new Function` in the host page (full code
+ * execution); never pass it a script from a model, a user or a tool call. */
+export declare const JavaScriptLanguage: ScriptLanguage;
+/** Human/LLM-readable catalog of the SuperScript vocabulary, generated from the
+ *  same signature table the checker uses, so the docs and the AI system prompt
+ *  cannot drift from the language. */
+export declare function superscriptReference(): string;
+export declare const superlib: {
+	sma: (src: Series, len: number) => Series;
+	ema: (src: Series, len: number) => Series;
+	rsi: (src: Series, len: number) => Series;
+	highest: (src: Series, len: number) => Series;
+	lowest: (src: Series, len: number) => Series;
+	crossover: (a: Series, b: Series) => Series;
+	crossunder: (a: Series, b: Series) => Series;
+	wma: (src: Series, len: number) => Series;
+	stdev: (src: Series, len: number) => Series;
+	change: (src: Series) => Series;
+	roc: (src: Series, len: number) => Series;
+	tr: (high: Series, low: Series, close: Series) => Series;
+	atr: (high: Series, low: Series, close: Series, len: number) => Series;
+	sum: (src: Series, len: number) => Series;
+	dev: (src: Series, len: number) => Series;
+	mom: (src: Series, len: number) => Series;
+	linreg: (src: Series, len: number, offset?: number | undefined) => Series;
+	rma: (src: Series, len: number) => Series;
+	hma: (src: Series, len: number) => Series;
+	vwma: (src: Series, volume: Series, len: number) => Series;
+};
+export interface AICompleteInput {
+	system?: string;
+	prompt: string;
+	/** Cancels the request. Clients must not serialise it into the request. */
+	signal?: AbortSignal;
+}
+/** The single seam the host implements to plug a model into SUPer-Chart. */
+export interface AIClient {
+	complete: (input: AICompleteInput) => Promise<string>;
+}
+export interface HttpAIClientOptions {
+	endpoint: string;
+	headers?: Record<string, string>;
+	/** Abort a request that takes longer (rejects with a "TimeoutError"). */
+	timeoutMs?: number;
+	/**
+	 * Map a response body to the model's text when it is none of the shapes the
+	 * client reads itself (a string, `{ text }`, `{ content: string }`, or
+	 * Anthropic's `{ content: [{ type: "text", text }] }`), e.g. OpenAI's
+	 * `{ choices }`.
+	 */
+	extract?: (data: unknown) => string;
+}
+/** An `AIClient` that POSTs `{ system, prompt }` to a host endpoint and reads back
+ * the model's text. Keeps model keys on the host/server. It rejects (instead of
+ * returning "" or "[object Object]") on an HTTP error, a body with an `error`,
+ * a body it cannot read, or empty text. */
+export declare function createHttpAIClient(opts: HttpAIClientOptions): AIClient;
+export declare const SUPERSCRIPT_SYSTEM_PROMPT: string;
+export interface AIRequestOptions {
+	signal?: AbortSignal;
+}
+/**
+ * Natural language → a SuperScript indicator (script source). The reply is
+ * compiled before it is returned: a reply that is not a valid script, or that
+ * draws nothing (prose, "", "[object Object]"), rejects with the error and the
+ * start of the reply, so it never reaches registerScriptIndicator. For a
+ * repair loop use nlToSuperScriptChecked.
+ */
+export declare function nlToSuperScript(client: AIClient, request: string, opts?: AIRequestOptions): Promise<string>;
+export interface CheckedScript {
+	/** True when the last script compiles and draws something. */
+	ok: boolean;
+	/** The last script the model returned. */
+	source: string;
+	/** Its diagnostics (errors and warnings). */
+	diagnostics: Diagnostic[];
+	/** Model calls made (1 + repairs). */
+	attempts: number;
+}
+/**
+ * nlToSuperScript with a bounded repair loop: when the script has errors (or
+ * draws nothing), the diagnostics — line, column and the offending source
+ * line — go back to the model, up to `maxRepairs` times (default 2). Each
+ * repair is another model call the host pays for; nothing retries unless the
+ * host calls this. Never throws for a bad script: read `ok`.
+ */
+export declare function nlToSuperScriptChecked(client: AIClient, request: string, opts?: AIRequestOptions & {
+	maxRepairs?: number;
+}): Promise<CheckedScript>;
+/** How analyzeChart writes the bars (set by buildChartContext); absent = the v1 format. */
+export interface ChartContextFormat {
+	pricePrecision?: number;
+	volumePrecision?: number;
+	/** IANA time zone the times are written in (default UTC). */
+	timezone?: string;
+	/** Data indexes of the visible window, [from, to). */
+	visibleFrom?: number;
+	visibleTo?: number;
+	/** Bars per row (1 = not aggregated). */
+	bucket?: number;
+	/** Bars before aggregation. */
+	sourceBars?: number;
+	/** Leading rows that are context before the visible window. */
+	contextRows?: number;
+}
+export interface ChartContext {
+	symbol: string;
+	period: string;
+	bars: Bar[];
+	/** Optional indicators already on the chart, for context. */
+	indicators?: string[];
+	/** Compact serialisation (rounded, indexed rows, aggregated). Set by buildChartContext. */
+	format?: ChartContextFormat;
+}
+/** What buildChartContext reads from a chart; a klinecharts Chart has both. */
+export interface ChartDataSource {
+	getDataList: () => readonly Bar[];
+	getVisibleRange: () => {
+		from: number;
+		to: number;
+	};
+}
+export interface SymbolLike {
+	ticker: string;
+	pricePrecision?: number | "auto";
+	volumePrecision?: number;
+}
+export interface PeriodLike {
+	multiplier: number;
+	timespan: string;
+	text?: string;
+}
+/** A SuperChart (or anything with the same getters). */
+export interface ChartProLike {
+	getChart: () => ChartDataSource | null;
+	getSymbol: () => SymbolLike;
+	getPeriod: () => PeriodLike;
+	getTimezone: () => string;
+}
+/**
+ * A `ChartWorkspace` from super-chart-web, or anything shaped like one: `buildChartContext(workspace)` reads the
+ * bars on screen from its viewport and the display time zone from its render options.
+ */
+export interface ChartWorkspaceLike {
+	getBars: (options?: {
+		limit?: number;
+	}) => readonly Bar[];
+	getSymbol: () => SymbolLike;
+	getPeriod: () => PeriodLike;
+	chart: {
+		view: {
+			getSnapshot: () => {
+				viewport: {
+					i0: number;
+					i1: number;
+				};
+			};
+		};
+		getRenderOptions?: () => {
+			timeZone?: string;
+		};
+	};
+}
+export interface ChartContextParts {
+	chart: ChartDataSource;
+	symbol: SymbolLike;
+	period: PeriodLike | string;
+	timezone?: string;
+}
+export interface ChartContextOptions {
+	/** 'visible' (default): the bars on screen; 'all'; or data indexes [from, to). */
+	range?: "visible" | "all" | {
+		from: number;
+		to: number;
+	};
+	/** Most rows to send (default 200); more bars are aggregated into OHLCV buckets. */
+	maxBars?: number;
+	/**
+	 * Bars before the range to include, labelled as context (default 0). When
+	 * rows are aggregated the context is whole rows ending at the first visible
+	 * bar: rounded up to whole rows, fewer when the data starts sooner, none
+	 * when not even one row fits or maxBars is 1.
+	 */
+	lookback?: number;
+	indicators?: string[];
+}
+/**
+ * The ChartContext for analyzeChart from a chart: the bars the user sees (not
+ * the newest 160), aggregated into at most `maxBars` OHLCV rows when zoomed
+ * out, with the symbol's precision and the chart's time zone so the prompt
+ * is short and exact. Works with a SuperChart or `{ chart, symbol, period }`
+ * around any klinecharts Chart (./lite).
+ */
+export declare function buildChartContext(source: ChartProLike | ChartWorkspaceLike | ChartContextParts, opts?: ChartContextOptions): ChartContext;
+export declare const ANALYST_SYSTEM_PROMPT = "You are a professional markets analyst embedded in a trading chart.\nBe concise and concrete. Reference price structure, key support/resistance, momentum,\nand lay out the most likely scenarios with invalidation levels. Never give financial\nadvice or position sizing \u2014 describe the chart, not what the user should do.";
+/** Analyse the candles in `ctx` (buildChartContext gives the visible ones). `question` is optional follow-up context. */
+export declare function analyzeChart(client: AIClient, ctx: ChartContext, question?: string, opts?: AIRequestOptions): Promise<string>;
+/**
+ * Register a script language and enable it on this entry. This is the only
+ * way to run anything but SuperScript through `./superscript`.
+ */
+export declare function registerLanguage(lang: ScriptLanguage): void;
+/** The language with this id, if it is enabled on this entry. */
+export declare function getLanguage(id: string): ScriptLanguage | undefined;
+/** The languages enabled on this entry (SuperScript plus any the host registered here). */
+export declare function listLanguages(): ScriptLanguage[];
+/**
+ * Compile and run a script. Throws for a language that is not enabled on this
+ * entry, including `"javascript"` unless the host registered it here.
+ */
+export declare function runScript(source: string, bars: Bar[], languageId?: string, params?: ScriptParams): ScriptResult;
+
+export {};