@mathieuc/tradingview 3.5.2 → 4.0.0-beta.1

package/docs/data-api.md

@@ -0,0 +1,285 @@
+# Data API guide
+
+[README](../README.md) · [Low-level API](low-level-api.md) · [Migrating from v3](migration-v4.md) · [Examples](../examples)
+
+**V4 beta is currently available from this repository only; the latest npm release is still v3.** Build this checkout before running the examples below.
+
+The data API is the simplest way to use this library, in any application. Each function opens what it needs, waits for complete data, and releases every websocket session (and the connection it opened) before returning, including on errors, timeouts and cancellation.
+
+```ts
+import { getCandles, watchQuotes } from '@mathieuc/tradingview/data';
+```
+
+Everything here is also exported from the root entry (`@mathieuc/tradingview`).
+
+| Function | Returns |
+| --- | --- |
+| `getCandles(query)` | Candles, oldest first |
+| `watchCandles(query, handlers)` | A watcher streaming candle snapshots |
+| `getQuote(query)` / `getQuotes(query)` | Current quote(s) |
+| `watchQuotes(query, handlers)` | A watcher streaming quotes |
+| `getSymbolInfo(query)` | Symbol metadata (exchange, currency, session...) |
+| `getIndicatorData(query)` | Indicator values, drawings and strategy report |
+| `watchIndicator(query, handlers)` | A watcher streaming indicator results |
+| `searchMarkets(text, options?)` | Markets matching a text |
+| `searchIndicators(text, options?)` | Built-in and community indicators |
+| `getTechnicalAnalysis(symbol, options?)` | TradingView technical ratings |
+
+## Candles
+
+```ts
+const candles = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '60', count: 500 });
+const last = candles.at(-1); // { time, open, high, low, close, volume }
+```
+
+`time` is the bar open time in Unix **seconds**. `getCandles('BINANCE:BTCUSDT')` is a shorthand for 100 daily candles.
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `symbol` | required | Exchange-qualified symbol: `BINANCE:BTCUSDT`, `NASDAQ:AAPL`, `FX:EURUSD`... Use `searchMarkets` to find one. |
+| `timeframe` | `'D'` | `1`, `5`, `15`, `60`, `240` (minutes), `D`, `W`, `M`, `1S` (seconds)... |
+| `count` | `100` | Number of most recent bars. Larger counts are loaded in batches automatically (deep history). |
+| `from` | | `Date` or Unix seconds. Loads every bar from this time (deep history); `count` is then ignored. |
+| `to` | now | `Date` or Unix seconds: newest bar time. |
+| `maxCount` | `20000` | Safety cap for `from` ranges. |
+| `chartType` | | `HeikinAshi`, `Renko`, `LineBreak`, `Kagi`, `PointAndFigure` or `Range`. |
+| `chartInputs` | | Inputs for `chartType`, e.g. `{ boxSize: 3, style: 'ATR', atrLength: 14 }`. |
+| `currency` | | Convert prices, e.g. `EUR`. |
+| `session` | | `regular` or `extended`. |
+| `adjustment` | `'splits'` | `splits`, `dividends` or `none`. |
+| `backAdjustment` | | Back-adjust continuous futures. |
+| `timezone` | | Chart timezone (affects daily and longer bar alignment). |
+| `credentials`, `client`, `clientOptions`, `timeoutMs`, `signal` | | See [Connections, timeouts and cancellation](#connections-timeouts-and-cancellation). |
+
+History stops early, without error, when the server has no more bars (`series_completed` reports `data_completed: "end"` or `"limit"`). Anonymous access is limited: in our tests, about 7 000 one-minute bars, and reference times (`to`) in the past were capped. An empty result rejects with `NO_DATA`; when the server reported a limit, the message says so.
+
+## Watching candles
+
+```ts
+const watcher = await watchCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '1', count: 50 }, {
+  onData(candles) {
+    console.log(candles.at(-1)?.close);
+  },
+  onError(error) {
+    console.error(error.code, error.message);
+  },
+});
+
+// ...later
+await watcher.stop(); // Idempotent
+```
+
+- The promise resolves once the initial history is loaded; `onData` has already received it.
+- Each snapshot is a frozen array of the `count` most recent bars, oldest first.
+- `watcher.latest` holds the last snapshot, `watcher.symbolInfo` the symbol metadata.
+- `watcher.closed` resolves when the watcher stops: after `stop()`, an aborted `signal`, or a fatal error.
+- Errors before start-up reject the promise. Afterwards they go to `onError`; fatal ones (disconnection, symbol or series errors) also stop the watcher. There is no automatic reconnection: start a new watcher when `closed` resolves if you need one.
+
+`watchCandles` accepts the same chart options as `getCandles`, except `from`, `to` and `maxCount`.
+
+## Quotes
+
+```ts
+const quote = await getQuote('BINANCE:BTCUSDT');
+console.log(quote.lp, quote.chp); // Last price, change in percent
+
+const quotes = await getQuotes({ symbols: ['NASDAQ:AAPL', 'FX:EURUSD'], fields: 'price' });
+console.log(quotes['NASDAQ:AAPL'].lp);
+```
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `symbol` / `symbols` | required | One symbol, or a non-empty list (duplicates are ignored). |
+| `fields` | `'all'` | `all`, `price` (`lp` only), or a list such as `['lp', 'bid', 'ask', 'volume']`. |
+| `session` | `'regular'` | `regular` or `extended`. |
+
+A quote contains the fields TradingView sent: `lp`, `lp_time`, `ch`, `chp`, `bid`, `ask`, `volume`, `open_price`, `high_price`, `low_price`, `prev_close_price`, `description`, `currency_code`... An unknown symbol rejects with `QUOTE_ERROR`.
+
+```ts
+const watcher = await watchQuotes({ symbols: ['BINANCE:BTCUSDT', 'BINANCE:ETHUSDT'] }, {
+  onData(symbol, quote, changes) {
+    console.log(symbol, quote.lp, changes);
+  },
+  onError: console.error,
+});
+console.log(watcher.latest); // Latest quote per symbol
+await watcher.stop();
+```
+
+`watchQuotes` resolves once every symbol has loaded or failed. Failing symbols are reported to `onError` and the others keep streaming; if all fail, the promise rejects.
+
+## Symbol information
+
+```ts
+const info = await getSymbolInfo('NASDAQ:AAPL');
+console.log(info.description, info.currency_code, info.timezone, info.session, info.pricescale);
+```
+
+Anonymous sessions may be served by a substitute feed: for `NASDAQ:AAPL`, `full_name` can be `BATS:AAPL` while `pro_name` stays `NASDAQ:AAPL`.
+
+## Indicators and strategies
+
+```ts
+const rsi = await getIndicatorData({
+  symbol: 'BINANCE:BTCEUR',
+  timeframe: '60',
+  indicator: 'STD;RSI',
+  inputs: { Length: 21 },
+  credentials, // Pine scripts need an account
+});
+console.log(rsi.values.at(-1)); // { $time, RSI: 54.2, ... }
+```
+
+`indicator` accepts:
+
+- a script ID: `STD;RSI` (built-in Pine), `PUB;xxxx` (community), `USER;xxxx` (private); use `searchIndicators` to find IDs, and `version` to pin a version;
+- a built-in study type: `Volume@tv-basicstudies-241`, `VbPFixed@tv-basicstudies-241!`... (works without an account);
+- a `PineIndicator` or `BuiltInIndicator` instance (it is copied, never modified).
+
+`inputs` sets Pine inputs (by input ID `in_0`, number, inline name or internal ID, with type and option validation) or built-in options.
+
+The result contains:
+
+| Field | Description |
+| --- | --- |
+| `indicator` | The indicator definition used. |
+| `candles` | Chart bars, oldest first. |
+| `values` | One row per bar: `$time` plus one key per plot (unnamed or duplicate plots are `plot_N`). The server may compute a few rows before the first returned candle. |
+| `graphics` | Drawings: `labels`, `lines`, `boxes`, `tables` (with `cells`), `polygons`, `horizLines`, `horizHists`, and `raw`. X positions are bars back from the latest loaded bar. |
+| `strategyReport` | For Pine strategies: `performance`, `trades` (most recent first), `history` (equity, drawdown, buy & hold), `currency`, `settings`. Empty for studies. |
+
+Without an account, TradingView refuses Pine studies ("maximum number of studies per chart"): the call rejects with `STUDY_ERROR`. Built-in studies work.
+
+`watchIndicator(query, { onData, onError })` streams the same result on every study update; `watcher.latest` holds the last one.
+
+### Strategy totals and open positions
+
+```ts
+import { summarizeStrategyReport } from '@mathieuc/tradingview/data';
+
+const summary = summarizeStrategyReport(result.strategyReport);
+// tradeRecordCount, closedTradeCount, openTradeCount,
+// closedNetProfit, openPnL, totalPnL, currency
+```
+
+Trade records can include open positions with a current exit valuation. An `exit`
+object does **not** establish that a trade is closed. The summary uses reported
+`performance.all.totalTrades` and `totalOpenTrades`, never the record count, for
+closed/open counts. It does not assign a closed/open status to individual records.
+Counts may differ from the available records in a partial report.
+
+`totalPnL` is closed net profit plus open PnL, in the report currency. Missing or
+non-finite values remain `undefined`; a missing open PnL is not assumed to be zero.
+Raw percentage/fraction fields are not rescaled. History series, including buy &
+hold, are retained independently even when no equity series is provided. Updates
+replace supplied arrays and retain omitted series; an empty array clears a series.
+
+Malformed trade lists (a non-array or non-object records) raise `PARSE_ERROR`
+before any part of that report is applied. Studies emit this error for both plain
+and compressed reports. Omitted trade lists retain previous records; `[]` clears them.
+This is structural validation, not full validation of every trade field.
+
+These offline checks validate report decoding and normalization, not fresh-client
+access, Replay playback, export entitlement or Deep Backtesting availability.
+
+In a Basic-account UI check on October 3, 2026, both strategy trade CSV export and
+strategy report XLSX export opened an upgrade prompt recommending Essential.
+No successful export was verified. These are TradingView UI entitlements, not
+library export methods or a guarantee about other accounts. Deep Backtesting is
+separate and was blocked by a Premium upgrade prompt in that session.
+
+### Complete strategy report example
+
+See [strategy-report.js](../examples/strategy-report.js) for a bounded, executable
+public-strategy → trade-records → PnL-summary workflow. Run it from a repository
+checkout after building:
+
+```bash
+node --env-file=.env examples/strategy-report.js
+```
+
+It uses the account cookies from `.env`, runs a public Supertrend strategy and
+closes its connection automatically. It places no orders. Trade records are
+most recent first and can include open positions with current exit valuations;
+use the reported aggregate counts rather than inferring closure from an exit.
+Missing summary fields remain `undefined`, not zero. `count` selects returned
+candles, not a guaranteed exact strategy backtest window. Basic was sufficient
+for the tested symbol/timeframe; UI exports and Deep Backtesting have separate
+subscription requirements.
+
+
+## Search and technical analysis
+
+```ts
+const markets = await searchMarkets('BINANCE:BTC', { type: 'crypto' });
+// [{ id: 'BINANCE:BTCUSDT', exchange, fullExchange, symbol, description, type, currency, country }, ...]
+
+const indicators = await searchIndicators('RSI');
+// [{ id: 'STD;RSI', version, name, author, image, source, type, access }, ...]
+
+const ratings = await getTechnicalAnalysis('BINANCE:BTCUSDT');
+// { '1': { All, MA, Other }, '5': ..., '1D': ..., '1W': ..., '1M': ... } or null
+```
+
+`searchMarkets` options: `type` (`stock`, `crypto`, `forex`, `futures`, `index`, `cfd`, `economic`...), `exchange`, `offset` (pagination). Ratings range from -2 (strong sell) to 2 (strong buy).
+
+## Connections, timeouts and cancellation
+
+Websocket data functions accept:
+
+| Option | Description |
+| --- | --- |
+| `timeoutMs` | Default 15 000. One-shot functions: whole call. Watchers: until start-up. Rejects with `TIMEOUT`. Raise it for deep history. |
+| `signal` | An `AbortSignal`. Aborting rejects with `ABORTED` (or stops a running watcher). |
+| `credentials` | `{ session, signature }`: your `sessionid` and `sessionid_sign` cookies, for data your account can access. |
+| `clientOptions` | Options for the connection opened by the call (`server`, `transport`, `debug`, `fetch`...). |
+| `client` | Reuse an open `TradingViewClient`. The call only removes its own sessions and leaves the connection open. Useful for many calls in a row. |
+
+```ts
+import { TradingViewClient, getCandles, getQuote } from '@mathieuc/tradingview';
+
+const client = new TradingViewClient({ credentials });
+try {
+  const [candles, quote] = await Promise.all([
+    getCandles({ symbol: 'BINANCE:BTCUSDT', client }),
+    getQuote({ symbol: 'BINANCE:BTCUSDT', client }),
+  ]);
+} finally {
+  await client.close();
+}
+```
+
+Keep credentials in environment variables or a secret store; never put them in source files, issues or prompts.
+
+## Alternate candle providers
+
+The V4 data API remains usable with a source other than TradingView. Implement `MarketDataProvider.watchCandles(query, handlers)`; its worker exposes `latest` and an idempotent `stop()`. Pass the provider to `getCandles(query, provider)` for a one-shot snapshot or `watchCandles(query, handlers, provider)` for streaming. The provider controls its own network access and must resolve only after its first usable snapshot.
+
+```ts
+import { getCandles, type MarketDataProvider } from '@mathieuc/tradingview/data';
+
+declare const myProvider: MarketDataProvider;
+const candles = await getCandles({ symbol: 'CUSTOM:ASSET' }, myProvider);
+```
+
+`TradingViewProvider` implements the same contract and can carry default connection options. The regular `getCandles(query)` and `watchCandles(query, handlers)` calls use TradingView directly, so no provider setup is needed.
+
+## Errors
+
+Every failure is a `TradingViewError` with a `code`:
+
+| Code | Meaning |
+| --- | --- |
+| `INVALID_ARGUMENT` | Invalid query (checked before connecting). |
+| `SYMBOL_ERROR` | Unknown symbol. |
+| `SERIES_ERROR` | Bars refused (for example a chart type or timeframe your account cannot use). |
+| `CRITICAL_ERROR` | Command refused (invalid timeframe, timezone...). |
+| `STUDY_ERROR` | Indicator failed or not allowed. |
+| `QUOTE_ERROR` | Quote refused for a symbol. |
+| `NO_DATA` | No bars in the requested range. |
+| `AUTH_ERROR` | Credentials rejected. |
+| `NOT_FOUND` | Unknown indicator, layout... |
+| `TIMEOUT`, `ABORTED`, `DISCONNECTED`, `CONNECTION_ERROR`, `PROTOCOL_ERROR`, `HTTP_ERROR`, `PARSE_ERROR` | Transport and decoding failures. |
+| `CALLBACK_ERROR` | A watcher callback threw; the stream remains active. |
+
+`error.details` keeps the raw server payload when there is one.

package/docs/low-level-api.md

@@ -0,0 +1,213 @@
+# Low-level API
+
+[README](../README.md) · [Data API](data-api.md) · [Migrating from v3](migration-v4.md) · [Examples](../examples)
+
+Use the low-level API when you need full control: several charts and studies on one connection, replay mode, raw protocol access, or long-lived sessions you manage yourself. The [data API](data-api.md) is built on it.
+
+```ts
+import { TradingViewClient, BuiltInIndicator, getIndicator } from '@mathieuc/tradingview';
+```
+
+## Events
+
+Clients, charts, studies, quote sessions and quote subscriptions share one typed event API:
+
+```ts
+const off = emitter.on('update', (changes) => {}); // Returns an unsubscribe function
+emitter.once('symbolLoaded', (info) => {});
+emitter.off('update', listener);
+emitter.onAny((event, ...args) => {}); // Every event
+```
+
+An `error` event without any listener is written to `console.error`. A throwing listener never breaks the protocol state: its exception is re-thrown asynchronously.
+
+## Client
+
+```ts
+const client = new TradingViewClient({
+  credentials: { session: process.env.SESSION, signature: process.env.SIGNATURE }, // Optional
+});
+await client.ready; // Optional: packets are queued until the connection is ready
+// ...
+await client.close();
+```
+
+| Option | Description |
+| --- | --- |
+| `credentials` | `sessionid` / `sessionid_sign` cookies. The client loads the account (`getUser`) to get the websocket auth token. Without credentials, the session is anonymous. |
+| `authToken` | Websocket auth token (`User.authToken`), to skip the account lookup. |
+| `location` | Page used for the account lookup, e.g. `https://fr.tradingview.com/`. |
+| `server` | `data` (default), `prodata` (paid accounts) or `widgetdata`. |
+| `headers` | Extra websocket headers. |
+| `debug` | `true` logs traffic with `console.log`; a function receives log arguments. |
+| `transport` | Custom websocket transport (proxy, other library, tests). See [Transport](#transport). |
+| `fetch` | Custom `fetch` for the account lookup. |
+| `connectTimeoutMs` | Time allowed to open and authenticate. Default 20 000. |
+
+| Member | Description |
+| --- | --- |
+| `ready` | Promise resolved once the auth token is sent; rejects on credential, connection or timeout failure. |
+| `isOpen`, `isAuthenticated`, `isClosed` | State. |
+| `serverInfo` | Server greeting (`session_id`, `release`, `protocol`...). |
+| `createChart()` | New `ChartSession`. |
+| `createQuoteSession(options)` | New `QuoteSession`. |
+| `send(method, params)` | Sends a raw packet (escape hatch for commands this library does not wrap). |
+| `close()` | Closes the connection; resolves once closed. Sessions are released without errors. |
+
+Events: `open`, `hello` (server greeting), `ready`, `heartbeat` (answered automatically), `packet` (packets addressed to no session), `close` (code, reason), `error`.
+
+If the connection drops unexpectedly, every chart, study and quote subscription emits a `DISCONNECTED` error. The client does not reconnect automatically: create a new client.
+
+## Charts
+
+```ts
+const chart = client.createChart();
+chart.on('symbolLoaded', (info) => console.log(info.description));
+chart.on('update', (changes) => console.log(chart.lastCandle));
+chart.on('error', (error) => console.error(error.code, error.message));
+
+chart.setMarket('BINANCE:BTCEUR', { timeframe: '60', count: 300 });
+```
+
+`setMarket(symbol, options)`:
+
+| Option | Description |
+| --- | --- |
+| `timeframe` | Default `D`. |
+| `count` | Bars to load when the series is created (default 100). **Negative** values load bars *after* `to` instead of before it. |
+| `to` | Reference time (Unix seconds) of the last bar. Sent as `['bar_count', to, count]`. |
+| `adjustment`, `backAdjustment`, `session`, `currency` | As in the data API. |
+| `type`, `inputs` | Custom chart type (`HeikinAshi`, `Renko`, `LineBreak`, `Kagi`, `PointAndFigure`, `Range`) and its inputs. |
+| `replay` | Start replay mode at this Unix time. See [Replay](#replay). |
+
+The first `setMarket` creates the series. Later calls (another symbol, type or replay) modify it and keep its bar count and studies: TradingView only accepts an empty range when modifying a series. Use `fetchMore` or a new chart to load a different amount.
+
+| Member | Description |
+| --- | --- |
+| `candles` | Loaded bars, oldest first: `{ time, open, high, low, close, volume }`. |
+| `lastCandle` | Most recent bar. |
+| `symbolInfo` | Symbol metadata from `symbol_resolved` (with `series_id`). |
+| `timeframe`, `seriesId`, `isReplay`, `isDeleted`, `studies` | State. |
+| `setTimeframe(timeframe)` | Changes the timeframe (keeps studies). Throws `INVALID_STATE` before `setMarket`. |
+| `setTimezone(timezone)` | Changes the chart timezone. |
+| `fetchMore(count)` | Loads older bars (negative: newer bars after a past `to`). |
+| `createStudy(indicator)` | Adds a study. |
+| `delete()` | Deletes the chart and its replay session. Idempotent. |
+
+Events: `symbolLoaded` (info), `update` (list of changed keys: `$prices` and/or study IDs), `seriesLoading`, `seriesCompleted` (`{ status, dataCompleted, turnaround }`: `dataCompleted` is `end` or `limit` when no more history can be loaded), `error`, and the replay events.
+
+### Replay
+
+```ts
+chart.setMarket('BINANCE:BTCEUR', { timeframe: 'D', replay: Math.round(Date.now() / 1000) - 86_400 * 7, count: 1 });
+chart.on('replayEnd', () => console.log('Reached the present'));
+
+await chart.replayStep(1);     // One bar forward; resolves when the server confirms
+await chart.replayStart(1000); // Play automatically, one bar per second
+await chart.replayStop();
+```
+
+Replay events: `replayLoaded` (instance ID), `replayPoint` (cursor time), `replayResolution` (resolutions reported by the server), `replayEnd`. Replay methods reject with `INVALID_STATE` outside replay mode, and pending requests reject when the chart is deleted or the market changes.
+
+## Studies
+
+```ts
+const rsi = await getIndicator('STD;RSI', { credentials });
+rsi.setInput('Length', 21);
+const study = chart.createStudy(rsi);
+
+study.on('ready', () => console.log(study.values.at(-1)));
+study.on('update', (changes) => {}); // 'plots', 'graphic', 'report.perf', 'report.trades'...
+study.on('error', (error) => console.error(error.message));
+```
+
+| Member | Description |
+| --- | --- |
+| `values` | Rows `{ $time, <plot>: number }`, oldest first. |
+| `graphics` | Parsed drawings (labels, lines, boxes, tables, polygons, horizontal lines and histograms, `raw`). |
+| `strategyReport` | Strategy `performance`, `trades`, `history`, `currency`, `settings` (decoded from plain or compressed payloads). |
+| `indicator`, `isReady`, `isRemoved` | State. |
+| `setIndicator(indicator)` | Replaces the indicator, e.g. after changing inputs. |
+| `remove()` | Removes the study. Idempotent. |
+
+Events: `loading`, `ready` (`study_completed`), `update`, `error`.
+
+### Indicator definitions
+
+- `getIndicator(id, { version, credentials })` returns a `PineIndicator` from `STD;...`, `PUB;...` or `USER;...` IDs.
+- `PineIndicator`: `id`, `version`, `description`, `shortDescription`, `inputs`, `plots`, `script`, `type`; `setInput(key, value)`, `setInputs(values)`, `findInput(key)`, `setType('StrategyScript@tv-scripting-101!')`, `clone()`.
+- `new BuiltInIndicator(type, options?)`: built-in studies such as `Volume@tv-basicstudies-241` and the volume profiles (`VbPFixed@...`, `VbPSessions@...`, `VbPVisible@...`). `setOption(key, value, force?)` validates names and types for known types unless `force` is true.
+- `parseIndicatorDefinition(result, id, version)` builds a `PineIndicator` from a cached `pine-facade` response.
+
+## Quotes
+
+```ts
+const quotes = client.createQuoteSession({ fields: ['lp', 'bid', 'ask'] }); // or 'all' / 'price'
+const btc = quotes.subscribe('BINANCE:BTCEUR', { session: 'regular' });
+btc.on('data', (quote, changes) => console.log(quote.lp, changes));
+btc.on('loaded', () => {});
+btc.on('error', (error) => {});
+
+btc.close();       // Stops this subscription
+quotes.setFields('all');
+quotes.delete();   // Deletes the session and its subscriptions
+```
+
+Subscriptions to the same symbol and session share one server subscription; the symbol is removed from the server when the last one closes. `btc.data` holds the merged latest values.
+
+## HTTP functions
+
+All accept `{ fetch?, signal?, headers? }`; functions that can use an account also accept `credentials`.
+
+| Function | Description |
+| --- | --- |
+| `searchMarkets(text, { type, exchange, offset })` | Symbol search (v3 endpoint). |
+| `getTechnicalAnalysis(symbol)` | Technical ratings for 1m to 1M periods, or `null`. |
+| `searchIndicators(text)` | Built-in (cached in memory; `clearIndicatorCache()`) and community indicators. |
+| `getIndicator(id, { version, credentials })` | Pine indicator definition. |
+| `getPrivateIndicators(credentials)` | Your saved scripts. |
+| `loginUser({ username, password, remember, userAgent })` | Signs in and returns the account with its cookies. Accounts with 2FA or captcha challenges are not supported. |
+| `getUser(credentials, { location, maxRedirects })` | Account behind session cookies (follows regional redirects, stops loops). |
+| `getChartToken(layoutId, { credentials, userId })` | Chart-storage token for a layout. |
+| `getDrawings(layoutId, { symbol, chartId, credentials, userId })` | Drawings saved in a layout. |
+| `new PinePermissionManager(pineId, { credentials })` | `getUsers(limit, order)`, `addUser(username, expiration?)`, `modifyExpiration(username, expiration?)`, `removeUser(username)` for invite-only scripts you own. |
+
+## Transport
+
+The default transport uses the [`ws`](https://github.com/websockets/ws) package, which works in Node and Bun. To use a proxy or another websocket implementation, pass `transport`:
+
+```ts
+import type { TransportFactory } from '@mathieuc/tradingview';
+
+const transport: TransportFactory = ({ url, origin, headers }, handlers) => {
+  const socket = createMySocket(url, { origin, headers });
+  socket.onopen = () => handlers.onOpen();
+  socket.onmessage = (event) => handlers.onMessage(String(event.data));
+  socket.onclose = (event) => handlers.onClose(event.code, event.reason);
+  socket.onerror = (event) => handlers.onError(new Error(String(event)));
+  return {
+    get isOpen() { return socket.readyState === 1; },
+    send: (data) => socket.send(data),
+    close: () => socket.close(),
+  };
+};
+
+const client = new TradingViewClient({ transport });
+```
+
+The same mechanism lets tests run without network access (see `tests/helpers/fake-server.ts`).
+
+## Protocol helpers
+
+`protocol` exposes the wire format for debugging and custom tooling:
+
+```ts
+import { protocol } from '@mathieuc/tradingview';
+
+protocol.encodePacket('set_auth_token', ['token']); // '~m~36~m~{"m":"set_auth_token","p":["token"]}'
+protocol.decodeFrames(rawMessage);  // [{ type: 'packet' | 'heartbeat' | 'data' | 'invalid', ... }]
+protocol.decodeCompressed(base64);  // Strategy report payloads (ZIP, zlib, raw deflate, gzip, JSON)
+protocol.createSessionId('cs');     // 'cs_Ab12Cd34Ef56'
+```
+
+Frames are `~m~<length>~m~<payload>`, where the length counts UTF-16 code units; heartbeats are `~h~<id>` and must be echoed (the client does it).

package/docs/migration-v4.md

@@ -0,0 +1,128 @@
+# Migrating from v3 to v4
+
+[README](../README.md) · [Data API](data-api.md) · [Low-level API](low-level-api.md) · [Coverage matrix](v4-coverage.md)
+
+Version 4 is a complete TypeScript rewrite with **no compatibility layer**. Every v3 capability is still available (see the [coverage matrix](v4-coverage.md)), under a more consistent API. This page shows how to translate v3 code.
+
+## Package
+
+| v3 | v4 |
+| --- | --- |
+| CommonJS: `const TradingView = require('@mathieuc/tradingview')` | ESM: `import { ... } from '@mathieuc/tradingview'`. On Node ≥ 20.19 or ≥ 22.12, `require()` of the ESM package also works. |
+| `agent.js` preview (`fetchCandles`, `watchCandles`) | `@mathieuc/tradingview/data` (`getCandles`, `watchCandles`, quotes, indicators...) |
+| Preview `MarketDataProvider` / `TradingViewProvider` | Provider-neutral candle injection remains: `getCandles(query, provider)`, `watchCandles(query, handlers, provider)` |
+| Node ≥ 14, untyped JSDoc | Node ≥ 20 or Bun, bundled TypeScript declarations |
+| `axios`, `jszip`, `ws` dependencies | `ws` only (HTTP uses the built-in `fetch`) |
+
+## Simplest path: the data API
+
+```js
+// v3
+const client = new TradingView.Client();
+const chart = new client.Session.Chart();
+chart.setMarket('BINANCE:BTCEUR', { timeframe: 'D', range: 100 });
+chart.onUpdate(() => { console.log(chart.periods); client.end(); });
+
+// v4
+import { getCandles } from '@mathieuc/tradingview/data';
+const candles = await getCandles({ symbol: 'BINANCE:BTCEUR', timeframe: 'D', count: 100 });
+```
+
+## Client
+
+| v3 | v4 |
+| --- | --- |
+| `new Client({ token, signature })` | `new TradingViewClient({ credentials: { session, signature } })` |
+| `server`, `location`, `headers` options | Same names |
+| `DEBUG: true` (sets a global flag) | `debug: true` or `debug: (...args) => {}` (per client) |
+| (not available) | `authToken`, `transport`, `fetch`, `connectTimeoutMs`, `client.ready` |
+| `client.onConnected(cb)` | `client.on('open', cb)` |
+| `client.onDisconnected(cb)` | `client.on('close', cb)` |
+| `client.onLogged(cb)` | `client.on('ready', cb)`; the server greeting is `client.on('hello', cb)` / `client.serverInfo` |
+| `client.onPing(cb)` | `client.on('heartbeat', cb)` |
+| `client.onData(cb)` | `client.on('packet', cb)` |
+| `client.onError(cb)` (`(...messages)`) | `client.on('error', (error) => ...)` (`TradingViewError`) |
+| `client.onEvent(cb)` | `client.onAny((event, ...args) => ...)` |
+| `client.isLogged`, `client.isOpen` | `client.isAuthenticated`, `client.isOpen` (and `client.isClosed`) |
+| `client.send(t, p)` / `client.sendQueue()` | `client.send(method, params)`; the queue is flushed automatically |
+| `client.end()` | `await client.close()` (now resolves once actually closed) |
+| `new client.Session.Chart()` | `client.createChart()` |
+| `new client.Session.Quote(options)` | `client.createQuoteSession(options)` |
+
+## Charts
+
+| v3 | v4 |
+| --- | --- |
+| `chart.setMarket(symbol, { range, to, backadjustment, ... })` | `chart.setMarket(symbol, { count, to, backAdjustment, ... })` (`timeframe`, `adjustment`, `session`, `currency`, `type`, `inputs`, `replay` unchanged). The default timeframe is now `D` (v3: `240`). An empty symbol throws instead of loading `BTCEUR`. |
+| `chart.setSeries(timeframe)` | `chart.setTimeframe(timeframe)` (throws `INVALID_STATE` before `setMarket` instead of emitting an error) |
+| `chart.periods` (newest first; `max`/`min`; volume rounded to 2 decimals) | `chart.candles` (**oldest first**; `high`/`low`; raw volume) and `chart.lastCandle` |
+| `chart.infos` | `chart.symbolInfo` |
+| `chart.setTimezone(tz)` | Same (no longer clears loaded bars) |
+| `chart.fetchMore(n)` | Same |
+| `chart.replayStep/Start/Stop()` | Same; they now reject with `INVALID_STATE` outside replay mode instead of never resolving |
+| `chart.onSymbolLoaded(cb)` | `chart.on('symbolLoaded', (info) => ...)` |
+| `chart.onUpdate(cb)` | `chart.on('update', (changes) => ...)` |
+| `chart.onReplayLoaded/Point/Resolution/End(cb)` | `chart.on('replayLoaded' / 'replayPoint' / 'replayResolution' / 'replayEnd', cb)` |
+| `chart.onError(cb)` | `chart.on('error', (error) => ...)` |
+| (not available) | `chart.on('seriesCompleted', ...)`, `chart.on('seriesLoading', ...)` |
+| `new chart.Study(indicator)` | `chart.createStudy(indicator)` |
+| `chart.delete()` | Same (idempotent) |
+
+## Studies
+
+| v3 | v4 |
+| --- | --- |
+| `study.periods` (newest first) | `study.values` (**oldest first**, still keyed by `$time` and plot names) |
+| `study.graphic` | `study.graphics`; `tables[i].cells()` is now the `tables[i].cells` array; `raw()` is now the `raw` object |
+| `study.strategyReport` | Same |
+| `study.instance` | `study.indicator` |
+| `study.setIndicator(indicator)`, `study.remove()` | Same |
+| `study.onReady/onUpdate/onError(cb)` | `study.on('ready' / 'update' / 'error', cb)` (also `loading`) |
+
+## Quotes
+
+| v3 | v4 |
+| --- | --- |
+| `new client.Session.Quote({ fields: 'all' })` | `client.createQuoteSession({ fields: 'all' })` |
+| `{ customFields: ['lp'] }` | `{ fields: ['lp'] }` |
+| `new quoteSession.Market(symbol, session)` | `quoteSession.subscribe(symbol, { session })` |
+| `market.onLoaded/onData/onError/onEvent(cb)` | `subscription.on('loaded' / 'data' / 'error', cb)` / `onAny(cb)`; `data` also receives the changed fields |
+| `market.close()`, `quoteSession.delete()` | `subscription.close()`, `quoteSession.delete()` |
+
+## Indicators
+
+| v3 | v4 |
+| --- | --- |
+| `TradingView.getIndicator(id, version, session, signature)` | `getIndicator(id, { version, credentials })` |
+| `indicator.pineId`, `indicator.pineVersion` | `indicator.id`, `indicator.version` |
+| `indicator.setOption(key, value)` | `indicator.setInput(key, value)` (chainable; also `setInputs({...})`, `clone()`) |
+| `indicator.setType(type)` | Same |
+| `new BuiltInIndicator(type)` + `setOption(key, value, FORCE)` | Same, plus initial options: `new BuiltInIndicator(type, { first_bar_time })` |
+
+## HTTP functions
+
+| v3 | v4 |
+| --- | --- |
+| `searchMarketV3(text, filter, offset)` | `searchMarkets(text, { type, offset, exchange })` |
+| `searchMarket(text, filter)` (deprecated v1 endpoint) | `searchMarkets(text, { type })` |
+| `result.getTA()` | `getTechnicalAnalysis(result.id)` |
+| `getTA(symbol)` (returned `false` without data) | `getTechnicalAnalysis(symbol)` (returns `null`) |
+| `searchIndicator(text)` + `result.get()` | `searchIndicators(text)` + `getIndicator(result.id, { version: result.version })` |
+| `getPrivateIndicators(session, signature)` + `result.get()` | `getPrivateIndicators({ session, signature })` + `getIndicator(result.id, { version, credentials })` |
+| `loginUser(username, password, remember, UA)` | `loginUser({ username, password, remember, userAgent })` |
+| `getUser(session, signature, location)` | `getUser({ session, signature }, { location })` (`id` is now a number) |
+| `getChartToken(layout, { id, session, signature })` | `getChartToken(layout, { userId, credentials: { session, signature } })` |
+| `getDrawings(layout, symbol, { id, session, signature }, chartID)` | `getDrawings(layout, { symbol, chartId, userId, credentials })` |
+| `new PinePermManager(session, signature, pineId)` | `new PinePermissionManager(pineId, { credentials: { session, signature } })` (same methods) |
+
+## Errors
+
+v3 passed lists of strings to `onError` callbacks, or printed them. v4 uses `TradingViewError` everywhere, with a `code` (`SYMBOL_ERROR`, `SERIES_ERROR`, `CRITICAL_ERROR`, `STUDY_ERROR`, `AUTH_ERROR`, `TIMEOUT`...), a readable `message` and the raw server payload in `details`. Study errors are formatted with their context, e.g. `Study error: Invalid value of the 'factor' argument (-1)...`.
+
+## High-level data preview (formerly agent-api)
+
+| Preview (`agent.js`) | v4 |
+| --- | --- |
+| `fetchCandles({ symbol, timeframe, limit, timeoutMs, signal })` | `getCandles({ symbol, timeframe, count, timeoutMs, signal })` |
+| `watchCandles(query, { onData, onError })` → `{ latest, stop() }` | `watchCandles(query, { onData, onError })` → `{ latest, stop(), closed, isActive, symbolInfo }` |
+| `TradingViewProvider` / `MarketDataProvider` injection | Provider injection remains: `getCandles(query, provider)` or `watchCandles(query, handlers, provider)`; `client` and `clientOptions.transport` also work for TradingView |

package/docs/release-4.0.0-beta.1.md

@@ -0,0 +1,39 @@
+# 4.0.0-beta.1 release candidate
+
+Status: prepared for review; not published by this change.
+Target npm dist-tag: **beta**. Keep **latest** on 3.5.2.
+
+## Changes since beta.0
+
+- Preserve buy-and-hold history even when a report has no equity history (#331).
+- Export `summarizeStrategyReport`: separate record counts, closed/open trade
+  counts, closed net profit, open PnL and total PnL; retain unknown fields as
+  undefined (#331).
+- Reject structurally malformed trade lists before modifying a report; report
+  parse errors consistently for plain and compressed envelopes (#332).
+- Add a runnable public-strategy/report/PnL example, with bounded execution,
+  credential checks and explicit failure status.
+- Document Basic Replay playback evidence and separate paid UI export and
+  Deep Backtesting limits from library report access.
+
+## Validation
+
+- Deterministic Node/Bun suites, typecheck, lint, build and packed-consumer smoke
+  checks are required before publication.
+- Basic live probe: daily BINANCE:BTCEUR Replay load, three step acknowledgments,
+  automatic bar advancement, start and stop acknowledgments.
+- Strategy example executed against Basic; report aggregates and history returned.
+- Private compressed strategy capture validated in the preceding fixes.
+- No claim of universal Replay entitlement, UI export success or Deep Backtesting.
+
+## Publication gate
+
+Publication requires the maintainer's explicit go-ahead. After approval, use the
+reviewed commit with a clean checkout, rerun package checks, and publish the
+inspected tarball using `npm publish <tarball> --tag beta`. Verify the resulting
+version and dist-tags. Do not use the default `latest` tag. No tag, GitHub release,
+or npm publication is created by preparing this candidate.
+
+For v3 migration and breaking changes inherited from beta.0, see
+[migration-v4.md](migration-v4.md). This candidate adds no new intended breaking
+change relative to beta.0.