@mathieuc/tradingview 4.0.0-beta.3 → 4.0.0-beta.5

package/dist/data/index.d.ts

@@ -30,3 +30,5 @@ export { summarizeStrategyReport } from '../chart/strategy.js';
 export type { StrategySummary } from '../chart/strategy.js';
 export { getScreener } from '../http/screener.js';
 export type { ScreenerFilter, ScreenerQuery, ScreenerResult, ScreenerRow } from '../http/screener.js';
+export { getWatchlists, getHotlist } from '../http/watchlists.js';
+export type { Watchlist, WatchlistOptions, HotlistKind, HotlistQuery } from '../http/watchlists.js';

package/dist/data/index.js

@@ -15,3 +15,4 @@ export { getTechnicalAnalysis, searchIndicators, searchMarkets, } from '../http/
 export { TradingViewError } from '../errors.js';
 export { summarizeStrategyReport } from '../chart/strategy.js';
 export { getScreener } from '../http/screener.js';
+export { getWatchlists, getHotlist } from '../http/watchlists.js';

package/dist/http/index.d.ts

@@ -11,3 +11,5 @@ export { PinePermissionManager } from './pine-permissions.js';
 export type { AuthorizedUser, AuthorizedUserOrder, PinePermissionOptions } from './pine-permissions.js';
 export { getScreener } from './screener.js';
 export type { ScreenerFilter, ScreenerQuery, ScreenerResult, ScreenerRow } from './screener.js';
+export { getWatchlists, getHotlist } from './watchlists.js';
+export type { Watchlist, WatchlistOptions, HotlistKind, HotlistQuery } from './watchlists.js';

package/dist/http/index.js

