@mathieuc/tradingview 3.5.2 → 4.0.0-beta.0

package/dist/data/operation.js

@@ -0,0 +1,205 @@
+import { TradingViewClient } from '../client/client.js';
+import { TradingViewError, toTradingViewError } from '../errors.js';
+export const DEFAULT_TIMEOUT_MS = 15_000;
+function abortError(signal) {
+    const { reason } = signal;
+    const message = reason instanceof Error ? reason.message : reason ? String(reason) : 'Aborted';
+    return new TradingViewError('ABORTED', message, { cause: reason });
+}
+export function validateTimeout(timeoutMs) {
+    const value = timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new TradingViewError('INVALID_ARGUMENT', 'timeoutMs must be a positive number');
+    }
+    return value;
+}
+export function validateSymbol(symbol) {
+    if (typeof symbol !== 'string' || !symbol.trim()) {
+        throw new TradingViewError('INVALID_ARGUMENT', 'symbol is required');
+    }
+    return symbol.trim();
+}
+export function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw abortError(signal);
+}
+function connect(options) {
+    if (options.client) {
+        if (options.client.isClosed)
+            throw new TradingViewError('INVALID_STATE', 'The provided client is closed');
+        return { client: options.client, release: async () => { } };
+    }
+    const client = new TradingViewClient({ ...options.clientOptions, credentials: options.credentials });
+    return { client, release: () => client.close() };
+}
+/**
+ * Runs a one-shot operation with timeout, abort and guaranteed cleanup:
+ * sessions are removed and an owned connection is closed before settling.
+ */
+export function runOperation(options, description, start) {
+    let timeoutMs;
+    let connection;
+    try {
+        timeoutMs = validateTimeout(options.timeoutMs);
+        throwIfAborted(options.signal);
+        connection = connect(options);
+    }
+    catch (error) {
+        return Promise.reject(toTradingViewError(error, 'INVALID_ARGUMENT'));
+    }
+    const { client } = connection;
+    const { signal } = options;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let cleanup;
+        const unsubscribers = [];
+        const finish = (error, value) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', onAbort);
+            for (const off of unsubscribers)
+                off();
+            try {
+                cleanup?.();
+            }
+            catch {
+                // Cleanup must never hide the result.
+            }
+            connection.release().catch(() => { }).then(() => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(value);
+            });
+        };
+        const onAbort = () => finish(abortError(signal));
+        const timer = setTimeout(() => {
+            finish(new TradingViewError('TIMEOUT', `${description} timed out after ${timeoutMs} ms`));
+        }, timeoutMs);
+        signal?.addEventListener('abort', onAbort, { once: true });
+        unsubscribers.push(client.on('error', (error) => finish(error)), client.on('close', () => finish(new TradingViewError('DISCONNECTED', `Connection closed during ${description}`))));
+        try {
+            cleanup = start({
+                client,
+                resolve: (value) => finish(undefined, value),
+                reject: (error) => finish(toTradingViewError(error)),
+            });
+        }
+        catch (error) {
+            finish(toTradingViewError(error, 'INVALID_ARGUMENT'));
+        }
+    });
+}
+/**
+ * Starts a watcher. The returned promise resolves once `ready()` is called
+ * and rejects on timeout, abort or failure before that.
+ */
+export function startWatcher(options, description, handlers, start, build) {
+    let timeoutMs;
+    let connection;
+    try {
+        timeoutMs = validateTimeout(options.timeoutMs);
+        throwIfAborted(options.signal);
+        connection = connect(options);
+    }
+    catch (error) {
+        return Promise.reject(toTradingViewError(error, 'INVALID_ARGUMENT'));
+    }
+    const { client } = connection;
+    const { signal } = options;
+    let active = true;
+    let started = false;
+    let cleanup;
+    let stopPromise;
+    let resolveClosed;
+    const closed = new Promise((resolve) => { resolveClosed = resolve; });
+    const unsubscribers = [];
+    let resolveStart;
+    let rejectStart;
+    const startPromise = new Promise((resolve, reject) => {
+        resolveStart = resolve;
+        rejectStart = reject;
+    });
+    const report = (error) => {
+        try {
+            handlers.onError?.(error);
+        }
+        catch (listenerError) {
+            console.error('[tradingview] onError callback threw:', listenerError);
+        }
+    };
+    const stop = () => {
+        if (stopPromise)
+            return stopPromise;
+        active = false;
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        for (const off of unsubscribers)
+            off();
+        try {
+            cleanup?.();
+        }
+        catch {
+            // Ignore cleanup failures.
+        }
+        stopPromise = connection.release().catch(() => { }).then(() => resolveClosed());
+        return stopPromise;
+    };
+    const fail = (raw) => {
+        if (!active)
+            return;
+        const error = toTradingViewError(raw);
+        const closing = stop();
+        if (!started)
+            closing.then(() => rejectStart(error));
+        else
+            report(error);
+    };
+    const watcher = build({
+        stop,
+        closed,
+        get isActive() {
+            return active;
+        },
+    });
+    const onAbort = () => fail(abortError(signal));
+    const timer = setTimeout(() => {
+        if (!started)
+            fail(new TradingViewError('TIMEOUT', `${description} timed out after ${timeoutMs} ms`));
+    }, timeoutMs);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    unsubscribers.push(client.on('error', (error) => fail(error)), client.on('close', () => fail(new TradingViewError('DISCONNECTED', `Connection closed during ${description}`))));
+    try {
+        cleanup = start({
+            client,
+            ready: () => {
+                if (!active || started)
+                    return;
+                started = true;
+                clearTimeout(timer);
+                resolveStart(watcher);
+            },
+            fail,
+            warn: (error) => {
+                if (active)
+                    report(toTradingViewError(error));
+            },
+            isActive: () => active,
+        });
+    }
+    catch (error) {
+        fail(error);
+    }
+    return startPromise;
+}
+/** Converts a Date or Unix time (seconds) into Unix seconds. */
+export function toUnixSeconds(value, name) {
+    if (value === undefined)
+        return undefined;
+    const seconds = value instanceof Date ? Math.floor(value.getTime() / 1000) : value;
+    if (!Number.isFinite(seconds))
+        throw new TradingViewError('INVALID_ARGUMENT', `${name} must be a Date or Unix seconds`);
+    return seconds;
+}

