@mathieuc/tradingview 3.5.2 → 4.0.0-beta.1

package/README.md

@@ -1,76 +1,137 @@
-# TradingView API [![GitHub stars](https://img.shields.io/github/stars/Mathieu2301/TradingView-API.svg?style=social&label=Star&maxAge=2592000)](https://GitHub.com/Mathieu2301/TradingView-API/stargazers/)
+# TradingView-API
 
-[![Tests](https://github.com/Mathieu2301/TradingView-API/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/Mathieu2301/TradingView-API/actions/workflows/tests.yml)
-[![CodeFactor](https://www.codefactor.io/repository/github/mathieu2301/tradingview-api/badge/main)](https://www.codefactor.io/repository/github/mathieu2301/tradingview-api/overview/main)
-[![GitHub latest commit](https://img.shields.io/github/last-commit/Mathieu2301/TradingView-API)](https://GitHub.com/Mathieu2301/TradingView-API/commit/)
-[![Npm package yearly downloads](https://badgen.net/npm/dt/@mathieuc/tradingview)](https://npmjs.com/@mathieuc/tradingview)
-[![Minimum node.js version](https://badgen.net/npm/node/@mathieuc/tradingview)](https://npmjs.com/@mathieuc/tradingview)
-[![Npm package version](https://badgen.net/npm/v/@mathieuc/tradingview)](https://npmjs.com/package/@mathieuc/tradingview)
+**Build with market data, from your first chart to a running watcher.** Fetch candles and quotes, run indicators and strategies, and turn ideas into working tools. An independent community project, not an official TradingView API.
 
-Get realtime market prices and indicator values from Tradingview !
+[Get started](#get-started) · [Explore examples](examples) · [Read the data API guide](docs/data-api.md)
 
-## 🟢 Need help with your project?
+**Language:** English · [Français](docs/README.fr.md) · [Español](docs/README.es.md) · [Português](docs/README.pt.md)
 
-🚀 Click [here](https://forms.gle/qPp5RKo8L55C5oJE7) for personalized assistance on your project.
+[![Tests](https://github.com/Mathieu2301/TradingView-API/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/Mathieu2301/TradingView-API/actions/workflows/tests.yml) [![npm](https://badgen.net/npm/v/@mathieuc/tradingview)](https://www.npmjs.com/package/@mathieuc/tradingview) [![Stars](https://img.shields.io/github/stars/Mathieu2301/TradingView-API?style=social)](https://github.com/Mathieu2301/TradingView-API)
 
-## 🔵 Telegram group
+![Recorded demonstration: a candle request returns 40 daily BTC/USDT candles, visualized as a line chart](assets/readme-demo.gif)
 
-👉 To get help, exchange tips, find collaborators, developers, missions, etc...
+*An actual candle request, recorded on 2 October 2026 with the development preview (`fetchCandles`, called `getCandles` in version 4) and visualized for this demo. Prices are not live.*
 
-Join the Telegram group of the TradingView-API Community: [t.me/tradingview_api](https://t.me/tradingview_api)
+### One request, real data
 
-## Features
+> **V4 beta is currently available from this repository, not from npm.** Build the source as shown below before running this example. The latest npm release is still v3 and does not export `getCandles`.
 
-- [x] Premium features
-- [x] Automatically backtest many strategies and try many settings in a very little time
-- [x] Get drawings you made on your chart
-- [x] Works with invite-only indicators
-- [x] Unlimited simultaneous indicators
-- [x] Realtime
-- [x] Get TradingView's technical analysis
-- [x] Replay mode + Fake Replay mode (for free plan)
-- [x] Get values from a specific date range
-- [ ] TradingView socket server emulation
-- [ ] Interract with public chats
-- [ ] Get Screener top values
-- [ ] Get Hotlists
-- [ ] Get Calendar
-- IF YOU WANT A FEATURE, ASK ME !
+```js
+import { getCandles } from '@mathieuc/tradingview/data';
 
-## Possibilities
+const candles = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: 'D', count: 40 });
+console.log(candles.at(-1)); // { time, open, high, low, close, volume }
+```
+
+Prefer to start without code? The setup paths below work too.
+
+> **Version 4 is a breaking rewrite** in TypeScript, with a new API and no compatibility layer. Coming from v3? Read the [migration guide](docs/migration-v4.md). Every v3 feature is still available: see the [coverage matrix](docs/v4-coverage.md). npm versions 3.x keep the previous `Client` API; check the [npm page](https://www.npmjs.com/package/@mathieuc/tradingview) for the version you install.
+
+## Get started
+
+### 1. Molted.cloud — recommended, no local setup
+
+[Create an agent on Molted.cloud](https://molted.cloud/) and share this repository with it. Describe what you want to build; the agent can read the docs, set up a workspace, and help you get from an idea to a working project. For example, ask it to build a market-data watcher with this library. [See an example on Molted Studio](https://molted.studio/dreams/market-watch-alerts).
+
+### 2. Claude Code, Codex, or another coding assistant
+
+Open your project in your preferred coding assistant and give it the [repository link](https://github.com/Mathieu2301/TradingView-API). You can start with:
+
+> Read the TradingView-API README and the data API guide. Build the V4 beta from source, make a small example that fetches candles and watches a quote, and show me how to run it.
+
+The assistant can handle the setup, but you keep the project in your own environment.
+
+### 3. Install manually
+
+The V4 beta requires Node.js 20 or later, or Bun. **Until the V4 npm release, install it from source:**
+
+```bash
+git clone https://github.com/Mathieu2301/TradingView-API.git
+cd TradingView-API
+npm ci && npm run build
+node examples/candles.js
+# Or use Bun: bun install && bun run build && bun examples/candles.js
+```
+
+Inside this built checkout, the examples and package self-imports use the V4 API. Running `npm install @mathieuc/tradingview` or `bun add @mathieuc/tradingview` in another project currently installs **v3**, which has the old `Client` API. Do not copy the V4 imports into a project that has v3 installed.
+
+The V4 package is ESM with TypeScript declarations. CommonJS projects can `require()` it on Node 20.19+ or 22.12+, or use `await import()`.
+
+### Want to contribute?
 
-- Trading bot
-- Discord alerts
-- Hard backtest
-- Machine Learning based indicator
-- Free replay mode for all timeframes
+[Open an issue](https://github.com/Mathieu2301/TradingView-API/issues/new/choose) to discuss a feature or report a bug, or send a pull request. Questions and early ideas are welcome; you do not need a perfect reproduction to start a conversation. `npm run check` runs the type check, lint, tests, build and package smoke test.
 
-___
+## Data API
 
-## Installation
+The data API handles connections, sessions, timeouts and cleanup for you. It suits any application: scripts, servers, dashboards, bots or agents.
 
-Stable version:
+```ts
+import {
+  getCandles, watchCandles, getQuote, getIndicatorData, searchMarkets,
+} from '@mathieuc/tradingview/data';
 
-```ruby
-npm i @mathieuc/tradingview
+// One-shot: resolves with complete data, then releases everything.
+const hourly = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '60', count: 500 });
+const lastWeek = await getCandles({ symbol: 'NASDAQ:AAPL', timeframe: '15', from: new Date(Date.now() - 7 * 86_400_000) });
+const quote = await getQuote('BINANCE:BTCUSDT');
+const [market] = await searchMarkets('ethereum', { type: 'crypto' });
+
+// Watcher: keeps streaming until stopped.
+const watcher = await watchCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '1' }, {
+  onData: (candles) => console.log(candles.at(-1)?.close),
+  onError: (error) => console.error(error.code, error.message),
+});
+await watcher.stop();
+
+// Indicators and strategies (Pine scripts need an account).
+const { values } = await getIndicatorData({
+  symbol: 'BINANCE:BTCUSDT', indicator: 'STD;RSI', credentials: { session, signature },
+});
 ```
 
-Last version:
+| Need | Function |
+| --- | --- |
+| Candles: latest bars, deep history, date ranges, Heikin Ashi/Renko/... | `getCandles`, `watchCandles` |
+| Quotes: last price, change, bid/ask, volume... | `getQuote`, `getQuotes`, `watchQuotes` |
+| Indicator values, drawings and strategy reports | `getIndicatorData`, `watchIndicator` |
+| Symbol metadata | `getSymbolInfo` |
+| Search and ratings | `searchMarkets`, `searchIndicators`, `getTechnicalAnalysis` |
+
+Websocket data functions accept `timeoutMs`, an `AbortSignal`, account `credentials`, and an optional shared `client`. HTTP lookups accept an `AbortSignal` through their options. Errors are `TradingViewError`s with a `code` such as `SYMBOL_ERROR`, `TIMEOUT` or `STUDY_ERROR`. Read the [data API guide](docs/data-api.md) for every option.
+
+## Low-level API
+
+For full control (several charts and studies on one connection, replay mode, raw packets), use the client and sessions directly:
+
+```ts
+import { TradingViewClient, getIndicator } from '@mathieuc/tradingview';
+
+const client = new TradingViewClient({ credentials: { session, signature } }); // Credentials are optional
+const chart = client.createChart();
+
+chart.on('update', () => console.log(chart.lastCandle?.close));
+chart.on('error', (error) => console.error(error.message));
+chart.setMarket('BINANCE:BTCUSDT', { timeframe: '60', count: 300 });
+
+const supertrend = chart.createStudy(await getIndicator('STD;Supertrend'));
+supertrend.on('update', () => console.log(supertrend.values.at(-1)));
 
-```ruby
-npm i github:Mathieu2301/TradingView-API
+// When your application is finished:
+await client.close();
 ```
 
-## Examples
+The [low-level API reference](docs/low-level-api.md) covers charts, replay, studies, quotes, account and layout functions, Pine permissions, custom transports and protocol helpers. The [examples](examples) show each feature.
 
-You can find all the examples and snippets in `./examples` folder.
+## Accounts and limits
 
-## Before opening an issue
+Without an account, TradingView serves limited data: shorter intraday history, no Pine studies, and possibly delayed or substitute feeds. With your `sessionid` and `sessionid_sign` cookies (`credentials`), you get what your account can access. Keep them in environment variables or a secret store; never put them in source files, issues or prompts.
 
-Please look at examples and previously resolved issues before opening a new one. I can't help everyone (especially for questions that are not library related but JavaScript related). Thank you for your understanding.
-___
+## Project links
 
-## Problems
+- [GitHub repository](https://github.com/Mathieu2301/TradingView-API)
+- [Trendshift community highlight](https://trendshift.io/repositories/26416)
+- [npm package](https://www.npmjs.com/package/@mathieuc/tradingview)
+- [Examples](examples)
+- [Report a bug or ask for a feature](https://github.com/Mathieu2301/TradingView-API/issues/new/choose)
 
- If you have errors in console or unwanted behavior,
- please create an issue [here](https://github.com/Mathieu2301/Tradingview-API/issues).
+TradingView is a trademark of its respective owner. This project is not affiliated with or endorsed by TradingView. Check your data provider's terms and applicable market-data permissions for your use case.

package/dist/chart/chart-session.d.ts

@@ -0,0 +1,114 @@
+import type { TradingViewClient } from '../client/client.js';
+import { TradingViewError } from '../errors.js';
+import { Emitter } from '../events.js';
+import type { Indicator } from '../indicators/index.js';
+import { Study } from './study.js';
+import { type Adjustment, type Candle, type ChartType, type ChartTypeInputs, type SymbolInfo, type Timeframe, type Timezone, type TradingSession } from './types.js';
+export interface MarketOptions {
+    /** Bar resolution. Default: `D`. */
+    timeframe?: Timeframe;
+    /**
+     * Number of bars to load when the series is created. Default: 100.
+     * Negative values load bars *after* `to` instead of before it.
+     * Only the first `setMarket` of a chart creates the series; later calls
+     * keep the loaded bar count (use `fetchMore` or a new chart).
+     */
+    count?: number;
+    /** Reference time (Unix seconds) of the last bar to load. Default: now. */
+    to?: number;
+    /** Price adjustment. Default: `splits`. */
+    adjustment?: Adjustment;
+    /** Back-adjust continuous futures contracts. */
+    backAdjustment?: boolean;
+    /** Trading session (`regular` or `extended`). */
+    session?: TradingSession;
+    /** Convert prices to a currency, e.g. `EUR`. */
+    currency?: string;
+    /** Custom bar type (Heikin Ashi, Renko...). */
+    type?: ChartType;
+    /** Inputs for the custom bar type. */
+    inputs?: ChartTypeInputs;
+    /** Starts replay mode at this Unix time (seconds). */
+    replay?: number;
+}
+/** `series_completed` details. */
+export interface SeriesCompletedInfo {
+    /** `streaming` for live data, `replay` in replay mode. */
+    status: 'streaming' | 'replay' | (string & {});
+    /**
+     * Set when no more history can be loaded: `end` (start of history) or
+     * `limit` (account limit).
+     */
+    dataCompleted?: 'end' | 'limit' | (string & {});
+    /** Request turnaround ID (`s1`, `s2`...). */
+    turnaround: string;
+    raw: unknown;
+}
+export interface ChartEvents {
+    [event: string]: unknown[];
+    /** Symbol metadata was resolved. */
+    symbolLoaded: [info: SymbolInfo];
+    /** Bars or studies changed. `changes` lists `$prices` and/or study IDs. */
+    update: [changes: string[]];
+    /** The server started loading bars. */
+    seriesLoading: [];
+    /** The requested bars were loaded. Realtime updates continue afterwards. */
+    seriesCompleted: [info: SeriesCompletedInfo];
+    /** The replay session is ready. */
+    replayLoaded: [instanceId: string];
+    /** The replay cursor moved (Unix seconds). */
+    replayPoint: [time: number];
+    /** Resolutions reported by the replay server. */
+    replayResolution: [resolution: string, stepResolution: string];
+    /** The replay reached the present. */
+    replayEnd: [];
+    error: [error: TradingViewError];
+}
+/**
+ * A chart: one symbol series plus any number of studies, with optional
+ * replay mode. Create it with `client.createChart()`.
+ */
+export declare class ChartSession extends Emitter<ChartEvents> {
+    #private;
+    readonly id: string;
+    readonly replayId: string;
+    readonly client: TradingViewClient;
+    constructor(client: TradingViewClient);
+    /** Loaded bars, oldest first. */
+    get candles(): Candle[];
+    /** Most recent bar. */
+    get lastCandle(): Candle | undefined;
+    /** Symbol metadata, once resolved. */
+    get symbolInfo(): SymbolInfo | undefined;
+    /** Current timeframe. */
+    get timeframe(): Timeframe;
+    /** Current series ID (`ser_1`, `ser_2`...), or undefined before `setMarket`. */
+    get seriesId(): string | undefined;
+    /** True when the chart is in replay mode. */
+    get isReplay(): boolean;
+    /** True after `delete()` or when the connection closed. */
+    get isDeleted(): boolean;
+    /** Studies currently on this chart. */
+    get studies(): Study[];
+    /** Loads a symbol, optionally with a custom bar type or in replay mode. */
+    setMarket(symbol: string, options?: MarketOptions): void;
+    /** Changes the timeframe of the loaded symbol, keeping studies. */
+    setTimeframe(timeframe: Timeframe): void;
+    /** Changes the chart timezone. */
+    setTimezone(timezone: Timezone): void;
+    /**
+     * Loads more history. Positive values load older bars; negative values
+     * load newer bars after a past `to` reference.
+     */
+    fetchMore(count?: number): void;
+    /** Moves the replay forward by `count` bars. */
+    replayStep(count?: number): Promise<void>;
+    /** Plays the replay automatically, one bar every `intervalMs`. */
+    replayStart(intervalMs?: number): Promise<void>;
+    /** Pauses automatic replay. */
+    replayStop(): Promise<void>;
+    /** Adds a study (Pine or built-in indicator) to this chart. */
+    createStudy(indicator: Indicator): Study;
+    /** Deletes the chart (and its replay session). Idempotent. */
+    delete(): void;
+}

package/dist/chart/chart-session.js

@@ -0,0 +1,339 @@
+import { TradingViewError } from '../errors.js';
+import { Emitter } from '../events.js';
+import { createSessionId } from '../protocol/ids.js';
+import { Study } from './study.js';
+import { CHART_TYPE_STUDIES, } from './types.js';
+/**
+ * A chart: one symbol series plus any number of studies, with optional
+ * replay mode. Create it with `client.createChart()`.
+ */
+export class ChartSession extends Emitter {
+    id = createSessionId('cs');
+    replayId = createSessionId('rs');
+    client;
+    #candles = new Map();
+    /** Bar index (`i`) → bar time, used to position study graphics. */
+    #barIndexes = new Map();
+    #studies = new Map();
+    #replayRequests = new Map();
+    #symbolInfo;
+    #seriesCount = 0;
+    #seriesCreated = false;
+    #turnaround = 0;
+    #timeframe = 'D';
+    #replayMode = false;
+    #deleted = false;
+    constructor(client) {
+        super();
+        this.client = client;
+        const chartHandler = {
+            onPacket: (packet) => this.#onChartPacket(packet),
+            onClose: (error, expected) => this.#onClientClose(error, expected),
+        };
+        client.registerSession(this.id, chartHandler);
+        client.registerSession(this.replayId, { onPacket: (packet) => this.#onReplayPacket(packet) });
+        client.send('chart_create_session', [this.id]);
+    }
+    /** Loaded bars, oldest first. */
+    get candles() {
+        return [...this.#candles.values()].sort((a, b) => a.time - b.time);
+    }
+    /** Most recent bar. */
+    get lastCandle() {
+        let last;
+        for (const candle of this.#candles.values())
+            if (!last || candle.time > last.time)
+                last = candle;
+        return last;
+    }
+    /** Symbol metadata, once resolved. */
+    get symbolInfo() {
+        return this.#symbolInfo;
+    }
+    /** Current timeframe. */
+    get timeframe() {
+        return this.#timeframe;
+    }
+    /** Current series ID (`ser_1`, `ser_2`...), or undefined before `setMarket`. */
+    get seriesId() {
+        return this.#seriesCount ? `ser_${this.#seriesCount}` : undefined;
+    }
+    /** True when the chart is in replay mode. */
+    get isReplay() {
+        return this.#replayMode;
+    }
+    /** True after `delete()` or when the connection closed. */
+    get isDeleted() {
+        return this.#deleted;
+    }
+    /** Studies currently on this chart. */
+    get studies() {
+        return [...this.#studies.values()];
+    }
+    /** Loads a symbol, optionally with a custom bar type or in replay mode. */
+    setMarket(symbol, options = {}) {
+        this.#assertAlive();
+        if (!symbol)
+            throw new TradingViewError('INVALID_ARGUMENT', 'A symbol is required');
+        this.#candles.clear();
+        this.#barIndexes.clear();
+        this.#symbolInfo = undefined;
+        const timeframe = options.timeframe ?? 'D';
+        if (this.#replayMode) {
+            this.#replayMode = false;
+            this.#rejectReplayRequests(new TradingViewError('INVALID_STATE', 'Replay session replaced'));
+            this.client.send('replay_delete_session', [this.replayId]);
+        }
+        const symbolInit = {
+            symbol,
+            adjustment: options.adjustment ?? 'splits',
+        };
+        if (options.backAdjustment)
+            symbolInit.backadjustment = 'default';
+        if (options.session)
+            symbolInit.session = options.session;
+        if (options.currency)
+            symbolInit['currency-id'] = options.currency;
+        if (options.replay !== undefined) {
+            this.#replayMode = true;
+            this.client.send('replay_create_session', [this.replayId]);
+            this.client.send('replay_add_series', [
+                this.replayId, 'req_replay_addseries', `=${JSON.stringify(symbolInit)}`, timeframe,
+            ]);
+            this.client.send('replay_reset', [this.replayId, 'req_replay_reset', options.replay]);
+        }
+        let chartInit = symbolInit;
+        if (options.type || options.replay !== undefined) {
+            chartInit = { symbol: symbolInit };
+            if (options.replay !== undefined)
+                chartInit.replay = this.replayId;
+            if (options.type) {
+                const study = CHART_TYPE_STUDIES[options.type];
+                if (!study)
+                    throw new TradingViewError('INVALID_ARGUMENT', `Unknown chart type '${options.type}'`);
+                chartInit.type = study;
+                chartInit.inputs = { ...options.inputs };
+            }
+        }
+        this.#seriesCount += 1;
+        this.client.send('resolve_symbol', [this.id, `ser_${this.#seriesCount}`, `=${JSON.stringify(chartInit)}`]);
+        this.#sendSeries(timeframe, options.count ?? 100, options.to);
+    }
+    /** Changes the timeframe of the loaded symbol, keeping studies. */
+    setTimeframe(timeframe) {
+        this.#assertAlive();
+        if (!this.#seriesCount) {
+            throw new TradingViewError('INVALID_STATE', 'Please set the market before setting the timeframe');
+        }
+        this.#candles.clear();
+        this.#barIndexes.clear();
+        this.#sendSeries(timeframe, 100);
+    }
+    #sendSeries(timeframe, count, to) {
+        this.#timeframe = timeframe;
+        this.#turnaround += 1;
+        const range = to === undefined ? count : ['bar_count', to, count];
+        this.client.send(this.#seriesCreated ? 'modify_series' : 'create_series', [
+            this.id, '$prices', `s${this.#turnaround}`, `ser_${this.#seriesCount}`, timeframe,
+            // modify_series only accepts an empty range: the bar count is kept.
+            this.#seriesCreated ? '' : range,
+        ]);
+        this.#seriesCreated = true;
+    }
+    /** Changes the chart timezone. */
+    setTimezone(timezone) {
+        this.#assertAlive();
+        this.client.send('switch_timezone', [this.id, timezone]);
+    }
+    /**
+     * Loads more history. Positive values load older bars; negative values
+     * load newer bars after a past `to` reference.
+     */
+    fetchMore(count = 1) {
+        this.#assertAlive();
+        this.client.send('request_more_data', [this.id, '$prices', count]);
+    }
+    /** Moves the replay forward by `count` bars. */
+    replayStep(count = 1) {
+        return this.#replayRequest('replay_step', 'rsq_step', [count]);
+    }
+    /** Plays the replay automatically, one bar every `intervalMs`. */
+    replayStart(intervalMs = 1000) {
+        return this.#replayRequest('replay_start', 'rsq_start', [intervalMs]);
+    }
+    /** Pauses automatic replay. */
+    replayStop() {
+        return this.#replayRequest('replay_stop', 'rsq_stop', []);
+    }
+    #replayRequest(method, prefix, params) {
+        if (this.#deleted)
+            return Promise.reject(new TradingViewError('INVALID_STATE', 'The chart is deleted'));
+        if (!this.#replayMode) {
+            return Promise.reject(new TradingViewError('INVALID_STATE', 'No replay session: use setMarket(symbol, { replay })'));
+        }
+        const requestId = createSessionId(prefix);
+        return new Promise((resolve, reject) => {
+            this.#replayRequests.set(requestId, { resolve, reject });
+            this.client.send(method, [this.replayId, requestId, ...params]);
+        });
+    }
+    /** Adds a study (Pine or built-in indicator) to this chart. */
+    createStudy(indicator) {
+        this.#assertAlive();
+        const bridge = {
+            chartId: this.id,
+            send: (method, params) => this.client.send(method, params),
+            barsBack: () => this.#barsBack(),
+            log: (...args) => this.client.log(...args),
+            unregister: (id) => { this.#studies.delete(id); },
+        };
+        const study = new Study(bridge, indicator);
+        this.#studies.set(study.id, study);
+        study.create();
+        return study;
+    }
+    /** Deletes the chart (and its replay session). Idempotent. */
+    delete() {
+        if (this.#deleted)
+            return;
+        if (!this.client.isClosed) {
+            if (this.#replayMode)
+                this.client.send('replay_delete_session', [this.replayId]);
+            this.client.send('chart_delete_session', [this.id]);
+        }
+        this.#dispose(new TradingViewError('INVALID_STATE', 'The chart was deleted'));
+    }
+    #dispose(error, notify = false) {
+        this.#deleted = true;
+        this.#replayMode = false;
+        this.client.unregisterSession(this.id);
+        this.client.unregisterSession(this.replayId);
+        this.#rejectReplayRequests(error);
+        for (const study of this.#studies.values())
+            study.dispose(notify ? error : undefined);
+        this.#studies.clear();
+    }
+    #onClientClose(error, expected) {
+        if (this.#deleted)
+            return;
+        this.#dispose(error, !expected);
+        if (!expected)
+            this.emit('error', error);
+    }
+    #assertAlive() {
+        if (this.#deleted)
+            throw new TradingViewError('INVALID_STATE', 'The chart is deleted');
+    }
+    #rejectReplayRequests(error) {
+        for (const request of this.#replayRequests.values())
+            request.reject(error);
+        this.#replayRequests.clear();
+    }
+    /** Bar index → bars back from the most recent loaded bar. */
+    #barsBack() {
+        const result = new Map();
+        [...this.#barIndexes.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .forEach(([index], position) => result.set(index, position));
+        return result;
+    }
+    #onChartPacket(packet) {
+        this.client.log('chart', this.id, packet);
+        const [, target] = packet.p;
+        if (typeof target === 'string' && this.#studies.has(target)) {
+            this.#studies.get(target)?.onPacket(packet);
+            return;
+        }
+        switch (packet.m) {
+            case 'symbol_resolved':
+                this.#symbolInfo = { series_id: target, ...packet.p[2] };
+                this.emit('symbolLoaded', this.#symbolInfo);
+                return;
+            case 'timescale_update':
+            case 'du': {
+                const data = (packet.p[1] ?? {});
+                const changes = [];
+                for (const key of Object.keys(data)) {
+                    changes.push(key);
+                    if (key === '$prices')
+                        this.#updateCandles(data.$prices);
+                    else
+                        this.#studies.get(key)?.onData(data[key]);
+                }
+                this.emit('update', changes);
+                return;
+            }
+            case 'series_loading':
+                this.emit('seriesLoading');
+                return;
+            case 'series_completed': {
+                const details = (packet.p[4] ?? {});
+                this.emit('seriesCompleted', {
+                    status: String(packet.p[2] ?? ''),
+                    dataCompleted: details.data_completed,
+                    turnaround: String(packet.p[3] ?? ''),
+                    raw: packet.p,
+                });
+                return;
+            }
+            case 'symbol_error':
+                this.emit('error', new TradingViewError('SYMBOL_ERROR', `(${String(target)}) Symbol error: ${String(packet.p[2])}`, {
+                    details: packet.p,
+                }));
+                return;
+            case 'series_error':
+                this.emit('error', new TradingViewError('SERIES_ERROR', `Series error: ${String(packet.p[3])}`, {
+                    details: packet.p,
+                }));
+                return;
+            case 'critical_error':
+                this.emit('error', new TradingViewError('CRITICAL_ERROR', `Critical error: ${String(packet.p[1])}`, {
+                    details: packet.p,
+                }));
+                return;
+            default:
+        }
+    }
+    #updateCandles(prices) {
+        for (const bar of prices?.s ?? []) {
+            const [time, open, high, low, close, volume] = bar.v;
+            this.#barIndexes.set(bar.i, time);
+            this.#candles.set(time, {
+                time, open, high, low, close, volume: volume ?? 0,
+            });
+        }
+    }
+    #onReplayPacket(packet) {
+        this.client.log('replay', this.replayId, packet);
+        switch (packet.m) {
+            case 'replay_ok': {
+                const requestId = String(packet.p[1]);
+                this.#replayRequests.get(requestId)?.resolve();
+                this.#replayRequests.delete(requestId);
+                return;
+            }
+            case 'replay_instance_id':
+                this.emit('replayLoaded', String(packet.p[1]));
+                return;
+            case 'replay_point':
+                this.emit('replayPoint', Number(packet.p[1]));
+                return;
+            case 'replay_resolutions':
+                this.emit('replayResolution', String(packet.p[1]), String(packet.p[2]));
+                return;
+            case 'replay_data_end':
+                this.emit('replayEnd');
+                return;
+            case 'critical_error':
+            case 'replay_error': {
+                const error = new TradingViewError('CRITICAL_ERROR', `Replay error: ${String(packet.p[1])}`, {
+                    details: packet.p,
+                });
+                this.#rejectReplayRequests(error);
+                this.emit('error', error);
+                return;
+            }
+            default:
+        }
+    }
+}