@vninvestcharts/widget 0.0.0-stage → 0.2.0

package/dist/adapters/index.d.mts

@@ -0,0 +1,673 @@
+import { StockDataAdapter, SourceSemanticsDescriptor, Timeframe, CoverageFragment, OHLCVBar, Unsubscribe, Trade, OrderbookSnapshot, SymbolInfo } from '@vninvestcharts/engine-core';
+
+/**
+ * Shared VNInvest domain type definitions.
+ *
+ * This module is the canonical home for cross-layer types used by
+ * widget/core/lib modules. Demo should consume these types, not own them.
+ */
+interface TechnicalIndicators {
+    bias?: number;
+    rsi14?: number;
+    sma20?: number;
+    sma50?: number;
+    sma200?: number;
+    ema9?: number;
+    ema21?: number;
+    macd?: number;
+    macd_signal?: number;
+    macd_histogram?: number;
+    atr_14?: number;
+    bb_upper?: number;
+    bb_middle?: number;
+    bb_lower?: number;
+    volume_sma20?: number;
+}
+interface StockItem {
+    symbol: string;
+    company_name: string;
+    exchange: string;
+    sector?: string;
+}
+type WhaleSizeClass = "small" | "shark" | "whale";
+type WhaleSide = "buy" | "sell";
+interface WhaleOrder {
+    /** ISO 8601 timestamp string */
+    ts: string;
+    price: number;
+    volume: number;
+    matched_value: number;
+    side: WhaleSide;
+    size_class: WhaleSizeClass;
+}
+interface WhaleOrderSummary {
+    buy_value: number;
+    sell_value: number;
+    shark_buy: number;
+    shark_sell: number;
+    whale_buy: number;
+    whale_sell: number;
+    small_buy: number;
+    small_sell: number;
+}
+interface WhaleFeedResponse {
+    symbol: string;
+    whale_orders: WhaleOrder[];
+    summary: WhaleOrderSummary;
+    /**
+     * Native backend alerts (GET /realtime/whale-feed/{symbol}/, verified live 2026-09-21).
+     * Present when the server returns `{symbol, alerts[]}` instead of the legacy
+     * `{summary, whale_orders}` contract. Rendered as a notification list — never
+     * coerced into WhaleOrder (alerts carry no price/volume).
+     */
+    alerts?: WhaleAlert[];
+}
+/** One native whale/signal alert from GET /realtime/whale-feed/{symbol}/. */
+interface WhaleAlert {
+    /** UUID string. */
+    id: string;
+    /** e.g. "signal" | "whale". */
+    alert_type: string;
+    /** e.g. "low" | "medium" | "high". */
+    severity: string;
+    title: string;
+    /** Score-ish string on signal alerts — NOT a VND value. Kept raw. */
+    value: string | number | null;
+    /** e.g. "buy" | "sell". */
+    direction: string;
+    /** ISO 8601 timestamp string. */
+    triggered_at: string;
+}
+/** One intraday CVD bucket from compute_cvd_series. */
+interface CVDPoint {
+    /** ISO 8601 datetime - today + bucket start time. */
+    bucket_ts: string;
+    buy_value: number;
+    sell_value: number;
+    /** Net delta for this bucket (buy_value - sell_value). */
+    cvd: number;
+    /** Running cumulative delta from session start. */
+    cumulative_cvd: number;
+}
+type DarkFlowSignalType = "none" | "absorption" | "iceberg" | "twap_bot" | "mixed";
+/** Dark flow strength result from detect_dark_flow. */
+interface DarkFlowResult {
+    signal_type: DarkFlowSignalType;
+    /** 0-100 composite strength score. */
+    strength: number;
+    /** 0-1 confidence. */
+    confidence: number;
+    components?: Record<string, unknown>;
+    triggered_at?: string | null;
+}
+interface OrderFlowSignal {
+    id: number | string;
+    symbol: string;
+    signal_type: string;
+    strength: number;
+    confidence: number;
+    tick_rate: number;
+    small_order_ratio: number;
+    cvd_at_signal: number | null;
+    price_at_signal: number | null;
+    created_at: string;
+    event_id: string | null;
+    severity?: string;
+}
+/** Response from GET /api/stock-management/stocks/<symbol>/order-flow/. */
+interface OrderFlowResponse {
+    ok: boolean;
+    symbol: string;
+    window: string;
+    window_minutes: number;
+    latest_signal: OrderFlowSignal | null;
+    signals: OrderFlowSignal[];
+    cvd_series: CVDPoint[];
+    dark_flow: DarkFlowResult;
+    tick_rate: Record<string, unknown>;
+    size_distribution: Record<string, unknown>;
+}
+/** A single intraday tape entry (one matched trade or large order). */
+interface TapeEntry {
+    /** Unique identifier for React keying (server id or client-generated). */
+    id: string;
+    /** ISO 8601 timestamp of the trade. */
+    ts: string;
+    /** Trade price. */
+    price: number;
+    /** Volume in shares/contracts. */
+    volume: number;
+    /** Trade value in VND (raw, not billions). */
+    value: number;
+    /** Direction of the aggressive side. */
+    side: "buy" | "sell" | "unknown";
+    /** True when value exceeds whale threshold - triggers highlight. */
+    is_whale: boolean;
+}
+/** HTTP envelope for GET /core/v1/market-data/intraday-tape/ */
+interface TapeResponse {
+    ok: boolean;
+    symbol: string;
+    entries: TapeEntry[];
+}
+/** Decision signal returned by AI advisory session. */
+type AdvisoryDecision = "STRONG_BUY" | "BUY" | "HOLD" | "SELL" | "STRONG_SELL";
+/** Per-agent score within an advisory session response. */
+interface AgentScore {
+    /** Agent identifier: "whale" | "tech" | "risk" | "sentiment". */
+    name: string;
+    /** Portfolio weight (0-1), e.g. 0.4 for whale agent. */
+    weight: number;
+    /** Raw score in [−100, 100]. Positive = bullish. */
+    score: number;
+    /** Signal label for this agent. */
+    signal: AdvisoryDecision;
+    /** Markdown-formatted explanation from this agent. */
+    explanation: string;
+}
+/** Full advisory result returned from POST /api/stock_ai_advisory_session/. */
+interface AdvisoryResult {
+    /** Aggregated decision across all agents. */
+    decision: AdvisoryDecision;
+    /** Aggregate confidence in [0, 1]. */
+    confidence: number;
+    /** Weighted composite score in [−100, 100]. */
+    weighted_score: number;
+    /** Per-agent breakdown - typically 4 agents. */
+    agents: readonly AgentScore[];
+    /** Markdown summary explanation. */
+    explanation: string;
+    /** ISO 8601 UTC timestamp when the analysis was triggered. */
+    triggered_at: string;
+}
+/** HTTP envelope for POST /api/stock_ai_advisory_session/ (legacy, 404 on current backend). */
+interface AdvisorySessionResponse {
+    ok: boolean;
+    symbol: string;
+    result?: AdvisoryResult;
+    /** Error message when ok is false. */
+    error?: string;
+}
+/** Decision block inside aggregate — actions are lowercase backend values. */
+interface AdvisoryDecisionBlock {
+    action: string | null;
+    risk: string | null;
+    score_band: string | null;
+    score: number | null;
+}
+/** Aggregate block of the native advisory session payload. */
+interface AdvisoryAggregate {
+    advisory_id: string;
+    session_date: string;
+    selected_trade_date: string;
+    contract_version: string;
+    decision: AdvisoryDecisionBlock;
+}
+/** One analysis component (indicator/flow/summary) of the native session. */
+interface AdvisoryComponent {
+    id: number;
+    symbol: string;
+    component_type: string;
+    indicator_name: string;
+    status: string;
+    confidence_score: number;
+    suggested_action: string;
+    rationale_text: string;
+    timeframe: string;
+    include_in_summary: boolean;
+    is_deleted: boolean;
+    created_at: string;
+    updated_at: string;
+}
+/** Executive summary built from active components. */
+interface AdvisoryExecutiveSummary {
+    symbol: string;
+    session_date: string;
+    strategy_action: string | null;
+    risk_level: string | null;
+    overall_confidence: number | null;
+    score_band: string | null;
+    summary_text: string;
+    component_ids: number[];
+    active_components_count: number;
+    source: string;
+}
+/** Native record fields spread at session top level by the backend. */
+interface AdvisoryRecordFields {
+    status?: string;
+    advisory_text?: string | null;
+    ai_model?: string | null;
+    tokens_used?: number | null;
+    strategy_action?: string | null;
+    risk_level?: string | null;
+    confidence_score?: number | null;
+}
+/**
+ * GET /core/v1/stock-management/stocks/{symbol}/ai-advisory-session/ response.
+ * Empty state: `{queued: false, reason: "no_advisory_data", advisory: null, ...}`.
+ * Record state: advisory/aggregate/components/executive_summary populated.
+ */
+interface AdvisorySessionV2 extends AdvisoryRecordFields {
+    queued: boolean;
+    symbol: string;
+    contract_version: string;
+    reason?: string | null;
+    message?: string | null;
+    advisory: Record<string, unknown> | null;
+    aggregate: AdvisoryAggregate | null;
+    components: AdvisoryComponent[];
+    deleted_components: AdvisoryComponent[];
+    executive_summary: AdvisoryExecutiveSummary | null;
+    executive_summaries: AdvisoryExecutiveSummary[];
+    user_ai_provider: string | null;
+    effective_ai_provider: string | null;
+    effective_ai_model: string | null;
+    effective_ai_source: string | null;
+}
+interface RawOHLCVBar {
+    date: Date;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+    technical?: Partial<TechnicalIndicators>;
+}
+
+interface AdImageSource {
+    default: string;
+    retina?: string;
+    svg?: string;
+}
+interface AdCampaign {
+    campaign_id: string;
+    image_source: AdImageSource;
+    video_url?: string;
+    click_url: string;
+    click_tracking_url: string;
+    impression_tracking_url: string;
+    width: number;
+    height: number;
+}
+
+/**
+ * WP-02: VNInvestClient — moved from src/demo/dataSources/
+ * HTTP client for the VNInvest REST API with PAT Bearer authentication.
+ * No React dependency — safe to use in non-component contexts.
+ */
+
+/** Resolve API base URL (priority: global override → localStorage → current origin → default). */
+declare function resolveApiBase(): string;
+/** Map of common timeframe aliases to VNInvest canonical formats. */
+declare const TIMEFRAME_MAP: Record<string, string>;
+/** Response of GET /core/v1/widget/ad — array of eligible campaigns. */
+interface WidgetAdResponse {
+    campaigns: AdCampaign[];
+}
+interface AuthMeResponse {
+    access?: string;
+    refresh?: string;
+    token?: string;
+    token_prefix?: string;
+    plan: string;
+    active_pat_count: number;
+    max_active_pats: number;
+    tenant: {
+        tenant_id: string;
+        tenant_code: string;
+        display_name: string;
+        plan: string;
+        max_active_pats: number;
+        status: string;
+        features?: string[];
+    };
+    user: {
+        id: number;
+        username: string;
+        email: string;
+        first_name: string;
+        last_name: string;
+        is_staff: boolean;
+    };
+    abilities: string[];
+    entitlements: Record<string, unknown>;
+}
+/** Parameters for the cursor-paged /bars/ endpoint. */
+type VNIBarsParams = {
+    type: "init";
+    symbol: string;
+    timeframe: string;
+    from?: number;
+    to?: number;
+    limit?: number;
+} | {
+    type: "backward";
+    symbol: string;
+    timeframe: string;
+    before: number;
+    limit: number;
+    snapshotId?: string;
+};
+/** Response from the cursor-paged /bars/ endpoint. */
+interface VNIBarsPageResponse {
+    bars: RawOHLCVBar[];
+    hasMoreBefore: boolean;
+    hasMoreAfter: boolean;
+    nextBefore: number | null;
+    nextAfter: number | null;
+    snapshotId: string | null;
+}
+
+type BarsHotWindowTelemetry = {
+    cacheHits: number;
+    inFlightCollapses: number;
+    networkRequests: number;
+    lastUpdatedAt: number | null;
+};
+type BarsHotWindowLoadGateStatus = "healthy" | "warning" | "rollback";
+type BarsHotWindowLoadGateThresholds = {
+    minimumObservedRequests: number;
+    healthySavedRequestRatio: number;
+    rollbackSavedRequestRatio: number;
+    healthyNetworkRequestRatio: number;
+    rollbackNetworkRequestRatio: number;
+};
+type BarsHotWindowLoadGateReport = {
+    status: BarsHotWindowLoadGateStatus;
+    reasons: readonly string[];
+    telemetry: BarsHotWindowTelemetry;
+    totalRequests: number;
+    cacheHitRatio: number;
+    collapseRatio: number;
+    networkRequestRatio: number;
+    savedRequestRatio: number;
+    thresholds: BarsHotWindowLoadGateThresholds;
+};
+interface WidgetAuthHandler {
+    getToken: () => string | Promise<string>;
+    getRefreshToken?: () => string | Promise<string>;
+    onTokensUpdated?: (tokens: {
+        patToken: string;
+        refreshToken?: string;
+    }) => void | Promise<void>;
+    onAuthError?: (error: Error) => void;
+}
+declare class VNInvestClient {
+    private _pat;
+    private _base;
+    private _authHandler?;
+    constructor(patToken?: string);
+    setAuthHandler(handler: WidgetAuthHandler): void;
+    setPAT(token: string): void;
+    /**
+     * Transport-only credential sync. Sets `_pat` WITHOUT touching storage —
+     * storage belongs to credentialStore alone. The SaaS context calls this before
+     * validation when its resolved credential (tenant > user > env) differs from
+     * what this transport carries; otherwise a user-pasted PAT sits in storage
+     * while requests go out with a stale or empty token, and the backend 401s with
+     * "Authentication credentials were not provided." No-op when equal.
+     */
+    syncTransportPat(token: string): void;
+    private _notifyPatChanged;
+    getPAT(): string;
+    setBase(url: string): void;
+    getBase(): string;
+    hasPAT(): boolean;
+    private buildHeaders;
+    private _fetch;
+    getChart(symbol: string, options?: {
+        timeframe?: string;
+        days?: number;
+    }): Promise<RawOHLCVBar[]>;
+    validateMe(): Promise<AuthMeResponse>;
+    /** Fetch eligible ad campaigns. Bearer PAT auto-attached; premium → empty list. */
+    fetchAd(): Promise<WidgetAdResponse>;
+    getBarsPage(params: VNIBarsParams): Promise<VNIBarsPageResponse>;
+    static __resetBarsHotWindowCacheForTests(): void;
+    static getBarsHotWindowTelemetry(): BarsHotWindowTelemetry;
+    static __getBarsHotWindowTelemetryForTests(): BarsHotWindowTelemetry;
+    getStocks(query?: string, exchange?: string): Promise<StockItem[]>;
+    getWhaleFeed(symbol: string): Promise<WhaleFeedResponse | null>;
+    getOrderFlow(symbol: string, window?: "5m" | "15m" | "30m" | "1h"): Promise<OrderFlowResponse | null>;
+    /** Shared GET/POST fetch for the native advisory session endpoint. */
+    private fetchAdvisorySessionV2;
+    /**
+     * Follow-up advisory V2: read the native AI advisory session.
+     * Returns the session in both empty (`reason: "no_advisory_data"`) and record states;
+     * null only on transport/auth failure. Never throws for empty sessions.
+     */
+    getAdvisorySessionV2(symbol: string): Promise<AdvisorySessionV2 | null>;
+    /**
+     * Follow-up advisory V2: trigger a manual refresh (queues generation server-side).
+     * Returns the updated session payload; null on transport/auth failure.
+     */
+    refreshAdvisorySession(symbol: string): Promise<AdvisorySessionV2 | null>;
+    /** @deprecated Legacy POST path 404s on current backends — use getAdvisorySessionV2. */
+    getAdvisorySession(symbol: string): Promise<AdvisorySessionResponse | null>;
+    getTapeEntries(symbol: string, pageSize?: number): Promise<TapeResponse | null>;
+    private _revalidateBarsHotWindow;
+}
+
+/**
+ * WP-03: VNInvestWebSocketClient — moved from src/demo/dataSources/
+ * WebSocket client for the VNInvest Realtime channel.
+ */
+interface TickerUpdateEvent {
+    event_type: "ticker_update";
+    symbol: string;
+    price: number;
+    current_price: number;
+    volume: number;
+    vwap?: number;
+    ts: string;
+    last_date?: string;
+    stale?: boolean;
+    seq?: number;
+    rsi_14?: number;
+    ma20_dist_pct?: number;
+    rvol?: number;
+    open_price?: number;
+    high_price?: number;
+    low_price?: number;
+    prev_price?: number | null;
+    change_value?: number | null;
+    change_pct?: number | null;
+}
+interface WhaleAlertWSEvent {
+    event_type: "whale_alert";
+    symbol: string;
+    side?: "buy" | "sell";
+    value?: number;
+    price?: number;
+    ts?: string;
+}
+type VNIWSEvent = TickerUpdateEvent | WhaleAlertWSEvent | {
+    event_type: string;
+    [key: string]: unknown;
+};
+declare class VNInvestWebSocketClient {
+    private static readonly MAX_RECONNECT_ATTEMPTS;
+    private static readonly RECONNECT_DELAY_MS;
+    private static readonly WS_PATH_CANDIDATES;
+    private ws;
+    private readonly pat;
+    private readonly apiBase;
+    private selectedWsPath;
+    private wsUnavailable;
+    private wsProbePromise;
+    private readonly subscribedSymbols;
+    private onTickerUpdateCb;
+    private onWhaleAlertCb;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private _isConnected;
+    private _destroyed;
+    constructor(pat: string, apiBase?: string);
+    get isConnected(): boolean;
+    get destroyed(): boolean;
+    buildWsUrl(path?: string): string;
+    private buildHttpProbeUrl;
+    private probeWsPath;
+    private resolveWsPath;
+    connect(): void;
+    private openConnection;
+    subscribe(symbols: string[]): void;
+    unsubscribe(symbols: string[]): void;
+    setOnTickerUpdate(cb: ((event: TickerUpdateEvent) => void) | null): void;
+    setOnWhaleAlert(cb: ((event: WhaleAlertWSEvent) => void) | null): void;
+    destroy(): void;
+    private handleRawMessage;
+    private scheduleReconnect;
+    private sendJson;
+}
+
+/**
+ * WP-04: VNInvestDataAdapter
+ *
+ * Implements `StockDataAdapter` interface, wrapping VNInvestClient (REST)
+ * and VNInvestWebSocketClient (WebSocket) into a single cohesive adapter.
+ *
+ * This is the OPTIONAL subpath import — NOT bundled in core IIFE.
+ * Usage:
+ *   import { VNInvestDataAdapter } from '@vninvestcharts/widget/adapters';
+ */
+
+/** Configuration for VNInvestDataAdapter. */
+interface VNInvestDataAdapterConfig {
+    /** Personal Access Token — never hardcoded, always passed by host app. */
+    patToken: string;
+    /** API base URL. Falls back to resolveApiBase() if not provided. */
+    apiBase?: string;
+}
+/**
+ * Full-featured data adapter for the VNInvest platform.
+ *
+ * Implements:
+ *   - fetchBarsInRange / fetchBarsBefore (cursor-paged /bars/ endpoint)
+ *   - subscribeToBar (WebSocket ticker_update)
+ *   - searchSymbols (GET /stocks/)
+ *
+ * Not implemented (VNInvest does not provide these endpoints):
+ *   - subscribeToTrades → returns no-op unsubscribe
+ *   - subscribeToOrderbook → returns no-op unsubscribe
+ */
+declare class VNInvestDataAdapter implements StockDataAdapter {
+    readonly name = "vninvest";
+    private client;
+    private wsClient;
+    private readonly barSubscribers;
+    private readonly snapshotIds;
+    private readonly lastBackfillCoverageMap;
+    private readonly lastRangeCoverageMap;
+    constructor(config: VNInvestDataAdapterConfig);
+    setAuthHandler(handler: WidgetAuthHandler): void;
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    private coverageKey;
+    getLastBackfillCoverage(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+    getLastRangeCoverage(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+    /** Expose the underlying REST client for advanced use cases. */
+    get restClient(): VNInvestClient;
+    /**
+     * Fetch bars in a date range.
+     * Uses the cursor-paged /bars/ endpoint with backward pagination.
+     *
+     * 504-guard: a single wide intraday window (e.g. 90d of 1H) times the server
+     * out — each request is capped to MAX_INTRADAY_SPAN_MS and the existing
+     * hasMoreAfter/nextAfter loop walks the remainder. Daily+ ranges are unaffected.
+     */
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date, chartId?: string, signal?: AbortSignal): Promise<readonly OHLCVBar[]>;
+    /**
+     * Fetch bars before a given anchor date (backward pagination).
+     */
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number, chartId?: string): Promise<readonly OHLCVBar[]>;
+    /**
+     * Subscribe to real-time bar updates via WebSocket.
+     * Maps ticker_update events to OHLCVBar callbacks.
+     */
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    /** Not supported by VNInvest — returns no-op. */
+    subscribeToTrades(_symbol: string, _onTrade: (trade: Trade) => void): Unsubscribe;
+    /** Not supported by VNInvest — returns no-op. */
+    subscribeToOrderbook(_symbol: string, _onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    /** Search symbols via GET /stocks/ endpoint. */
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+    /** Clean up: destroy WebSocket connection. */
+    destroy(): void;
+    private handleTickerUpdate;
+}
+
+/**
+ * WP-02: Bars paging policy — moved from src/demo/dataSources/
+ * Cursor-paged /bars/ endpoint response normalization.
+ */
+
+interface BarsPagingMeta {
+    hasMoreBefore: boolean;
+    hasMoreAfter: boolean;
+    nextBefore: number | null;
+    nextAfter: number | null;
+    snapshotId: string | null;
+}
+declare function normalizeBarsPagingMeta(payload: Record<string, unknown>, bars: readonly RawOHLCVBar[]): BarsPagingMeta;
+declare function buildBackwardPageRequest(meta: BarsPagingMeta, fallbackBefore: number, limit: number): {
+    before: number;
+    limit: number;
+    snapshotId?: string;
+} | null;
+
+interface UseWatchlistRealtimeSyncOptions {
+    /** Instance of the VNInvest WebSocket client. */
+    wsClient: VNInvestWebSocketClient | null;
+    /** Array of symbols to subscribe to in the watchlist/heatmap. */
+    symbols: string[];
+    /** Optional callback triggered on each state flush with the accumulated updates. */
+    onUpdate?: (updatedData: Map<string, TickerUpdateEvent>) => void;
+    /** Throttle duration in milliseconds. Defaults to 500ms. */
+    throttleMs?: number;
+}
+/**
+ * Hook to synchronize a list of symbols in real-time using VNInvestWebSocketClient.
+ * Uses throttled state updates to ensure smooth rendering of large watchlists/heatmaps.
+ */
+declare function useWatchlistRealtimeSync({ wsClient, symbols, onUpdate, throttleMs, }: UseWatchlistRealtimeSyncOptions): Map<string, TickerUpdateEvent>;
+
+declare class ContinuousFuturesStockDataAdapter implements StockDataAdapter {
+    private continuousAdapter;
+    private baseAdapter;
+    private symbol;
+    constructor(symbol: string, baseAdapter: StockDataAdapter);
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date, chartId?: string): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number, chartId?: string): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    subscribeToTrades(symbol: string, onTrade: (trade: Trade) => void): Unsubscribe;
+    subscribeToOrderbook(symbol: string, onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+    getSourceSemantics(): SourceSemanticsDescriptor;
+    getLastBackfillCoverage?(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+    getLastRangeCoverage?(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+}
+
+interface SourceRoute {
+    pattern: RegExp;
+    adapter: StockDataAdapter;
+}
+interface MultiSourceDataAdapterConfig {
+    routes: SourceRoute[];
+    defaultAdapter: StockDataAdapter;
+}
+declare class MultiSourceDataAdapter implements StockDataAdapter {
+    private readonly config;
+    private readonly _cache;
+    constructor(config: MultiSourceDataAdapterConfig);
+    private _resolve;
+    fetchBarsInRange(symbol: string, timeframe: Timeframe, from: Date, to: Date, chartId?: string): Promise<readonly OHLCVBar[]>;
+    fetchBarsBefore(symbol: string, timeframe: Timeframe, before: Date, limit?: number, chartId?: string): Promise<readonly OHLCVBar[]>;
+    subscribeToBar(symbol: string, timeframe: Timeframe, onBar: (bar: OHLCVBar) => void): Unsubscribe;
+    subscribeToTrades(symbol: string, onTrade: (trade: Trade) => void): Unsubscribe;
+    subscribeToOrderbook(symbol: string, onUpdate: (snapshot: OrderbookSnapshot) => void): Unsubscribe;
+    searchSymbols(query: string): Promise<readonly SymbolInfo[]>;
+    getLastBackfillCoverage?(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+    getLastRangeCoverage?(symbol?: string, timeframe?: Timeframe, chartId?: string): readonly CoverageFragment[] | null;
+}
+
+export { type BarsHotWindowLoadGateReport, type BarsHotWindowLoadGateStatus, type BarsHotWindowLoadGateThresholds, type BarsHotWindowTelemetry, type BarsPagingMeta, ContinuousFuturesStockDataAdapter, MultiSourceDataAdapter, type MultiSourceDataAdapterConfig, type SourceRoute, TIMEFRAME_MAP, type TickerUpdateEvent, type UseWatchlistRealtimeSyncOptions, type VNIBarsPageResponse, type VNIBarsParams, type VNIWSEvent, VNInvestClient, VNInvestDataAdapter, type VNInvestDataAdapterConfig, VNInvestWebSocketClient, type WhaleAlertWSEvent, buildBackwardPageRequest, normalizeBarsPagingMeta, resolveApiBase, useWatchlistRealtimeSync };