package/dist/data/provider.d.ts

@@ -0,0 +1,23 @@
+import type { Candle } from '../chart/types.js';
+import { type CandleHandlers, type WatchCandlesQuery } from './candles.js';
+import type { ConnectionOptions } from './operation.js';
+/** Minimum lifecycle required of a streaming candle source. */
+export interface CandleSourceWorker {
+    /** First usable snapshot and subsequent updates, oldest first. */
+    readonly latest: readonly Candle[];
+    /** Releases resources. Safe to call more than once. */
+    stop(): Promise<void>;
+}
+/**
+ * Source-neutral candle contract. Applications can provide another market
+ * data source without emulating TradingView's charts or websocket protocol.
+ */
+export interface MarketDataProvider {
+    watchCandles(query: WatchCandlesQuery, handlers: CandleHandlers): Promise<CandleSourceWorker>;
+}
+/** Default candle source backed by TradingView, with optional connection defaults. */
+export declare class TradingViewProvider implements MarketDataProvider {
+    private readonly connection;
+    constructor(connection?: ConnectionOptions);
+    watchCandles(query: WatchCandlesQuery, handlers: CandleHandlers): Promise<CandleSourceWorker>;
+}

package/dist/data/provider.js

@@ -0,0 +1,11 @@
+import { watchCandles } from './candles.js';
+/** Default candle source backed by TradingView, with optional connection defaults. */
+export class TradingViewProvider {
+    connection;
+    constructor(connection = {}) {
+        this.connection = connection;
+    }
+    watchCandles(query, handlers) {
+        return watchCandles({ ...this.connection, ...query }, handlers);
+    }
+}

package/dist/data/quotes.d.ts