@@ -4,3 +4,4 @@ export { clearIndicatorCache, getIndicator, getPrivateIndicators, parseIndicator
 export { getChartToken, getDrawings } from './layouts.js';
 export { PinePermissionManager } from './pine-permissions.js';
 export { getScreener } from './screener.js';
+export { getWatchlists, getHotlist } from './watchlists.js';

package/dist/http/watchlists.d.ts

@@ -0,0 +1,22 @@
+import { type Credentials, type HttpOptions } from './request.js';
+import { type ScreenerQuery, type ScreenerResult } from './screener.js';
+export interface Watchlist {
+    id: number;
+    name: string;
+    /** Ordered upstream entries, including any section markers. */
+    symbols: string[];
+    /** Additional upstream metadata, preserved without coercion. */
+    [key: string]: unknown;
+}
+export interface WatchlistOptions extends HttpOptions {
+    credentials: Credentials;
+}
+/** Reads all watchlists belonging to the authenticated account. Never modifies them. */
+export declare function getWatchlists(options: WatchlistOptions): Promise<Watchlist[]>;
+export type HotlistKind = 'gainers' | 'losers' | 'mostActive' | 'volumeGainers';
+export interface HotlistQuery extends Omit<ScreenerQuery, 'columns' | 'sort'> {
+    kind: HotlistKind;
+    columns?: string[];
+}
+/** Scanner-ranked lists, not a promise of parity with the TradingView UI hotlist widget. */
+export declare function getHotlist(query: HotlistQuery, options?: HttpOptions): Promise<ScreenerResult>;

package/dist/http/watchlists.js

@@ -0,0 +1,42 @@
+import { TradingViewError } from '../errors.js';
+import { request } from './request.js';
+import { getScreener } from './screener.js';
+/** Reads all watchlists belonging to the authenticated account. Never modifies them. */
+export async function getWatchlists(options) {
+    if (!options?.credentials?.session) {
+        throw new TradingViewError('INVALID_ARGUMENT', 'getWatchlists requires account credentials');
+    }
+    const { data, status } = await request('https://www.tradingview.com/api/v1/symbols_list/all/', {
+        credentials: options.credentials,
+        headers: { origin: 'https://www.tradingview.com' },
+        redirect: 'manual',
+    }, options);
+    if (status === 401 || status === 403 || (status >= 300 && status < 400)) {
+        throw new TradingViewError('AUTH_ERROR', `Watchlist access rejected (HTTP ${status})`);
+    }
+    if (status < 200 || status >= 300 || !Array.isArray(data)
+        || data.some((list) => !list || !Number.isSafeInteger(list.id) || typeof list.name !== 'string'
+            || !Array.isArray(list.symbols) || list.symbols.some((symbol) => typeof symbol !== 'string'))) {
+        throw new TradingViewError('HTTP_ERROR', `Unexpected watchlist response (HTTP ${status})`);
+    }
+    return data;
+}
+/** Scanner-ranked lists, not a promise of parity with the TradingView UI hotlist widget. */
+export async function getHotlist(query, options = {}) {
+    const rankings = {
+        gainers: { sortBy: 'change', sortOrder: 'desc' },
+        losers: { sortBy: 'change', sortOrder: 'asc' },
+        mostActive: { sortBy: 'volume', sortOrder: 'desc' },
+        volumeGainers: { sortBy: 'relative_volume_10d_calc', sortOrder: 'desc' },
+    };
+    if (!Object.hasOwn(rankings, query.kind)) {
+        throw new TradingViewError('INVALID_ARGUMENT', 'Unknown hotlist kind');
+    }
+    return getScreener({
+        ...query,
+        market: query.market ?? 'america',
+        columns: query.columns ?? ['name', 'close', 'change', 'volume', 'relative_volume_10d_calc'],
+        filter: query.filter ?? [{ left: 'type', operation: 'equal', right: 'stock' }],
+        sort: rankings[query.kind],
+    }, options);
+}

package/docs/data-api.md

@@ -289,3 +289,8 @@ Every failure is a `TradingViewError` with a `code`:
 Use [`getScreener`](screener.md) for a single scanner page with custom columns,
 filters, ranking and explicit pagination. Available from this high-level entry
 point as well as the root package; no chart or quote session is required.
+
+## Watchlists and rankings
+
+[`getWatchlists` and `getHotlist`](watchlists.md) provide read-only account lists
+and scanner-based gainers, losers and volume rankings. Available from both entry points.

package/docs/v4-backlog-triage.md

@@ -144,3 +144,18 @@ No issues/legacy PRs were closed, and no contributor comments were sent by this
 Beta.3 adds `getScreener` for #53 and scanner fields relevant to #280. See
 [screener documentation](screener.md). #85 real-time exchange entitlement is not
 resolved by a successful HTTP scan. Watchlists and paid/private cases remain open.
+
+## Watchlist follow-up
+
+Beta.4 adds read-only `getWatchlists` and scanner-ranked `getHotlist` (#87).
+Authenticated discovery returned two empty lists; populated entries are fixture-tested.
+Exact TradingView UI hotlist parity is not claimed. See [watchlists](watchlists.md).
+
+## Account and endurance follow-up
+
+Beta.5 ships opt-in account/endurance diagnostics and documents six successful
+private USER-script runs. Deep Backtesting reached the server but returned
+`request_error` / `not_allowed` with the available account. This is a concrete
+prerequisite blocker, not implemented Premium support. Original private-script,
+CME/GUI and 12-hour issue fixtures remain necessary; no historical issue is closed
+from the broader smoke results. See [reliability evidence](v4-reliability.md).

package/docs/v4-reliability.md

@@ -34,3 +34,61 @@ V4 now starts the account lookup at `/chart/` and follows `Location` only on HTT
 - Basic daily Replay and strategy reports are documented in [v4-coverage.md](v4-coverage.md); this is not proof of Deep Backtesting or universal intraday entitlement.
 - Private/invite-only script cases, subscribed futures parity, owned layouts and long-running Pine failures need matching assets and targeted reproductions. See [backlog triage](v4-backlog-triage.md).
 - Live CI is non-blocking. Review its actual test results, not just the overall workflow conclusion, before release.
+
+## Account-scoped diagnostics (beta.5)
+
+From a source checkout, set `SESSION` and `SIGNATURE` securely and run
+`npm run probe:account`. The read-only probe authenticates, lists saved scripts,
+then evaluates at most ten scripts sequentially on 100 daily BTCUSDT bars. Use
+`--max-scripts=N` and `--timeout-ms=N` after `--` to change these bounds.
+It prints only counts, index-based outcomes, script namespace categories and the
+account token's plan claim. It does not print script IDs, names, source, values,
+account identifiers or credentials. A plan claim is informational, not proof of
+exchange or Deep Backtesting entitlement. Failures exit nonzero; an empty saved
+script list is not considered successful private-script coverage.
+
+The package now includes both diagnostics, so installed consumers can run:
+
+```sh
+node node_modules/@mathieuc/tradingview/scripts/probe-account.mjs
+node node_modules/@mathieuc/tradingview/scripts/endurance.mjs --minutes=7 --cycle-seconds=600 --require-post-threshold-updates
+```
+
+The second command requires candle **and** quote callbacks after more than 30
+heartbeats on the same connection. `--heartbeat-threshold=N` changes the threshold.
+Counters reset per connection for threshold eligibility; ten short connections do
+not constitute one long connection. Initial snapshots alone cannot satisfy this
+mode. Any recorded error or interruption also makes the probe fail. Without the
+flag, a completed run remains a transport/lifecycle check, not a liveness guarantee.
+Run strict mode on an open market; a closed venue cannot supply the required proof.
+
+### Verified private scripts and outstanding paid-account prerequisite
+
+On 3 October 2026, all six saved `USER;` scripts accessible to the available account
+completed: two studies and four strategies, each returning 100 candles and 200
+study rows. Three strategies returned 208, 4 and 69 trades respectively; the fourth
+returned a report with zero trades. These are account-specific fixtures, not a
+reproduction of the private strategy in #89 or the table payload in #251.
+
+A bounded request to `history-data` using the protocol in PR #204 reached the server
+and returned `request_error` / `not_allowed`. No Deep Backtesting success is claimed.
+An eligible account and current successful protocol capture are required before
+shipping that API. No subscription was purchased and no account content was modified.
+The original scripts/fixtures for #188 (long-running Pine depth error), #24 (Renko
+GUI parity) and #311 (subscribed CME sessions) remain unavailable for exact reproduction.
+
+### Unbroken-socket checks, 3 October 2026
+
+- **BTCUSDT, six minutes, one connection:** 35 heartbeats, 85 candle callbacks,
+  89 quote callbacks; after heartbeat 30 on that same connection, 13 candle and
+  12 quote callbacks. Zero errors/failures; strict mode exited successfully.
+- **OANDA:EURUSD HeikinAshi, seven minutes, one connection:** 41 heartbeats,
+  one initial candle callback and one initial quote callback, zero errors/failures.
+  The forex market was closed: this proves heartbeat continuity only and does not
+  resolve #236's reported price-stream freeze on an open market.
+- Negative controls: a short initial-snapshot-only run fails strict mode, and an
+  interrupted run exits nonzero after cleanup. Account diagnostics also fail cleanly
+  without credentials; a bounded one-script run was separately verified on Bun.
+
+Neither run is a 12-hour Pine reproduction. The full authenticated live suite on
+beta.4 passed all 22 tests; beta.5 changes diagnostic tooling/documentation only.

package/docs/watchlists.md

@@ -0,0 +1,56 @@
+# Watchlists and ranked lists
+
+## Read your watchlists
+
+```js
+import { getWatchlists } from '@mathieuc/tradingview/data';
+
+const lists = await getWatchlists({
+  credentials: {
+    session: process.env.TV_SESSION,
+    signature: process.env.TV_SIGNATURE,
+  },
+});
+for (const list of lists) console.log(list.id, list.name, list.symbols);
+```
+
+This is a read-only account API. Each list preserves its numeric ID, name, ordered
+`symbols` and additional upstream metadata. Entries can include section markers;
+do not blindly pass every entry to `getQuotes`. Filter for exchange-qualified
+symbols appropriate to your application. No lists are created, edited or deleted.
+
+Credentials are required. Access rejection (401/403 or login redirects) produces
+`AUTH_ERROR`; malformed responses and other failed statuses produce `HTTP_ERROR`.
+Authenticated redirects are not followed. The options also accept `fetch`,
+`headers` and `signal`. Treat returned names/symbols as private account data.
+
+## Scanner-ranked lists
+
+```js
+import { getHotlist } from '@mathieuc/tradingview/data';
+
+const page = await getHotlist({ kind: 'gainers', range: [0, 10] });
+console.log(page.rows);
+```
+
+| Kind | Ranking |
+| --- | --- |
+| `gainers` | Percentage change descending |
+| `losers` | Percentage change ascending |
+| `mostActive` | Volume descending |
+| `volumeGainers` | Relative volume (`relative_volume_10d_calc`) descending |
+
+These are convenient [screener](screener.md) queries, **not an exact replica of the
+TradingView hotlist widget**. UI universe, session and liquidity filters may differ.
+Default universe: America stocks; default fields: name, close, change, volume and
+relative volume. Override `market`, `columns`, `filter`, `range` or `symbols` as
+needed. For a non-stock universe, supply appropriate filters (or `filter: []`),
+since changing the market does not remove the default stock filter. Exchange data
+may be delayed. No automatic polling or paid entitlement is implied.
+
+## Evidence and limits
+
+On 3 October 2026, the account endpoint returned two watchlists successfully.
+Both were empty, so nonempty ordered entries and section preservation are covered
+by deterministic fixtures, not claimed as live-tested account content. An anonymous
+America relative-volume scan returned populated rows. No account data was modified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mathieuc/tradingview",
-  "version": "4.0.0-beta.3",
+  "version": "4.0.0-beta.5",
   "description": "TradingView market data for JavaScript and TypeScript: candles, quotes, indicators and strategies, with a simple data API and full low-level access.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,9 @@
   "files": [
     "dist",
     "README.md",
-    "docs"
+    "docs",
+    "scripts/endurance.mjs",
+    "scripts/probe-account.mjs"
   ],
   "sideEffects": false,
   "scripts": {
@@ -36,7 +38,8 @@
     "check": "npm run typecheck && npm run lint && npm test && npm run build && npm run smoke",
     "prepack": "npm run build",
     "probe:endurance": "npm run build && node scripts/endurance.mjs",
-    "probe:parity": "npm run build && node scripts/parity.mjs"
+    "probe:parity": "npm run build && node scripts/parity.mjs",
+    "probe:account": "npm run build && node scripts/probe-account.mjs"
   },
   "repository": {
     "type": "git",

package/scripts/endurance.mjs

@@ -0,0 +1,93 @@
+/** Opt-in live endurance probe. No credentials are read or logged. */
+import { TradingViewClient } from '../dist/index.js';
+import { watchCandles, watchQuotes } from '../dist/data/index.js';
+
+const argument = (name, fallback) => {
+  const raw = process.argv.find((value) => value.startsWith(`--${name}=`))?.split('=')[1];
+  const number = raw === undefined ? fallback : Number(raw);
+  if (!Number.isFinite(number) || number <= 0) throw new Error(`--${name} must be positive`);
+  return number;
+};
+
+const textArgument = (name, fallback) => process.argv.find((value) => value.startsWith(`--${name}=`))?.split('=')[1] ?? fallback;
+const minutes = argument('minutes', 120);
+const cycleSeconds = argument('cycle-seconds', 600);
+const heartbeatThreshold = argument('heartbeat-threshold', 30);
+const requirePostThresholdUpdates = process.argv.includes('--require-post-threshold-updates');
+const symbol = textArgument('symbol', 'BINANCE:BTCUSDT');
+const timeframe = textArgument('timeframe', '1');
+const chartType = textArgument('chart-type', undefined);
+const deadline = Date.now() + minutes * 60_000;
+const metrics = { cycles: 0, starts: 0, failures: 0, candleUpdates: 0, quoteUpdates: 0, heartbeats: 0, postThresholdCandleUpdates: 0, postThresholdQuoteUpdates: 0, errors: [] };
+let interrupted = false;
+for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => { interrupted = true; });
+
+const report = (event, extra = {}) => console.log(JSON.stringify({
+  at: new Date().toISOString(), event, ...extra,
+}));
+
+function waitForCycle(ms, watchers) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => resolve('elapsed'), ms);
+    Promise.race(watchers.map((watcher) => watcher.closed)).then(() => {
+      clearTimeout(timer);
+      resolve('closed');
+    });
+  });
+}
+
+const status = setInterval(() => report('status', { ...metrics, errors: metrics.errors.slice(-3) }), 60_000);
+report('start', { minutes, cycleSeconds, symbol, timeframe, chartType, heartbeatThreshold, requirePostThresholdUpdates });
+try {
+  while (!interrupted && Date.now() < deadline) {
+    metrics.cycles += 1;
+    const client = new TradingViewClient();
+    let cycleHeartbeats = 0;
+    client.on('heartbeat', () => { metrics.heartbeats += 1; cycleHeartbeats += 1; });
+    client.on('error', (error) => metrics.errors.push(error.code));
+    let candles;
+    let quotes;
+    try {
+      candles = await watchCandles({ symbol, timeframe, chartType, count: 5, client }, {
+        onData: () => {
+          metrics.candleUpdates += 1;
+          if (cycleHeartbeats > heartbeatThreshold) metrics.postThresholdCandleUpdates += 1;
+        },
+        onError: (error) => metrics.errors.push(error.code),
+      });
+      quotes = await watchQuotes({ symbols: [symbol], fields: 'price', client }, {
+        onData: () => {
+          metrics.quoteUpdates += 1;
+          if (cycleHeartbeats > heartbeatThreshold) metrics.postThresholdQuoteUpdates += 1;
+        },
+        onError: (error) => metrics.errors.push(error.code),
+      });
+      if (candles.latest.length !== 5 || typeof quotes.latest[symbol]?.lp !== 'number') {
+        throw new Error('Initial market snapshots incomplete');
+      }
+      metrics.starts += 1;
+      report('connected', { cycle: metrics.cycles, candles: candles.latest.length, quotePricePresent: true });
+      const duration = Math.min(cycleSeconds * 1000, deadline - Date.now());
+      const outcome = await waitForCycle(duration, [candles, quotes]);
+      if (outcome === 'closed' && !interrupted) throw new Error('Watcher closed before planned rotation');
+      report('rotation', { cycle: metrics.cycles, outcome });
+    } catch (error) {
+      metrics.failures += 1;
+      metrics.errors.push(error?.code ?? error?.message ?? String(error));
+      report('failure', { cycle: metrics.cycles, code: error?.code, message: error?.message });
+    } finally {
+      await Promise.allSettled([candles?.stop(), quotes?.stop()]);
+      await client.close();
+    }
+    if (metrics.failures >= 3) break;
+    if (metrics.failures && Date.now() < deadline) await new Promise((resolve) => setTimeout(resolve, 3_000));
+  }
+} finally {
+  clearInterval(status);
+  report('summary', { ...metrics, errors: metrics.errors.slice(-10), interrupted });
+}
+if (interrupted || metrics.failures || metrics.errors.length || metrics.starts === 0
+  || metrics.quoteUpdates === 0 || metrics.candleUpdates === 0
+  || (requirePostThresholdUpdates && (!metrics.postThresholdCandleUpdates || !metrics.postThresholdQuoteUpdates))) {
+  process.exitCode = 1;
+}

