tickatlas 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,865 @@
+/**
+ * Enums & constant catalogues for the TickAtlas API.
+ *
+ * Every constant object below is exported `as const` so that, in TypeScript,
+ * the union of its values is available as a type (see the companion type
+ * aliases). All methods that accept these values also accept raw strings, so
+ * these objects exist purely for discoverability / autocomplete.
+ *
+ * Source of truth: SPEC.md §6 ("Common enums & constants").
+ */
+/**
+ * Bar timeframes accepted by the indicator / indicators / summary / ohlc /
+ * multi / history / screener endpoints. Default everywhere is `H1`.
+ */
+declare const Timeframes: {
+    readonly M1: "M1";
+    readonly M5: "M5";
+    readonly M15: "M15";
+    readonly M30: "M30";
+    readonly H1: "H1";
+    readonly H4: "H4";
+    readonly D1: "D1";
+};
+type Timeframe = (typeof Timeframes)[keyof typeof Timeframes];
+/**
+ * Timeframes accepted by the heatmap endpoint (note: different set — no
+ * intraday below H1, adds W1). Default is `H4`.
+ */
+declare const HeatmapTimeframes: {
+    readonly H1: "H1";
+    readonly H4: "H4";
+    readonly D1: "D1";
+    readonly W1: "W1";
+};
+type HeatmapTimeframe = (typeof HeatmapTimeframes)[keyof typeof HeatmapTimeframes];
+/** Symbol categories. */
+declare const SymbolCategories: {
+    readonly forex: "forex";
+    readonly metals: "metals";
+    readonly commodities: "commodities";
+    readonly indices: "indices";
+    readonly crypto: "crypto";
+    readonly stocks: "stocks";
+};
+type SymbolCategory = (typeof SymbolCategories)[keyof typeof SymbolCategories];
+/** Spread statistic periods. Default is `24h`. */
+declare const SpreadPeriods: {
+    readonly "1h": "1h";
+    readonly "24h": "24h";
+    readonly "7d": "7d";
+    readonly "30d": "30d";
+};
+type SpreadPeriod = (typeof SpreadPeriods)[keyof typeof SpreadPeriods];
+/** Economic-calendar impact levels. */
+declare const CalendarImpacts: {
+    readonly high: "high";
+    readonly medium: "medium";
+    readonly low: "low";
+};
+type CalendarImpact = (typeof CalendarImpacts)[keyof typeof CalendarImpacts];
+/** Summary market-bias values. */
+declare const Bias: {
+    readonly bullish: "bullish";
+    readonly bearish: "bearish";
+    readonly neutral: "neutral";
+};
+type BiasValue = (typeof Bias)[keyof typeof Bias];
+/** Summary bias strength. */
+declare const BiasStrengths: {
+    readonly normal: "normal";
+    readonly strong: "strong";
+};
+type BiasStrength = (typeof BiasStrengths)[keyof typeof BiasStrengths];
+/** Heatmap mode. Default is `strength`. */
+declare const HeatmapTypes: {
+    readonly strength: "strength";
+    readonly correlation: "correlation";
+};
+type HeatmapType = (typeof HeatmapTypes)[keyof typeof HeatmapTypes];
+/** Indicator catalogue categories (used by `getIndicators` filtering). */
+declare const IndicatorCategories: {
+    readonly trend: "trend";
+    readonly oscillator: "oscillator";
+    readonly volatility: "volatility";
+    readonly volume: "volume";
+};
+type IndicatorCategory = (typeof IndicatorCategories)[keyof typeof IndicatorCategories];
+/** Account plans. */
+declare const Plans: {
+    readonly free: "free";
+    readonly trial: "trial";
+    readonly starter: "starter";
+    readonly pro: "pro";
+    readonly enterprise: "enterprise";
+    readonly payg: "payg";
+};
+type Plan = (typeof Plans)[keyof typeof Plans];
+/** Screener sort direction. Default is `asc`. */
+declare const SortDirections: {
+    readonly asc: "asc";
+    readonly desc: "desc";
+};
+type SortDirection = (typeof SortDirections)[keyof typeof SortDirections];
+/**
+ * The full, case-sensitive catalogue of 42 indicator identifiers accepted by
+ * the API (source of truth: server `INDICATOR_COLUMN_MAP`, SPEC.md §6).
+ *
+ * Use these verbatim — the docs occasionally use wrong names that 404 (e.g.
+ * `Parabolic_SAR`, `Tick_Volume`, `RSI_9`, `EMA_200`). The correct names are
+ * `SAR`, `Volumes`; `EMA` stops at `EMA_50`; only three Ichimoku keys exist.
+ */
+declare const Indicators: {
+    readonly SMA_10: "SMA_10";
+    readonly SMA_20: "SMA_20";
+    readonly SMA_50: "SMA_50";
+    readonly SMA_100: "SMA_100";
+    readonly SMA_200: "SMA_200";
+    readonly EMA_10: "EMA_10";
+    readonly EMA_20: "EMA_20";
+    readonly EMA_50: "EMA_50";
+    readonly MACD_main: "MACD_main";
+    readonly MACD_signal: "MACD_signal";
+    readonly MACD_hist: "MACD_hist";
+    readonly ADX: "ADX";
+    readonly ADX_plusDI: "ADX_plusDI";
+    readonly ADX_minusDI: "ADX_minusDI";
+    readonly Ichimoku_tenkan: "Ichimoku_tenkan";
+    readonly Ichimoku_kijun: "Ichimoku_kijun";
+    readonly Ichimoku_senkou_a: "Ichimoku_senkou_a";
+    readonly Alligator_jaw: "Alligator_jaw";
+    readonly Alligator_teeth: "Alligator_teeth";
+    readonly Alligator_lips: "Alligator_lips";
+    readonly SAR: "SAR";
+    readonly TEMA_20: "TEMA_20";
+    readonly DEMA_20: "DEMA_20";
+    readonly RSI_14: "RSI_14";
+    readonly Stochastic_K: "Stochastic_K";
+    readonly Stochastic_D: "Stochastic_D";
+    readonly CCI_14: "CCI_14";
+    readonly CCI_20: "CCI_20";
+    readonly WilliamsR_14: "WilliamsR_14";
+    readonly Momentum_14: "Momentum_14";
+    readonly DeMarker_14: "DeMarker_14";
+    readonly BB_upper: "BB_upper";
+    readonly BB_middle: "BB_middle";
+    readonly BB_lower: "BB_lower";
+    readonly BB_width: "BB_width";
+    readonly ATR_14: "ATR_14";
+    readonly ATR_7: "ATR_7";
+    readonly StdDev_20: "StdDev_20";
+    readonly OBV: "OBV";
+    readonly MFI_14: "MFI_14";
+    readonly AD: "AD";
+    readonly Volumes: "Volumes";
+};
+type Indicator = (typeof Indicators)[keyof typeof Indicators];
+/** Indicators grouped by their catalogue category (4 + total 42). */
+declare const IndicatorsByCategory: {
+    readonly trend: readonly ["SMA_10", "SMA_20", "SMA_50", "SMA_100", "SMA_200", "EMA_10", "EMA_20", "EMA_50", "MACD_main", "MACD_signal", "MACD_hist", "ADX", "ADX_plusDI", "ADX_minusDI", "Ichimoku_tenkan", "Ichimoku_kijun", "Ichimoku_senkou_a", "Alligator_jaw", "Alligator_teeth", "Alligator_lips", "SAR", "TEMA_20", "DEMA_20"];
+    readonly oscillator: readonly ["RSI_14", "Stochastic_K", "Stochastic_D", "CCI_14", "CCI_20", "WilliamsR_14", "Momentum_14", "DeMarker_14"];
+    readonly volatility: readonly ["BB_upper", "BB_middle", "BB_lower", "BB_width", "ATR_14", "ATR_7", "StdDev_20"];
+    readonly volume: readonly ["OBV", "MFI_14", "AD", "Volumes"];
+};
+/** Flat, ordered list of all 42 indicator identifiers. */
+declare const ALL_INDICATORS: readonly Indicator[];
+
+/**
+ * Request-parameter objects and response models for every TickAtlas endpoint.
+ *
+ * Response models mirror the `data` payloads from SPEC.md §7 (the SDK unwraps
+ * the `{ success, data }` envelope and returns the typed `data`). All models
+ * tolerate unknown extra keys via index signatures where the API is explicitly
+ * forward-compatible; nullable fields use `| null` per the spec.
+ */
+
+/** A value that is accepted both as a typed enum member and as a raw string. */
+type Loose$1<T extends string> = T | (string & {});
+/** Standard offset/limit pagination block. */
+interface Pagination {
+    offset: number;
+    limit: number;
+    total: number;
+    has_more: boolean;
+}
+interface GetSymbolsOptions {
+    category?: Loose$1<SymbolCategory>;
+    search?: string;
+    offset?: number;
+    limit?: number;
+}
+interface SymbolListItem {
+    symbol: string;
+    name: string | null;
+    category: string;
+    base_currency: string | null;
+    quote_currency: string | null;
+    digits: number;
+    tradable: boolean;
+}
+interface SymbolsData {
+    symbols: SymbolListItem[];
+    total: number;
+    pagination: Pagination;
+}
+interface TradingHours {
+    sunday: string;
+    monday: string;
+    tuesday: string;
+    wednesday: string;
+    thursday: string;
+    friday: string;
+    saturday: string;
+    [day: string]: string;
+}
+interface SymbolDetail {
+    symbol: string;
+    name: string | null;
+    category: string;
+    description: string | null;
+    base_currency: string | null;
+    quote_currency: string | null;
+    digits: number;
+    point: number;
+    contract_size: number;
+    min_volume: number;
+    max_volume: number;
+    volume_step: number;
+    swap_long: number | null;
+    swap_short: number | null;
+    margin_currency: string | null;
+    trading_hours: TradingHours;
+}
+interface GetQuoteOptions {
+    /** Include per-broker `sources[]`. */
+    includeSources?: boolean;
+    /** Force a specific broker source (debug). */
+    source?: string;
+}
+interface QuoteSource {
+    broker: string;
+    bid: number;
+    ask: number;
+    spread: number;
+    updated: string;
+}
+interface QuoteData {
+    symbol: string;
+    bid: number | null;
+    ask: number | null;
+    spread: number;
+    spread_pips: number | null;
+    timestamp: string;
+    source?: string;
+    best_bid?: number | null;
+    best_ask?: number | null;
+    best_spread?: number | null;
+    source_count?: number;
+    sources?: QuoteSource[];
+}
+/** Fields selectable on the batch-quotes endpoint. */
+type QuoteField = "bid" | "ask" | "spread" | "spread_pips" | "timestamp";
+interface BulkQuoteItem {
+    symbol: string;
+    bid?: number | null;
+    ask?: number | null;
+    spread?: number | null;
+    spread_pips?: number | null;
+    timestamp?: string;
+}
+interface BulkQuotesData {
+    quotes: BulkQuoteItem[];
+    count: number;
+    not_found: string[] | null;
+    timestamp: string;
+}
+interface GetOhlcOptions {
+    timeframe?: Loose$1<Timeframe>;
+    /** ISO 8601 start; defaults server-side to retention start. */
+    from?: string;
+    /** ISO 8601 end; defaults to now. */
+    to?: string;
+    /** 1..1000, default 100. */
+    limit?: number;
+}
+interface Candle {
+    time: string;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+interface OHLCData {
+    symbol: string;
+    timeframe: string;
+    candles: Candle[];
+    count: number;
+    retention: string | null;
+}
+interface Tick {
+    time: string;
+    bid: number;
+    ask: number;
+    flags: number;
+}
+interface TicksData {
+    symbol: string;
+    ticks: Tick[];
+    count: number;
+}
+interface GetIndicatorOptions {
+    timeframe?: Loose$1<Timeframe>;
+    /** Force a broker source. */
+    source?: string;
+}
+interface IndicatorValue {
+    symbol: string;
+    timeframe: string;
+    indicator: string;
+    value: number | null;
+    bid: number | null;
+    ask: number | null;
+    updated_at: number;
+    server_time: string | null;
+}
+interface GetIndicatorsOptions {
+    timeframe?: Loose$1<Timeframe>;
+    category?: Loose$1<IndicatorCategory>;
+}
+interface OHLCV {
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+interface IndicatorsData {
+    symbol: string;
+    timeframe: string;
+    ohlcv: OHLCV | null;
+    bid: number | null;
+    ask: number | null;
+    indicators: Record<string, number | null>;
+    count: number;
+    updated_at: number;
+}
+interface IndicatorCatalogue {
+    indicators: Record<string, Record<string, string>>;
+    timeframes: string[];
+    categories: string[];
+}
+interface GetIndicatorHistoryOptions {
+    timeframe?: Loose$1<Timeframe>;
+    /** ISO 8601 start; defaults to `to − max_window`. */
+    from?: string;
+    /** ISO 8601 end; defaults to now. */
+    to?: string;
+    /** 1..5000, default 500 (also capped per-timeframe). */
+    limit?: number;
+}
+interface IndicatorHistoryPoint {
+    time: string;
+    value: number | null;
+}
+interface IndicatorHistoryData {
+    symbol: string;
+    indicator: string;
+    timeframe: string;
+    from: string | null;
+    to: string | null;
+    count: number;
+    max_window_hours: number | null;
+    series: IndicatorHistoryPoint[];
+}
+interface GetMultiOptions {
+    timeframe?: Loose$1<Timeframe>;
+    /** ISO 8601 start; its presence switches the endpoint to historical mode. */
+    from?: string;
+    /** ISO 8601 end (historical mode). */
+    to?: string;
+}
+/** Real-time response shape (no `from`/`to` supplied). */
+interface MultiRealtimeData {
+    timeframe: string;
+    data: Record<string, Record<string, number | null>>;
+    not_found: string[] | null;
+    updated_at: number;
+    mode?: undefined;
+}
+/** Historical response shape (returned when `from` is supplied). */
+interface MultiHistoricalData {
+    timeframe: string;
+    mode: "historical";
+    from: string;
+    to: string;
+    data: Record<string, Array<{
+        time: string;
+    } & Record<string, number | null | string>>>;
+    not_found: string[] | null;
+}
+type MultiData = MultiRealtimeData | MultiHistoricalData;
+interface ScreenOptions {
+    /** Not validated server-side; still sent through. */
+    timeframe?: Loose$1<Timeframe>;
+    /** Inclusive lower bound. Serialised to `min_val`. */
+    minVal?: number;
+    /** Inclusive upper bound. Serialised to `max_val`. */
+    maxVal?: number;
+    /** `asc` (default) or `desc`. */
+    sort?: Loose$1<SortDirection>;
+    /** `≥ 0`, default 0. */
+    offset?: number;
+    /** 1..200, default 50. */
+    limit?: number;
+}
+interface ScreenerResult {
+    symbol: string;
+    value: number | null;
+    bid: number | null;
+}
+interface ScreenerData {
+    indicator: string;
+    timeframe: string;
+    filter: {
+        min: number | null;
+        max: number | null;
+    };
+    results: ScreenerResult[];
+    total_matches: number;
+    pagination: Pagination;
+    updated_at: number;
+}
+interface SummarySignals {
+    trend: string;
+    momentum: string;
+    volatility: string;
+    volume: string;
+    [key: string]: string;
+}
+interface SummaryKeyLevels {
+    resistance: number[];
+    support: number[];
+}
+interface SummaryKeyValues {
+    bid: number | null;
+    ask: number | null;
+    rsi_14: number | null;
+    macd_hist: number | null;
+    adx: number | null;
+    atr_14: number | null;
+    sma_20: number | null;
+    sma_50: number | null;
+    sma_200: number | null;
+    bb_upper: number | null;
+    bb_lower: number | null;
+    stochastic_k: number | null;
+    mfi_14: number | null;
+    [key: string]: number | null;
+}
+interface SummaryData {
+    symbol: string;
+    timeframe: string;
+    bias: BiasValue;
+    bias_strength: BiasStrength;
+    confidence: number;
+    trend_score: number;
+    momentum_score: number;
+    volatility_score: number;
+    signals: SummarySignals;
+    key_levels: SummaryKeyLevels;
+    bullish_signals: string[];
+    bearish_signals: string[];
+    neutral_signals: string[];
+    volatility_info: string[];
+    volume_info: string[];
+    summary: string;
+    recommendations: string[];
+    key_values: SummaryKeyValues;
+    updated_at: number;
+}
+interface SpreadCurrent {
+    spread_pips: number;
+    spread_points: number;
+}
+interface SpreadStatistics {
+    period: string;
+    avg_spread: number;
+    min_spread: number;
+    max_spread: number;
+    std_deviation: number;
+}
+interface SpreadBySession {
+    asian: number | null;
+    london: number | null;
+    new_york: number | null;
+}
+interface SpreadData {
+    symbol: string;
+    current: SpreadCurrent;
+    statistics: SpreadStatistics;
+    by_session: SpreadBySession;
+}
+interface SpreadCompareItem {
+    symbol: string;
+    current_pips: number | null;
+    avg_pips: number | null;
+    min_pips: number | null;
+    max_pips: number | null;
+    has_live_data: boolean;
+}
+interface SpreadCompareData {
+    period: string;
+    symbols: SpreadCompareItem[];
+    count: number;
+}
+interface SessionState {
+    status: "open" | "closed";
+    closes_in?: string;
+    opens_in?: string;
+    weekend?: boolean;
+    [key: string]: unknown;
+}
+interface SessionsData {
+    current_time: string;
+    active_sessions: string[];
+    sessions: {
+        sydney: SessionState;
+        tokyo: SessionState;
+        london: SessionState;
+        new_york: SessionState;
+        [name: string]: SessionState;
+    };
+    overlaps: string[];
+    next_major_event: {
+        event: string;
+        in: string;
+    } | null;
+}
+interface GetHeatmapOptions {
+    type?: Loose$1<HeatmapType>;
+    timeframe?: Loose$1<HeatmapTimeframe>;
+    /** `true` forces correlation mode (alternative to `type: "correlation"`). */
+    correlations?: boolean;
+}
+interface CurrencyStrength {
+    strength: number;
+    trend: BiasValue;
+    change: number;
+    pairs_analyzed: number;
+}
+interface HeatmapStrengthData {
+    type: "strength";
+    timeframe: string;
+    currencies: Record<string, CurrencyStrength>;
+    strongest: string | null;
+    weakest: string | null;
+    range: number;
+    timestamp: string;
+}
+interface HeatmapCorrelationData {
+    type: "correlation";
+    timeframe: string;
+    correlation_matrix: Record<string, Record<string, number>>;
+    available: boolean;
+    message?: string;
+    timestamp: string;
+}
+type HeatmapData = HeatmapStrengthData | HeatmapCorrelationData;
+interface GetCalendarOptions {
+    /** Date/ISO; default today 00:00 UTC. */
+    from?: string;
+    /** Date/ISO; default from+7d; range ≤ 30 days. */
+    to?: string;
+    /** Comma-separated list, or string[] — e.g. ["USD","EUR"]. */
+    currencies?: string | string[];
+    /** Alias of `currencies`. */
+    country?: string | string[];
+    impact?: Loose$1<CalendarImpact>;
+    /** Title search, ≤100 chars. */
+    q?: string;
+    /** 1..168; overrides from/to. */
+    nextHours?: number;
+    offset?: number;
+    limit?: number;
+}
+interface CalendarEvent {
+    id: string;
+    /** ISO, naive-UTC, no suffix — treat as UTC. */
+    datetime: string;
+    currency: string;
+    event: string;
+    impact: string;
+    forecast: string | null;
+    previous: string | null;
+    actual: string | null;
+}
+interface CalendarData {
+    events: CalendarEvent[];
+    count: number;
+    pagination: Pagination;
+    range: {
+        from: string;
+        to: string;
+    };
+}
+interface AccountData {
+    name: string;
+    plan: Plan | string;
+    prepaid_credits: number;
+    /** `null` means unlimited. */
+    daily_quota: number | null;
+    daily_used: number;
+}
+interface LayoutData {
+    layout: unknown[] | null;
+}
+interface SaveLayoutData {
+    saved: true;
+}
+interface HealthComponent {
+    status?: string;
+    [key: string]: unknown;
+}
+interface HealthData {
+    status: string;
+    /** Per-dependency status, e.g. `{ redis: { status: "ok" }, postgres: {...} }`. */
+    components: Record<string, HealthComponent>;
+    [key: string]: unknown;
+}
+interface RateLimitInfo {
+    limit: number | null;
+    remaining: number | null;
+    reset: number | null;
+    requestId: string | null;
+}
+
+type Loose<T extends string> = T | (string & {});
+/** Options accepted by the {@link TickAtlas} constructor. */
+interface TickAtlasOptions {
+    /**
+     * API key. If omitted, falls back to `process.env.TICKATLAS_API_KEY`
+     * (Node only), then throws {@link TickAtlasConfigError}.
+     */
+    apiKey?: string;
+    /**
+     * Base URL. Precedence: this option → `TICKATLAS_BASE_URL` env →
+     * `https://tickatlas.com/v1`.
+     */
+    baseURL?: string;
+    /** Per-request timeout in ms. Default 30000. */
+    timeout?: number;
+    /** Maximum retry attempts for 429/5xx/network. Default 3. */
+    maxRetries?: number;
+    /** Exponential-backoff base in ms. Default 500. */
+    backoffBase?: number;
+    /** Backoff cap in ms. Default 30000. */
+    backoffCap?: number;
+    /** Inject a custom fetch implementation (defaults to global `fetch`). */
+    fetch?: typeof fetch;
+    /** Inject a deterministic sleep (testing). */
+    sleep?: (ms: number) => Promise<void>;
+    /** Inject deterministic jitter in [0,1) (testing). */
+    jitter?: () => number;
+}
+declare class TickAtlas {
+    /** SDK version (e.g. for diagnostics). */
+    static readonly version = "0.1.0";
+    private readonly config;
+    constructor(options?: TickAtlasOptions);
+    /** 7.1 `GET /symbols` — list symbols (paginated). */
+    getSymbols(opts?: GetSymbolsOptions): Promise<SymbolsData>;
+    /** 7.2 `GET /symbols/{symbol}` — symbol contract spec. */
+    getSymbol(symbol: string): Promise<SymbolDetail>;
+    /** 7.3 `GET /quote` — single real-time quote. */
+    getQuote(symbol: string, opts?: GetQuoteOptions): Promise<QuoteData>;
+    /**
+     * 7.4 `POST /quotes` — batch quotes (1..100 symbols).
+     * `fields` ⊆ ["bid","ask","spread","spread_pips","timestamp"] (default all).
+     */
+    getQuotes(symbols: string[], fields?: QuoteField[]): Promise<BulkQuotesData>;
+    /** 7.5 `GET /ohlc` — OHLC candles. */
+    getOhlc(symbol: string, opts?: GetOhlcOptions): Promise<OHLCData>;
+    /**
+     * 7.6 `GET /ticks` — tick data (plan: pro/enterprise).
+     * `from`/`to` are required ISO 8601; range must be ≤ 1 hour.
+     */
+    getTicks(symbol: string, from: string, to: string): Promise<TicksData>;
+    /** 7.7 `GET /indicator` — single indicator value. */
+    getIndicator(symbol: string, indicator: Loose<Indicator>, opts?: GetIndicatorOptions): Promise<IndicatorValue>;
+    /** 7.8 `GET /indicators` — all indicators for a symbol. */
+    getIndicators(symbol: string, opts?: GetIndicatorsOptions): Promise<IndicatorsData>;
+    /** 7.9 `GET /indicators/list` — indicator catalogue. */
+    listIndicators(): Promise<IndicatorCatalogue>;
+    /**
+     * 7.10 `GET /indicator/history` — indicator series (plan: starter+).
+     */
+    getIndicatorHistory(symbol: string, indicator: Loose<Indicator>, opts?: GetIndicatorHistoryOptions): Promise<IndicatorHistoryData>;
+    /**
+     * 7.11 `GET /multi` — batch indicators across symbols. Supplying `from`
+     * switches the server into historical mode (plan: starter+).
+     */
+    getMulti(symbols: string[], indicators: Array<Loose<Indicator>>, opts?: GetMultiOptions): Promise<MultiData>;
+    /**
+     * 7.12 `GET /screener` — scan symbols by indicator.
+     * Note: `minVal`/`maxVal` serialise to `min_val`/`max_val` (the docs' `min`/
+     * `max` are silently ignored by the API — see SPEC §12 F2).
+     */
+    screen(indicator: Loose<Indicator>, opts?: ScreenOptions): Promise<ScreenerData>;
+    /** 7.13 `GET /summary` — market-bias summary. */
+    getSummary(symbol: string, timeframe?: Loose<Timeframe>): Promise<SummaryData>;
+    /** 7.14 `GET /spread` — spread statistics. */
+    getSpread(symbol: string, period?: Loose<SpreadPeriod>): Promise<SpreadData>;
+    /** 7.15 `GET /spread/compare` — compare spread across symbols (≤20). */
+    compareSpread(symbols: string[], period?: Loose<SpreadPeriod>): Promise<SpreadCompareData>;
+    /** 7.16 `GET /sessions` — market session clock. */
+    getSessions(): Promise<SessionsData>;
+    /** 7.17 `GET /heatmap` — currency strength / correlation. */
+    getHeatmap(opts?: GetHeatmapOptions): Promise<HeatmapData>;
+    /** 7.18 `GET /calendar` — economic calendar. */
+    getCalendar(opts?: GetCalendarOptions): Promise<CalendarData>;
+    /** 7.19 `GET /monitor/account` — account identity & quota. */
+    getAccount(): Promise<AccountData>;
+    /** 7.20 `GET /monitor/layout` — saved dashboard layout. */
+    getLayout(): Promise<LayoutData>;
+    /**
+     * 7.21 `PUT /monitor/layout` — save dashboard layout (≤60 widgets).
+     *
+     * ADVANCED / WRITE: this is the only mutating endpoint in the SDK. It
+     * overwrites the user's saved dashboard layout for this API key. Use with care.
+     */
+    saveLayout(layout: unknown[]): Promise<SaveLayoutData>;
+    /** `GET /health` — service health probe (no API key required server-side). */
+    health(): Promise<HealthData>;
+}
+
+/**
+ * Low-level HTTP transport for the TickAtlas SDK: a thin wrapper over the
+ * global `fetch` that handles auth headers, query serialisation, timeouts
+ * (via `AbortController`), envelope unwrapping, error mapping, and the retry
+ * policy from SPEC.md §5.
+ *
+ * Zero runtime dependencies: relies on the platform `fetch`/`AbortController`
+ * available in Node 18+ and modern browsers.
+ */
+
+/** SDK version — kept in sync with package.json. */
+declare const SDK_VERSION = "0.1.0";
+
+/**
+ * Typed exception hierarchy for the TickAtlas SDK.
+ *
+ * Mirrors SPEC.md §4 exactly:
+ *
+ *   TickAtlasError                  (base for everything)
+ *   ├── TickAtlasAPIError           (server returned a structured error)
+ *   │   ├── AuthenticationError     HTTP 401
+ *   │   ├── PermissionDeniedError   HTTP 403
+ *   │   ├── NotFoundError           HTTP 404
+ *   │   ├── ValidationError         HTTP 400 & 422
+ *   │   ├── RateLimitError          HTTP 429 (carries retryAfter)
+ *   │   └── ServerError             HTTP 5xx
+ *   └── TickAtlasNetworkError       no HTTP response (connection/timeout/DNS)
+ */
+/** Shape of the normalised `error` object returned by the API envelope. */
+interface ApiErrorBody {
+    code: string;
+    message?: string;
+    /** Present for `VALIDATION_ERROR` (HTTP 422). */
+    details?: unknown;
+    /** Forward-compatible: any additional context keys the API may attach. */
+    [key: string]: unknown;
+}
+/** Base class for every error thrown by the SDK. */
+declare class TickAtlasError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Options used to construct a {@link TickAtlasAPIError}. */
+interface ApiErrorOptions {
+    statusCode: number;
+    code: string;
+    message: string;
+    details?: unknown;
+    requestId?: string | null;
+    /** The full raw `error` object from the response envelope. */
+    raw?: ApiErrorBody | null;
+}
+/**
+ * Raised when the server returned a structured error envelope
+ * (`{ success: false, error: { code, message, ... } }`).
+ */
+declare class TickAtlasAPIError extends TickAtlasError {
+    /** HTTP status code of the response. */
+    readonly statusCode: number;
+    /** Stable, machine-branchable `error.code` string. */
+    readonly code: string;
+    /** Validation detail payload (present on `VALIDATION_ERROR`). */
+    readonly details?: unknown;
+    /** `X-Request-ID` correlation id, if present. */
+    readonly requestId?: string | null;
+    /** The full raw `error` object (read context fields off this). */
+    readonly raw?: ApiErrorBody | null;
+    constructor(opts: ApiErrorOptions);
+}
+/** HTTP 401 — `MISSING_API_KEY`, `INVALID_API_KEY`. */
+declare class AuthenticationError extends TickAtlasAPIError {
+    constructor(opts: ApiErrorOptions);
+}
+/**
+ * HTTP 403 — `API_KEY_DISABLED`, `API_KEY_EXPIRED`, `IP_NOT_ALLOWED`,
+ * `ACCOUNT_*`, `PERMISSION_DENIED`, `PLAN_UPGRADE_REQUIRED`.
+ */
+declare class PermissionDeniedError extends TickAtlasAPIError {
+    constructor(opts: ApiErrorOptions);
+}
+/** HTTP 404 — `SYMBOL_NOT_FOUND`, `DATA_NOT_FOUND`, `INDICATOR_NOT_FOUND`. */
+declare class NotFoundError extends TickAtlasAPIError {
+    constructor(opts: ApiErrorOptions);
+}
+/**
+ * HTTP 400 & 422 — all `INVALID_*`, `RANGE_TOO_LARGE`, `OUTSIDE_RETENTION`,
+ * `TOO_MANY_SYMBOLS`, `NO_SYMBOLS`, `VALIDATION_ERROR`, `HTTP_400`, …
+ */
+declare class ValidationError extends TickAtlasAPIError {
+    constructor(opts: ApiErrorOptions);
+}
+/**
+ * HTTP 429 — `RATE_LIMIT_EXCEEDED`, `QUOTA_EXCEEDED`, `RATE_LIMITED`.
+ * Carries {@link retryAfter} (seconds), derived from the `Retry-After`
+ * header (fallback `X-RateLimit-Reset`, then `reset_in_seconds`).
+ */
+declare class RateLimitError extends TickAtlasAPIError {
+    /** Seconds to wait before retrying, if the server advertised one. */
+    readonly retryAfter?: number | null;
+    constructor(opts: ApiErrorOptions & {
+        retryAfter?: number | null;
+    });
+}
+/** HTTP 5xx — `INTERNAL_ERROR`, `SERVICE_UNAVAILABLE`. */
+declare class ServerError extends TickAtlasAPIError {
+    constructor(opts: ApiErrorOptions);
+}
+/**
+ * Raised when no HTTP response was received at all — connection refused, DNS
+ * failure, TLS error, or a request that exceeded the configured `timeout`
+ * (aborted via `AbortController`).
+ */
+declare class TickAtlasNetworkError extends TickAtlasError {
+    /** True when the failure was caused by the request timing out. */
+    readonly isTimeout: boolean;
+    constructor(message: string, options?: {
+        cause?: unknown;
+        isTimeout?: boolean;
+    });
+}
+/**
+ * Raised before any request is made when the SDK is misconfigured (e.g. no API
+ * key could be resolved). This is a usage error, not an API error.
+ */
+declare class TickAtlasConfigError extends TickAtlasError {
+    constructor(message: string);
+}
+
+export { ALL_INDICATORS, type AccountData, type ApiErrorBody, type ApiErrorOptions, AuthenticationError, Bias, type BiasStrength, BiasStrengths, type BiasValue, type BulkQuoteItem, type BulkQuotesData, type CalendarData, type CalendarEvent, type CalendarImpact, CalendarImpacts, type Candle, type CurrencyStrength, type GetCalendarOptions, type GetHeatmapOptions, type GetIndicatorHistoryOptions, type GetIndicatorOptions, type GetIndicatorsOptions, type GetMultiOptions, type GetOhlcOptions, type GetQuoteOptions, type GetSymbolsOptions, type HealthData, type HeatmapCorrelationData, type HeatmapData, type HeatmapStrengthData, type HeatmapTimeframe, HeatmapTimeframes, type HeatmapType, HeatmapTypes, type Indicator, type IndicatorCatalogue, IndicatorCategories, type IndicatorCategory, type IndicatorHistoryData, type IndicatorHistoryPoint, type IndicatorValue, Indicators, IndicatorsByCategory, type IndicatorsData, type LayoutData, type MultiData, type MultiHistoricalData, type MultiRealtimeData, NotFoundError, type OHLCData, type OHLCV, type Pagination, PermissionDeniedError, type Plan, Plans, type QuoteData, type QuoteField, type QuoteSource, RateLimitError, type RateLimitInfo, SDK_VERSION, type SaveLayoutData, type ScreenOptions, type ScreenerData, type ScreenerResult, ServerError, type SessionState, type SessionsData, type SortDirection, SortDirections, type SpreadBySession, type SpreadCompareData, type SpreadCompareItem, type SpreadCurrent, type SpreadData, type SpreadPeriod, SpreadPeriods, type SpreadStatistics, type SummaryData, type SummaryKeyLevels, type SummaryKeyValues, type SummarySignals, SymbolCategories, type SymbolCategory, type SymbolDetail, type SymbolListItem, type SymbolsData, type Tick, TickAtlas, TickAtlasAPIError, TickAtlasConfigError, TickAtlasError, TickAtlasNetworkError, type TickAtlasOptions, type TicksData, type Timeframe, Timeframes, type TradingHours, ValidationError };