@@ -0,0 +1,33 @@
+import type { TradingSession } from '../chart/types.js';
+import type { QuoteData, QuoteField, QuoteFieldPreset } from '../quote/fields.js';
+import { type OperationOptions, type WatchHandlers, type Watcher } from './operation.js';
+export interface QuoteOptions extends OperationOptions {
+    /** `all` (default), `price`, or a list of fields. */
+    fields?: QuoteFieldPreset | readonly QuoteField[];
+    /** Trading session. Default: `regular`. */
+    session?: TradingSession;
+}
+export interface QuoteQuery extends QuoteOptions {
+    symbol: string;
+}
+export interface QuotesQuery extends QuoteOptions {
+    symbols: readonly string[];
+}
+/** Gets quotes for several symbols at once, keyed by symbol. */
+export declare function getQuotes(query: QuotesQuery | readonly string[]): Promise<Record<string, QuoteData>>;
+/** Gets the current quote of a symbol (last price, change, volume...). */
+export declare function getQuote(query: QuoteQuery | string): Promise<QuoteData>;
+export interface QuoteHandlers extends WatchHandlers {
+    /** Receives the merged quote and the fields that changed. */
+    onData(symbol: string, quote: QuoteData, changes: QuoteData): void;
+}
+export interface QuoteWatcher extends Watcher {
+    /** Latest quote per symbol. */
+    readonly latest: Readonly<Record<string, QuoteData>>;
+}
+/**
+ * Streams quotes for one or more symbols. Resolves once every symbol has
+ * loaded (or failed: failures go to `onError`; if every symbol fails, the
+ * promise rejects). Call `stop()` when finished.
+ */
+export declare function watchQuotes(query: QuotesQuery, handlers: QuoteHandlers): Promise<QuoteWatcher>;

package/dist/data/quotes.js