package/scripts/probe-account.mjs

@@ -0,0 +1,55 @@
+/** Opt-in read-only diagnostics. Never print account tokens, script IDs or names. */
+import { Buffer } from 'node:buffer';
+import { getUser, getPrivateIndicators, getIndicatorData } from '../dist/index.js';
+
+const positiveArgument = (name, fallback) => {
+  const raw = process.argv.find((value) => value.startsWith(`--${name}=`))?.slice(name.length + 3);
+  const value = raw === undefined ? fallback : Number(raw);
+  if (!Number.isSafeInteger(value) || value < 1) throw new Error('Invalid probe argument');
+  return value;
+};
+
+async function main() {
+  const maxScripts = positiveArgument('max-scripts', 10);
+  const timeoutMs = positiveArgument('timeout-ms', 30_000);
+  if (!process.env.SESSION) throw new Error('SESSION is required');
+  const credentials = { session: process.env.SESSION, signature: process.env.SIGNATURE };
+  const options = { signal: AbortSignal.timeout(timeoutMs) };
+  const user = await getUser(credentials, options);
+  let planClaim = null;
+  try {
+    const claims = JSON.parse(Buffer.from(user.authToken.split('.')[1], 'base64url').toString());
+    if (typeof claims.plan === 'string') planClaim = claims.plan;
+  } catch { /* The account token is not guaranteed to remain a JWT. */ }
+  console.log(JSON.stringify({ event: 'account', authenticated: true, planClaim }));
+  const scripts = await getPrivateIndicators(credentials, { signal: AbortSignal.timeout(timeoutMs) });
+  let failures = 0;
+  const selected = scripts.slice(0, maxScripts);
+  console.log(JSON.stringify({ event: 'selection', available: scripts.length, selected: selected.length }));
+  for (const [index, script] of selected.entries()) {
+    const classification = script.id.startsWith('USER;') ? 'user' : script.id.startsWith('PUB;') ? 'published' : 'other';
+    try {
+      const result = await getIndicatorData({
+        symbol: 'BINANCE:BTCUSDT', timeframe: '1D', count: 100,
+        indicator: script.id, credentials, timeoutMs, signal: AbortSignal.timeout(timeoutMs),
+      });
+      console.log(JSON.stringify({
+        event: 'script', index, classification, ok: true,
+        candles: result.candles.length, values: result.values.length,
+        trades: result.strategyReport.trades?.length ?? 0,
+        reportPresent: Object.keys(result.strategyReport.performance ?? {}).length > 0,
+      }));
+    } catch (error) {
+      failures += 1;
+      console.log(JSON.stringify({ event: 'script', index, classification, ok: false, code: error?.code ?? 'ERROR' }));
+    }
+  }
+  console.log(JSON.stringify({ event: 'summary', checked: selected.length, failures, remaining: scripts.length - selected.length }));
+  if (failures || selected.length === 0) process.exitCode = 1;
+}
+
+main().catch((error) => {
+  // Do not log message/details: upstream failures may carry private script payloads.
+  console.error(JSON.stringify({ event: 'failure', code: error?.code ?? 'CONFIG_OR_NETWORK_ERROR' }));
+  process.exitCode = 1;
+});