@mathieuc/tradingview 4.0.0-beta.2 → 4.0.0-beta.4

package/dist/data/index.d.ts

@@ -28,3 +28,7 @@ export type { GraphicsData } from '../chart/graphics.js';
 export type { StrategyReport } from '../chart/strategy.js';
 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

@@ -14,3 +14,5 @@ export { DEFAULT_TIMEOUT_MS } from './operation.js';
 export { getTechnicalAnalysis, searchIndicators, searchMarkets, } from '../http/index.js';
 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

@@ -9,3 +9,7 @@ export { getChartToken, getDrawings } from './layouts.js';
 export type { Drawing, DrawingPoint, GetDrawingsOptions, LayoutOptions, } from './layouts.js';
 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

@@ -3,3 +3,5 @@ export { getTechnicalAnalysis, searchMarkets } from './market.js';
 export { clearIndicatorCache, getIndicator, getPrivateIndicators, parseIndicatorDefinition, searchIndicators, } from './indicators.js';
 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/screener.d.ts

@@ -0,0 +1,32 @@
+import { type AuthHttpOptions } from './request.js';
+export interface ScreenerFilter {
+    left: string;
+    operation: string;
+    right?: unknown;
+}
+export interface ScreenerQuery {
+    /** Scanner universe, e.g. america, crypto, forex or global. */
+    market?: string;
+    /** Exact scanner field names, including optional timeframe suffixes. */
+    columns: string[];
+    filter?: ScreenerFilter[];
+    sort?: {
+        sortBy: string;
+        sortOrder: 'asc' | 'desc';
+    };
+    /** Zero-based, end-exclusive page range. Defaults to [0, 50]. */
+    range?: [number, number];
+    /** Optional exchange-qualified symbols. */
+    symbols?: string[];
+}
+export interface ScreenerRow {
+    symbol: string;
+    /** Values retain upstream types and nulls; keys match requested columns. */
+    values: Record<string, unknown>;
+}
+export interface ScreenerResult {
+    totalCount: number;
+    rows: ScreenerRow[];
+}
+/** One scanner page. This does not subscribe to live prices or grant exchange entitlements. */
+export declare function getScreener(query: ScreenerQuery, options?: AuthHttpOptions): Promise<ScreenerResult>;

package/dist/http/screener.js

@@ -0,0 +1,36 @@
+import { TradingViewError } from '../errors.js';
+import { request } from './request.js';
+/** One scanner page. This does not subscribe to live prices or grant exchange entitlements. */
+export async function getScreener(query, options = {}) {
+    const market = query.market ?? 'global';
+    const range = query.range ?? [0, 50];
+    if (!/^[a-z][a-z0-9_-]*$/i.test(market)
+        || !Array.isArray(query.columns) || !query.columns.length
+        || query.columns.some((column) => typeof column !== 'string' || !column.trim())
+        || new Set(query.columns).size !== query.columns.length
+        || range.length !== 2 || !range.every(Number.isSafeInteger) || range[0] < 0 || range[1] <= range[0]) {
+        throw new TradingViewError('INVALID_ARGUMENT', 'Invalid screener market, columns or page range');
+    }
+    const { data, status } = await request(`https://scanner.tradingview.com/${market}/scan`, {
+        method: 'POST',
+        credentials: options.credentials,
+        headers: { origin: 'https://www.tradingview.com' },
+        json: {
+            columns: query.columns, range, filter: query.filter ?? [], sort: query.sort,
+            symbols: query.symbols === undefined ? undefined : { tickers: query.symbols },
+        },
+    }, options);
+    if (status < 200 || status >= 300 || !data || !Number.isSafeInteger(data.totalCount)
+        || data.totalCount < 0 || !Array.isArray(data.data)
+        || data.data.some((row) => !row || typeof row.s !== 'string'
+            || !Array.isArray(row.d) || row.d.length !== query.columns.length)) {
+        throw new TradingViewError('HTTP_ERROR', `Unexpected screener response (HTTP ${status})`);
+    }
+    return {
+        totalCount: data.totalCount,
+        rows: data.data.map((row) => ({
+            symbol: row.s,
+            values: Object.fromEntries(query.columns.map((column, index) => [column, row.d[index]])),
+        })),
+    };
+}

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

@@ -283,3 +283,14 @@ Every failure is a `TradingViewError` with a `code`:
 | `CALLBACK_ERROR` | A watcher callback threw; the stream remains active. |
 
 `error.details` keeps the raw server payload when there is one.
+
+## Screener
+
+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/screener.md

@@ -0,0 +1,42 @@
+# Screener
+
+`getScreener` is available from both the root package and `@mathieuc/tradingview/data`.
+It performs one HTTP scan, without creating WebSocket sessions.
+
+```js
+import { getScreener } from '@mathieuc/tradingview/data';
+
+const page = await getScreener({
+  market: 'america',
+  columns: ['name', 'close', 'volume', 'Stoch.RSI.D'],
+  filter: [{ left: 'type', operation: 'equal', right: 'stock' }],
+  sort: { sortBy: 'volume', sortOrder: 'desc' },
+  range: [0, 20],
+});
+console.log(page.totalCount, page.rows);
+```
+
+Each row has an exchange-qualified `symbol` and a `values` object keyed by the
+requested columns. Values retain their upstream types, including null. Columns
+must be nonempty and unique. Unknown fields and invalid server filters throw
+`TradingViewError` with code `HTTP_ERROR`; they do not silently become empty results.
+
+The default market is `global`. Other upstream universes include `america`,
+`crypto` and `forex`. Exact column names, filter operations and available markets
+are controlled by TradingView, not a stable schema owned by this package.
+Use `symbols: ['NASDAQ:AAPL']` to restrict the scan to explicit tickers.
+
+`range` is zero-based and end-exclusive, defaulting to `[0, 50]`. Request subsequent
+pages explicitly. Rankings can change between requests; pages are not a transactionally
+consistent snapshot. There is no automatic unbounded pagination, polling or retry.
+
+The second argument accepts `credentials`, `fetch`, `headers` and `signal`.
+Account cookies may be supplied but do not grant paid exchange rights. This is
+**not a real-time screener subscription**: delays and entitlements remain upstream.
+Use `watchQuotes` separately when you need quote updates for selected symbols.
+
+## Live evidence
+
+On 3 October 2026 an anonymous America scan with stock filters, volume sorting and
+`name`, `close`, `volume`, `Stoch.RSI.D` returned a total count and two typed rows.
+This establishes the request/response contract, not paid real-time availability.

package/docs/v4-backlog-triage.md

@@ -138,3 +138,15 @@ No issues/legacy PRs were closed, and no contributor comments were sent by this
 - Dependency audit: baseline had two moderate entries for the same Vitest/mocker advisory; patched development dependency in this change.
 - No new authenticated, private-script, Premium or long-duration claims are made.
 - No npm publication or promotion of the `latest` tag is part of this change.
+
+## Screener follow-up
+
+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).

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.2",
+  "version": "4.0.0-beta.4",
   "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",