@@ -0,0 +1,117 @@
+import { TradingViewError } from '../errors.js';
+import { runOperation, startWatcher, validateSymbol, } from './operation.js';
+function validateSymbols(symbols) {
+    if (!Array.isArray(symbols) || symbols.length === 0) {
+        throw new TradingViewError('INVALID_ARGUMENT', 'symbols must be a non-empty array');
+    }
+    return [...new Set(symbols.map(validateSymbol))];
+}
+/** Gets quotes for several symbols at once, keyed by symbol. */
+export function getQuotes(query) {
+    const options = Array.isArray(query) ? { symbols: query } : query;
+    let symbols;
+    try {
+        symbols = validateSymbols(options.symbols);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    return runOperation(options, `getQuotes(${symbols.join(', ')})`, ({ client, resolve, reject }) => {
+        const session = client.createQuoteSession({ fields: options.fields });
+        const results = {};
+        let pending = symbols.length;
+        for (const symbol of symbols) {
+            const sub = session.subscribe(symbol, { session: options.session });
+            sub.on('error', reject);
+            sub.once('loaded', () => {
+                results[symbol] = sub.data;
+                pending -= 1;
+                if (pending === 0)
+                    resolve(results);
+            });
+        }
+        return () => session.delete();
+    });
+}
+/** Gets the current quote of a symbol (last price, change, volume...). */
+export async function getQuote(query) {
+    const options = typeof query === 'string' ? { symbol: query } : query;
+    const symbol = validateSymbol(options.symbol);
+    const quotes = await getQuotes({ ...options, symbols: [symbol] });
+    return quotes[symbol];
+}
+/**
+ * Streams quotes for one or more symbols. Resolves once every symbol has
+ * loaded (or failed: failures go to `onError`; if every symbol fails, the
+ * promise rejects). Call `stop()` when finished.
+ */
+export function watchQuotes(query, handlers) {
+    let symbols;
+    try {
+        if (typeof handlers?.onData !== 'function')
+            throw new TradingViewError('INVALID_ARGUMENT', 'onData must be a function');
+        symbols = validateSymbols(query.symbols);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    const latest = {};
+    return startWatcher(query, `watchQuotes(${symbols.join(', ')})`, handlers, (ctx) => {
+        const session = ctx.client.createQuoteSession({ fields: query.fields });
+        const settled = new Set();
+        const errors = [];
+        let loaded = 0;
+        const settle = (symbol, ok) => {
+            if (settled.has(symbol))
+                return;
+            settled.add(symbol);
+            if (ok)
+                loaded += 1;
+            if (settled.size < symbols.length)
+                return;
+            if (loaded === 0)
+                ctx.fail(errors[0]);
+            else {
+                for (const error of errors)
+                    ctx.warn(error);
+                ctx.ready();
+            }
+        };
+        const subscriptions = symbols.map((symbol) => {
+            const sub = session.subscribe(symbol, { session: query.session });
+            sub.on('data', (quote, changes) => {
+                latest[symbol] = quote;
+                if (!ctx.isActive())
+                    return;
+                try {
+                    handlers.onData(symbol, quote, changes);
+                }
+                catch (error) {
+                    ctx.warn(new TradingViewError('CALLBACK_ERROR', 'onData callback threw', { cause: error }));
+                }
+            });
+            sub.on('loaded', () => settle(symbol, true));
+            sub.on('error', (error) => {
+                if (error.code === 'DISCONNECTED')
+                    return; // Reported by the watcher itself.
+                if (settled.size < symbols.length && !settled.has(symbol)) {
+                    errors.push(error);
+                    settle(symbol, false);
+                }
+                else
+                    ctx.warn(error);
+            });
+            return sub;
+        });
+        return () => {
+            for (const sub of subscriptions)
+                sub.close();
+            session.delete();
+        };
+    }, (base) => ({
+        stop: base.stop,
+        closed: base.closed,
+        get isActive() { return base.isActive; },
+        get latest() { return { ...latest }; },
+    }));
+}

package/dist/data/symbols.d.ts

@@ -0,0 +1,9 @@
+import type { SymbolInfo, TradingSession } from '../chart/types.js';
+import { type OperationOptions } from './operation.js';
+export interface SymbolInfoQuery extends OperationOptions {
+    symbol: string;
+    session?: TradingSession;
+    currency?: string;
+}
+/** Resolves a symbol: exchange, currency, session, price scale, type... */
+export declare function getSymbolInfo(query: SymbolInfoQuery | string): Promise<SymbolInfo>;

package/dist/data/symbols.js

@@ -0,0 +1,19 @@
+import { runOperation, validateSymbol } from './operation.js';
+/** Resolves a symbol: exchange, currency, session, price scale, type... */
+export function getSymbolInfo(query) {
+    const options = typeof query === 'string' ? { symbol: query } : query;
+    let symbol;
+    try {
+        symbol = validateSymbol(options.symbol);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    return runOperation(options, `getSymbolInfo(${symbol})`, ({ client, resolve, reject }) => {
+        const chart = client.createChart();
+        chart.on('error', reject);
+        chart.on('symbolLoaded', resolve);
+        chart.setMarket(symbol, { count: 1, session: options.session, currency: options.currency });
+        return () => chart.delete();
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,53 @@
+/** Machine-readable error categories raised by this library. */
+export type TradingViewErrorCode = 
+/** The server rejected a websocket packet and closed the connection. */
+'PROTOCOL_ERROR'
+/** The websocket could not be opened or failed. */
+ | 'CONNECTION_ERROR'
+/** The websocket closed while an operation was still waiting for data. */
+ | 'DISCONNECTED'
+/** Credentials were rejected or the account could not be loaded. */
+ | 'AUTH_ERROR'
+/** `symbol_error`: the symbol could not be resolved. */
+ | 'SYMBOL_ERROR'
+/** `series_error`: the series could not be loaded (permissions, timeframe...). */
+ | 'SERIES_ERROR'
+/** `critical_error`: the server rejected a chart or replay command. */
+ | 'CRITICAL_ERROR'
+/** `study_error`: an indicator failed on the server. */
+ | 'STUDY_ERROR'
+/** A quote symbol returned an error status. */
+ | 'QUOTE_ERROR'
+/** A strategy report or compressed payload could not be decoded. */
+ | 'PARSE_ERROR'
+/** A method was called in a state where it cannot work. */
+ | 'INVALID_STATE'
+/** An argument is invalid. */
+ | 'INVALID_ARGUMENT'
+/** An HTTP endpoint answered with an unexpected status or payload. */
+ | 'HTTP_ERROR'
+/** The requested resource does not exist or is not accessible. */
+ | 'NOT_FOUND'
+/** The server answered but returned no usable data. */
+ | 'NO_DATA'
+/** An operation did not complete in time. */
+ | 'TIMEOUT'
+/** An operation was cancelled through an `AbortSignal`. */
+ | 'ABORTED'
+/** A user-supplied callback threw while processing data. */
+ | 'CALLBACK_ERROR';
+export interface TradingViewErrorOptions {
+    /** Raw details sent by the server, when available. */
+    details?: unknown;
+    cause?: unknown;
+}
+/** Every error produced by this library is a `TradingViewError`. */
+export declare class TradingViewError extends Error {
+    readonly name = "TradingViewError";
+    readonly code: TradingViewErrorCode;
+    /** Raw details sent by the server, when available. */
+    readonly details: unknown;
+    constructor(code: TradingViewErrorCode, message: string, options?: TradingViewErrorOptions);
+}
+/** Normalises any thrown value into a `TradingViewError`. */
+export declare function toTradingViewError(error: unknown, fallbackCode?: TradingViewErrorCode): TradingViewError;

package/dist/errors.js

@@ -0,0 +1,24 @@
+/** Every error produced by this library is a `TradingViewError`. */
+export class TradingViewError extends Error {
+    name = 'TradingViewError';
+    code;
+    /** Raw details sent by the server, when available. */
+    details;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.code = code;
+        this.details = options.details;
+    }
+}
+/** Normalises any thrown value into a `TradingViewError`. */
+export function toTradingViewError(error, fallbackCode = 'CONNECTION_ERROR') {
+    if (error instanceof TradingViewError)
+        return error;
+    if (error instanceof Error) {
+        if (error.name === 'AbortError') {
+            return new TradingViewError('ABORTED', error.message || 'Aborted', { cause: error });
+        }
+        return new TradingViewError(fallbackCode, error.message, { cause: error });
+    }
+    return new TradingViewError(fallbackCode, String(error), { details: error });
+}

package/dist/events.d.ts

@@ -0,0 +1,36 @@
+type EventMap = {
+    [event: string]: unknown[];
+};
+export type Listener<Args extends unknown[]> = (...args: Args) => void;
+/** Unsubscribes the listener it was returned for. */
+export type Unsubscribe = () => void;
+/** Catch-all listener: receives the event name, then the event arguments. */
+export type AnyListener<Events extends EventMap> = (...args: {
+    [K in keyof Events & string]: [event: K, ...args: Events[K]];
+}[keyof Events & string]) => void;
+/**
+ * Small typed event emitter shared by clients, sessions and studies.
+ *
+ * Listener exceptions are reported without interrupting other listeners or
+ * crashing the host process. An `error` event without any
+ * listener is written to `console.error` instead of being silently dropped.
+ */
+export declare class Emitter<Events extends EventMap> {
+    #private;
+    /** Adds a listener and returns a function that removes it. */
+    on<K extends keyof Events & string>(event: K, listener: Listener<Events[K]>): Unsubscribe;
+    /** Adds a listener called at most once. */
+    once<K extends keyof Events & string>(event: K, listener: Listener<Events[K]>): Unsubscribe;
+    /** Removes a listener. */
+    off<K extends keyof Events & string>(event: K, listener: Listener<Events[K]>): void;
+    /** Listens to every event; receives the event name first. */
+    onAny(listener: AnyListener<Events>): Unsubscribe;
+    /** Number of listeners for an event (catch-all listeners excluded). */
+    listenerCount(event: keyof Events & string): number;
+    /** True when the event has a listener, including catch-all listeners. */
+    protected hasListeners(event: keyof Events & string): boolean;
+    /** Removes every listener. */
+    protected removeAllListeners(): void;
+    protected emit<K extends keyof Events & string>(event: K, ...args: Events[K]): void;
+}
+export {};

package/dist/events.js

@@ -0,0 +1,70 @@
+/**
+ * Small typed event emitter shared by clients, sessions and studies.
+ *
+ * Listener exceptions are reported without interrupting other listeners or
+ * crashing the host process. An `error` event without any
+ * listener is written to `console.error` instead of being silently dropped.
+ */
+export class Emitter {
+    #listeners = new Map();
+    #anyListeners = new Set();
+    /** Adds a listener and returns a function that removes it. */
+    on(event, listener) {
+        let set = this.#listeners.get(event);
+        if (!set) {
+            set = new Set();
+            this.#listeners.set(event, set);
+        }
+        set.add(listener);
+        return () => this.off(event, listener);
+    }
+    /** Adds a listener called at most once. */
+    once(event, listener) {
+        const wrapper = (...args) => {
+            this.off(event, wrapper);
+            listener(...args);
+        };
+        return this.on(event, wrapper);
+    }
+    /** Removes a listener. */
+    off(event, listener) {
+        this.#listeners.get(event)?.delete(listener);
+    }
+    /** Listens to every event; receives the event name first. */
+    onAny(listener) {
+        this.#anyListeners.add(listener);
+        return () => { this.#anyListeners.delete(listener); };
+    }
+    /** Number of listeners for an event (catch-all listeners excluded). */
+    listenerCount(event) {
+        return this.#listeners.get(event)?.size ?? 0;
+    }
+    /** True when the event has a listener, including catch-all listeners. */
+    hasListeners(event) {
+        return this.listenerCount(event) > 0 || this.#anyListeners.size > 0;
+    }
+    /** Removes every listener. */
+    removeAllListeners() {
+        this.#listeners.clear();
+        this.#anyListeners.clear();
+    }
+    emit(event, ...args) {
+        const set = this.#listeners.get(event);
+        if (event === 'error' && !set?.size && !this.#anyListeners.size) {
+            console.error('[tradingview]', ...args);
+            return;
+        }
+        for (const listener of [...(set ?? [])])
+            Emitter.#call(() => listener(...args));
+        for (const listener of [...this.#anyListeners])
+            Emitter.#call(() => listener(event, ...args));
+    }
+    static #call(fn) {
+        try {
+            fn();
+        }
+        catch (error) {
+            console.error('[tradingview] Listener threw:', error);
+        }
+    }
+}

package/dist/http/account.d.ts

@@ -0,0 +1,47 @@
+import { type Credentials, type HttpOptions } from './request.js';
+/** A TradingView account. */
+export interface User {
+    id: number;
+    username: string;
+    firstName: string;
+    lastName: string;
+    reputation: number;
+    following: number;
+    followers: number;
+    notifications: {
+        user: number;
+        following: number;
+    };
+    /** `sessionid` cookie. Keep it secret. */
+    session: string;
+    /** `sessionid_sign` cookie. Keep it secret. */
+    signature: string;
+    sessionHash: string;
+    privateChannel: string;
+    /** Websocket auth token. Keep it secret. */
+    authToken: string;
+    joinDate: Date;
+}
+export interface LoginOptions extends HttpOptions {
+    username: string;
+    password: string;
+    /** Keep the session alive longer. Default: true. */
+    remember?: boolean;
+    /** Custom user agent prefix. */
+    userAgent?: string;
+}
+/**
+ * Signs in with a username/email and password and returns the account with
+ * its session cookies. Accounts with 2FA or captcha challenges are not supported.
+ */
+export declare function loginUser(options: LoginOptions): Promise<User>;
+export interface GetUserOptions extends HttpOptions {
+    /** Page used to read the account, for example `https://fr.tradingview.com/`. */
+    location?: string;
+    /** Maximum number of redirects to follow. Default: 5. */
+    maxRedirects?: number;
+}
+/** Parses the account embedded in a TradingView HTML page. */
+export declare function parseUserPage(page: string, credentials: Credentials): User;
+/** Loads the account behind `sessionid` (and `sessionid_sign`) cookies. */
+export declare function getUser(credentials: Credentials, options?: GetUserOptions): Promise<User>;