pinets 0.9.5 → 0.9.7

package/dist/types/Context.class.d.ts

@@ -14,7 +14,31 @@ export declare class Context {
     isSecondaryContext: boolean;
     chartTimezone: string | null;
     dataVersion: number;
+    __maxLoops: number;
     NA: any;
+    /** Runtime warnings (OOB access, etc.) — non-blocking, script continues. */
+    warnings: {
+        message: string;
+        method?: string;
+        bar: number;
+    }[];
+    /** Alert events emitted by alert() and alertcondition() calls. */
+    alerts: {
+        type: string;
+        id: string;
+        message: string;
+        title?: string;
+        freq?: string;
+        bar_index: number;
+        time: number;
+    }[];
+    /** Alert mode: 'realtime' = only fire on live bars (TV behavior), 'all' = fire on every bar (backtest). */
+    _alertMode: 'realtime' | 'all';
+    /** Monotonically increasing counter, incremented each time a bar starts executing.
+     *  Used by alertcondition/AlertHelper to detect re-execution of the same bar. */
+    _execTick: number;
+    /** Emit a runtime warning. The script continues execution (returns na/no-op). */
+    warn(message: string, method?: string): void;
     lang: any;
     length: number;
     /** References to drawing helpers for streaming rollback */

package/dist/types/PineTS.class.d.ts

@@ -40,6 +40,23 @@ export declare class PineTS {
      * @param timezone IANA timezone name (e.g. 'America/New_York'), UTC offset ('UTC+5'), or 'UTC'
      */
     setTimezone(timezone: string): void;
+    private _maxLoops;
+    /**
+     * Set the maximum number of iterations allowed per loop.
+     * Mirrors TradingView's internal loop protection. If a for/while loop
+     * exceeds this limit, a runtime error is thrown.
+     * @param maxLoops Maximum iterations per loop (default: 500000)
+     */
+    setMaxLoops(maxLoops: number): void;
+    private _alertMode;
+    /**
+     * Set alert mode.
+     * - 'realtime' (default): alerts only fire on the last (realtime) bar,
+     *   matching TradingView behavior.
+     * - 'all': alerts fire on every bar, useful for backtesting alert strategies.
+     * @param mode Alert firing mode
+     */
+    setAlertMode(mode: 'realtime' | 'all'): void;
     constructor(source: IProvider | any[], tickerId?: string, timeframe?: string, limit?: number, sDate?: number, eDate?: number);
     setDebugSettings({ ln, debug }: {
         ln: boolean;
@@ -74,7 +91,7 @@ export declare class PineTS {
         live?: boolean;
         interval?: number;
     }): {
-        on: (event: 'data' | 'error', callback: Function) => void;
+        on: (event: 'data' | 'error' | 'warning' | 'alert', callback: Function) => void;
         stop: () => void;
     };
     /**

package/dist/types/errors/PineRuntimeError.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime error thrown by PineTS when a Pine Script runtime violation occurs.
+ * Mirrors TradingView behavior where operations like out-of-bounds array/matrix
+ * access or infinite loops halt the script with a runtime error.
+ *
+ * Consumers can catch this specific error type to distinguish Pine runtime
+ * errors from general JavaScript errors:
+ *
+ * ```typescript
+ * try {
+ *     const result = await pineTS.run(code);
+ * } catch (err) {
+ *     if (err instanceof PineRuntimeError) {
+ *         console.log('Pine runtime error:', err.message);
+ *         console.log('Method:', err.method); // e.g. 'array.get'
+ *     }
+ * }
+ * ```
+ */
+export declare class PineRuntimeError extends Error {
+    /**
+     * The Pine Script method that caused the error (e.g. 'array.get', 'matrix.set').
+     * May be undefined for non-method errors (e.g. loop guard).
+     */
+    method?: string;
+    constructor(message: string, method?: string);
+}

package/dist/types/index.d.ts

@@ -2,4 +2,13 @@ import PineTS from './PineTS.class';
 import { Context } from './Context.class';
 import { Provider } from './marketData/Provider.class';
 import { Indicator } from './Indicator';
-export { PineTS, Context, Provider, Indicator };
+import { PineRuntimeError } from './errors/PineRuntimeError';
+export { BaseProvider } from './marketData/BaseProvider';
+export { BinanceProvider } from './marketData/Binance/BinanceProvider.class';
+export { FMPProvider } from './marketData/FMP/FMPProvider.class';
+export { AlpacaProvider } from './marketData/Alpaca/AlpacaProvider.class';
+export type { IProvider, ISymbolInfo, BaseProviderConfig, ApiKeyProviderConfig } from './marketData/IProvider';
+export type { Kline, PeriodType } from './marketData/types';
+export { computeNextPeriodStart, localTimeToUTC, computeSessionClose, TIMEFRAME_SECONDS, TIMEFRAME_PERIOD_INFO } from './marketData/types';
+export { aggregateCandles, selectSubTimeframe, getAggregationRatio } from './marketData/aggregation';
+export { PineTS, Context, Provider, Indicator, PineRuntimeError };

package/dist/types/marketData/Alpaca/AlpacaProvider.class.d.ts

@@ -0,0 +1,115 @@
+import { ISymbolInfo, ApiKeyProviderConfig } from '@pinets/marketData/IProvider';
+import { BaseProvider } from '@pinets/marketData/BaseProvider';
+import { Kline } from '@pinets/marketData/types';
+/**
+ * Configuration for AlpacaProvider.
+ *
+ * @property apiKey    - Alpaca API Key ID
+ * @property apiSecret - Alpaca API Secret Key
+ * @property paper     - Use paper trading endpoint for asset info (default: true)
+ * @property feed      - Market data feed: 'sip' (paid, full market) or 'iex' (free tier). Default: 'sip'
+ * @property dataUrl   - Override the market data base URL
+ * @property tradingUrl - Override the trading/asset API base URL
+ */
+export interface AlpacaProviderConfig extends ApiKeyProviderConfig {
+    apiSecret: string;
+    paper?: boolean;
+    feed?: 'sip' | 'iex';
+    dataUrl?: string;
+    tradingUrl?: string;
+}
+/**
+ * Alpaca Markets data provider.
+ *
+ * Supports US stocks and crypto via Alpaca's Market Data API v2.
+ * All timeframes (1Min through 1Month) are natively supported.
+ *
+ * ## Usage
+ *
+ * ### Direct instantiation:
+ * ```typescript
+ * const alpaca = new AlpacaProvider({
+ *     apiKey: 'PK...',
+ *     apiSecret: '...',
+ * });
+ * const pineTS = new PineTS(alpaca, 'AAPL', 'D', null, sDate, eDate);
+ * ```
+ *
+ * ### Via Provider registry:
+ * ```typescript
+ * Provider.Alpaca.configure({ apiKey: 'PK...', apiSecret: '...' });
+ * const pineTS = new PineTS(Provider.Alpaca, 'AAPL', 'D', null, sDate, eDate);
+ * ```
+ *
+ * ## API Keys
+ * Get free API keys at https://alpaca.markets/
+ * Free tier provides IEX data; paid plan adds SIP (full market) data.
+ *
+ * ## Symbol Format
+ * - Stocks: `AAPL`, `MSFT`, `SPY`
+ * - Crypto: `BTC/USD`, `ETH/USD` (slash notation)
+ */
+export declare class AlpacaProvider extends BaseProvider<AlpacaProviderConfig> {
+    private _apiKey;
+    private _apiSecret;
+    private _dataUrl;
+    private _tradingUrl;
+    private _feed;
+    private _assetCache;
+    /** Calendar cache: date string "YYYY-MM-DD" → { open, close } times. */
+    private _calendarCache;
+    constructor(config?: AlpacaProviderConfig);
+    configure(config: AlpacaProviderConfig): void;
+    private _headers;
+    protected getSupportedTimeframes(): Set<string>;
+    protected _getMarketDataNative(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<Kline[]>;
+    /**
+     * Fetch all bars with automatic pagination.
+     */
+    private _fetchAllBars;
+    /**
+     * Build the bars URL for stocks or crypto.
+     */
+    private _buildBarsUrl;
+    getSymbolInfo(tickerId: string): Promise<ISymbolInfo>;
+    /**
+     * Convert bars for crypto (24/7 — no session boundaries).
+     * closeTime = next bar's openTime, or openTime + period for last bar.
+     */
+    private _convertBarsCrypto;
+    /**
+     * Convert bars for stocks using the Alpaca trading calendar.
+     * closeTime = exact session close from the calendar (handles early closes, DST).
+     */
+    private _convertBarsStock;
+    /** Build a Kline from an AlpacaBar + computed times. */
+    private _toKline;
+    /**
+     * Find the last trading day of the week containing `barDate` and return
+     * its session close time in UTC ms.
+     */
+    private _weeklyCloseFromCalendar;
+    /**
+     * Find the last trading day of the month containing `barDate` and return
+     * its session close time in UTC ms.
+     */
+    private _monthlyCloseFromCalendar;
+    /**
+     * Ensure the calendar cache covers the given date range.
+     * Fetches from Alpaca's `GET /v2/calendar` endpoint, which returns
+     * per-day trading hours including early closes (data from 1970-2029).
+     */
+    private _ensureCalendar;
+    private _fetchAsset;
+    /**
+     * Parse an Alpaca timeframe string (e.g., '1Min', '4Hour', '1Month')
+     * into a PeriodType and multiplier for calendar-aware date math.
+     */
+    private _parseAlpacaTimeframe;
+    /** Resolve PineTS timeframe to Alpaca timeframe string. */
+    private _resolveTimeframe;
+    /** Heuristic: crypto tickers contain '/'. */
+    private _isCrypto;
+    /** Add N days to a "YYYY-MM-DD" date string. */
+    private _addDaysToDate;
+}

package/dist/types/marketData/BaseProvider.d.ts

@@ -0,0 +1,92 @@
+import { IProvider, ISymbolInfo, BaseProviderConfig } from './IProvider';
+import { Kline } from './types';
+/**
+ * Abstract base class for market data providers.
+ *
+ * Provides shared logic: closeTime normalization, fail-early API key
+ * validation, and **automatic candle aggregation** for unsupported
+ * timeframes.
+ *
+ * ## Aggregation
+ *
+ * When a provider doesn't natively support a timeframe, `getMarketData()`
+ * automatically:
+ * 1. Selects the best sub-timeframe the provider supports
+ * 2. Fetches sub-candles via `_getMarketDataNative()`
+ * 3. Aggregates them into the requested timeframe
+ *
+ * Providers declare native support via `getSupportedTimeframes()` and
+ * implement `_getMarketDataNative()` for the actual API call.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * class MyProvider extends BaseProvider<MyConfig> {
+ *     protected getSupportedTimeframes() {
+ *         return new Set(['1', '5', '15', '60', 'D']);
+ *     }
+ *     protected async _getMarketDataNative(...) { ... }
+ * }
+ * ```
+ */
+export declare abstract class BaseProvider<TConfig extends BaseProviderConfig = BaseProviderConfig> implements IProvider {
+    private _configured;
+    private _requiresApiKey;
+    private _providerName;
+    private _aggregationSubTimeframe;
+    constructor(options: {
+        requiresApiKey: boolean;
+        providerName: string;
+    });
+    /**
+     * Fail-early check — call at the top of `_getMarketDataNative()` / `getSymbolInfo()`
+     * in providers that require an API key.
+     */
+    protected ensureConfigured(): void;
+    /**
+     * Base configure — marks the provider as configured.
+     * Subclasses override to store their specific config, and must call `super.configure(config)`.
+     */
+    configure(config: TConfig): void;
+    /** Whether this provider has been configured (always true for keyless providers). */
+    get isConfigured(): boolean;
+    /**
+     * Shared closeTime normalization utility.
+     * Delegates to the standalone `normalizeCloseTime()` from `types.ts`.
+     */
+    protected normalizeCloseTime(data: Kline[]): void;
+    /**
+     * Override the sub-timeframe used for aggregation.
+     * When set, this timeframe is used instead of auto-selecting the best divisor.
+     * Set to `null` to re-enable automatic selection.
+     */
+    setAggregationSubTimeframe(subTimeframe: string | null): void;
+    /**
+     * Return the set of timeframes this provider supports natively.
+     *
+     * Override in subclasses. Default: all canonical timeframes (no aggregation).
+     * Use canonical keys: '1','3','5','15','30','45','60','120','180','240','D','W','M'
+     * and optionally second-based: '1S','5S','10S','15S','30S'.
+     */
+    protected getSupportedTimeframes(): Set<string>;
+    /**
+     * Fetch market data — delegates to native fetch or aggregates from sub-candles.
+     *
+     * 1. If the timeframe is natively supported, delegates to `_getMarketDataNative()`.
+     * 2. Otherwise, selects the best sub-timeframe, fetches sub-candles, and aggregates.
+     */
+    getMarketData(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<Kline[]>;
+    /**
+     * Fetch market data natively from the provider's API.
+     *
+     * Subclasses MUST implement this. It is called by the BaseProvider
+     * orchestrator either for the requested timeframe (if natively supported)
+     * or for a sub-candle timeframe (if aggregation is needed).
+     */
+    protected abstract _getMarketDataNative(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<Kline[]>;
+    abstract getSymbolInfo(tickerId: string): Promise<ISymbolInfo>;
+    /**
+     * Compute how many sub-candles to fetch to produce `limit` aggregated candles.
+     */
+    private _computeSubLimit;
+}

package/dist/types/marketData/Binance/BinanceProvider.class.d.ts

@@ -1,15 +1,13 @@
-import { IProvider, ISymbolInfo } from '@pinets/marketData/IProvider';
-export declare class BinanceProvider implements IProvider {
+import { ISymbolInfo } from '@pinets/marketData/IProvider';
+import { BaseProvider } from '@pinets/marketData/BaseProvider';
+import { Kline } from '@pinets/marketData/types';
+/** Config for BinanceProvider (no API key needed). */
+export interface BinanceProviderConfig {
+}
+export declare class BinanceProvider extends BaseProvider<BinanceProviderConfig> {
     private cacheManager;
     private activeApiUrl;
     constructor();
-    /**
-     * Normalize closeTime to TradingView convention: closeTime = next bar's openTime.
-     * Binance raw API returns closeTime as (nextBarOpen - 1ms). For all bars except the
-     * last, we use the next bar's actual openTime (exact). For the last bar, we add 1ms
-     * to the raw value.
-     */
-    private _normalizeCloseTime;
     /**
      * Resolves the working Binance API endpoint.
      * Tries default first, then falls back to US endpoint.
@@ -21,13 +19,13 @@ export declare class BinanceProvider implements IProvider {
      * Used internally by pagination methods that assemble chunks before normalizing.
      */
     private _fetchRawChunk;
-    getMarketDataInterval(tickerId: string, timeframe: string, sDate: number, eDate: number): Promise<any>;
+    getMarketDataInterval(tickerId: string, timeframe: string, sDate: number, eDate: number): Promise<Kline[]>;
     private getMarketDataBackwards;
-    getMarketData(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<any>;
+    protected getSupportedTimeframes(): Set<string>;
+    protected _getMarketDataNative(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<Kline[]>;
     /**
      * Determines if pagination is needed based on the parameters
      */
     private shouldPaginate;
     getSymbolInfo(tickerId: string): Promise<ISymbolInfo>;
-    configure(config: any): void;
 }

package/dist/types/marketData/FMP/FMPProvider.class.d.ts

@@ -0,0 +1,69 @@
+import { ISymbolInfo, ApiKeyProviderConfig } from '@pinets/marketData/IProvider';
+import { BaseProvider } from '@pinets/marketData/BaseProvider';
+import { Kline } from '@pinets/marketData/types';
+/** Configuration for FMPProvider — requires an API key. */
+export interface FMPProviderConfig extends ApiKeyProviderConfig {
+    /** Optional: override the base URL (e.g. for proxy or self-hosted). */
+    baseUrl?: string;
+}
+/**
+ * Financial Modeling Prep (FMP) market data provider.
+ *
+ * Supports stocks, ETFs, crypto, and forex via FMP's stable API.
+ *
+ * ## Usage
+ *
+ * ### Direct instantiation:
+ * ```typescript
+ * const fmp = new FMPProvider({ apiKey: 'your-key' });
+ * const pineTS = new PineTS(fmp, 'AAPL', 'D', null, sDate, eDate);
+ * ```
+ *
+ * ### Via Provider registry:
+ * ```typescript
+ * Provider.FMP.configure({ apiKey: 'your-key' });
+ * const pineTS = new PineTS(Provider.FMP, 'AAPL', 'D', null, sDate, eDate);
+ * ```
+ *
+ * ## API Key
+ * Get a free API key (250 req/day) at https://financialmodelingprep.com/
+ * Intraday data (1min, 5min, 15min, 30min, 1h, 4h) requires a paid plan.
+ *
+ * ## Symbol Format
+ * Use standard ticker symbols: `AAPL`, `MSFT`, `SPY`, `BTCUSD`, `EURUSD`
+ */
+export declare class FMPProvider extends BaseProvider<FMPProviderConfig> {
+    private _apiKey;
+    private _baseUrl;
+    private _profileCache;
+    constructor(config?: FMPProviderConfig);
+    configure(config: FMPProviderConfig): void;
+    protected getSupportedTimeframes(): Set<string>;
+    protected _getMarketDataNative(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<Kline[]>;
+    /**
+     * Fetch daily EOD data from FMP and convert to Kline format.
+     */
+    private _fetchDailyData;
+    /**
+     * Fetch intraday chart data from FMP and convert to Kline format.
+     * Note: Requires a paid FMP plan.
+     */
+    private _fetchIntradayData;
+    getSymbolInfo(tickerId: string): Promise<ISymbolInfo>;
+    private _fetchProfile;
+    /**
+     * Resolve session string and timezone for a ticker by fetching its profile.
+     * Falls back to NYSE defaults if profile is unavailable.
+     */
+    private _resolveSessionInfo;
+    /** Convert ms timestamp to FMP date string "YYYY-MM-DD". */
+    private _msToDateStr;
+    /** Convert FMP date string "YYYY-MM-DD" to ms timestamp (UTC midnight). */
+    private _dateStrToMs;
+    /** Convert FMP datetime string "YYYY-MM-DD HH:MM:SS" to ms timestamp. */
+    private _dateTimeStrToMs;
+    /** Heuristic: crypto tickers end with USD/USDT/BTC/ETH. */
+    private _isCrypto;
+    /** Heuristic: forex pairs are 6 chars, two 3-letter currency codes. */
+    private _isForex;
+}

package/dist/types/marketData/IProvider.d.ts

@@ -1,3 +1,11 @@
+import type { Kline } from './types';
+/** Base config — all providers extend this (may be empty for keyless providers). */
+export interface BaseProviderConfig {
+}
+/** Config for providers that require an API key (FMP, Alpaca, etc.). */
+export interface ApiKeyProviderConfig extends BaseProviderConfig {
+    apiKey: string;
+}
 export type ISymbolInfo = {
     current_contract: string;
     description: string;
@@ -44,16 +52,21 @@ export type ISymbolInfo = {
  * Market data provider interface.
  *
  * ## closeTime convention
- * Providers MUST return `closeTime` following the TradingView convention:
- * `closeTime` = the timestamp of the **start of the next bar** (not the last
- * millisecond of the current bar).  For example, a weekly bar opening on
- * Monday 2019-01-07T00:00Z should have `closeTime = 2019-01-14T00:00Z`.
+ * Providers MUST return `closeTime` as the **session close time** for the bar,
+ * mirroring TradingView's `time_close` built-in variable.
+ *
+ * - **Stocks / regulated markets**: `closeTime` = the session close time on
+ *   the bar's trading day (e.g., 16:00 ET for NYSE daily bars, 13:00 ET for
+ *   early-close days). For weekly/monthly bars, use the session close of the
+ *   last trading day in the period.
+ * - **24/7 markets (crypto)**: `closeTime` = the start of the next bar
+ *   (equivalent to `openTime + barDuration`), since there are no session gaps.
  *
- * If a provider's raw data uses a different convention (e.g., Binance returns
- * `nextBarOpen - 1ms`), the provider must normalize before returning.
+ * Use `computeSessionClose()` from `types.ts` for session-aware computation,
+ * or the Alpaca Calendar API for exact per-day close times including early closes.
  */
 export interface IProvider {
-    getMarketData(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<any>;
+    getMarketData(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<Kline[]>;
     getSymbolInfo(tickerId: string): Promise<ISymbolInfo>;
     configure(config: any): void;
 }

package/dist/types/marketData/Mock/MockProvider.class.d.ts

@@ -1,17 +1,9 @@
-import { IProvider, ISymbolInfo } from '@pinets/marketData/IProvider';
-interface Kline {
-    openTime: number;
-    open: number;
-    high: number;
-    low: number;
-    close: number;
-    volume: number;
-    closeTime: number;
-    quoteAssetVolume: number;
-    numberOfTrades: number;
-    takerBuyBaseAssetVolume: number;
-    takerBuyQuoteAssetVolume: number;
-    ignore: number | string;
+import { ISymbolInfo } from '@pinets/marketData/IProvider';
+import { BaseProvider } from '@pinets/marketData/BaseProvider';
+import { Kline } from '@pinets/marketData/types';
+/** Config for MockProvider. */
+export interface MockProviderConfig {
+    dataDirectory?: string;
 }
 /**
  * Mock Market Data Provider for Unit Tests
@@ -30,14 +22,12 @@ interface Kline {
  *
  * Example: BTCUSDC-1h-1704067200000-1763683199000.json
  */
-export declare class MockProvider implements IProvider {
+export declare class MockProvider extends BaseProvider<MockProviderConfig> {
     private dataCache;
     private exchangeInfoCache;
     private dataDirectory;
-    constructor(dataDirectory?: string);
-    configure({ dataDirectory }: {
-        dataDirectory?: string;
-    }): void;
+    constructor(dataDirectoryOrConfig?: string | MockProviderConfig);
+    configure(config: MockProviderConfig): void;
     /**
      * Generates a cache key for the data file
      */
@@ -58,8 +48,9 @@ export declare class MockProvider implements IProvider {
      * Normalizes timeframe to match file naming convention
      */
     private normalizeTimeframe;
+    protected getSupportedTimeframes(): Set<string>;
     /**
-     * Implements IProvider.getMarketData
+     * Implements _getMarketDataNative
      *
      * @param tickerId - Symbol (e.g., 'BTCUSDC')
      * @param timeframe - Timeframe (e.g., '1h', '60', 'D')
@@ -68,7 +59,7 @@ export declare class MockProvider implements IProvider {
      * @param eDate - Optional end date (timestamp in milliseconds)
      * @returns Promise<Kline[]> - Array of candle data
      */
-    getMarketData(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<Kline[]>;
+    protected _getMarketDataNative(tickerId: string, timeframe: string, limit?: number, sDate?: number, eDate?: number): Promise<Kline[]>;
     /**
      * Loads exchange info from JSON file
      */
@@ -80,13 +71,6 @@ export declare class MockProvider implements IProvider {
      * @returns Promise<ISymbolInfo> - Symbol information
      */
     getSymbolInfo(tickerId: string): Promise<ISymbolInfo>;
-    /**
-     * Normalize closeTime to TradingView convention: closeTime = next bar's openTime.
-     * Mock data files contain raw Binance data where closeTime = (nextBarOpen - 1ms).
-     * For all bars except the last, we use the next bar's actual openTime. For the
-     * last bar, we add 1ms to the raw value.
-     */
-    private _normalizeCloseTime;
     /**
      * Clears the data cache
      */
@@ -96,4 +80,3 @@ export declare class MockProvider implements IProvider {
      */
     setDataDirectory(directory: string): void;
 }
-export {};

package/dist/types/marketData/Provider.class.d.ts

@@ -1,7 +1,10 @@
 import { IProvider } from './IProvider';
+export { BinanceProvider } from './Binance/BinanceProvider.class';
+export { FMPProvider } from './FMP/FMPProvider.class';
+export { AlpacaProvider } from './Alpaca/AlpacaProvider.class';
+export { BaseProvider } from './BaseProvider';
 type TProvider = {
     [key: string]: IProvider;
 };
 export declare const Provider: TProvider;
 export declare function registerProvider(name: string, provider: IProvider): void;
-export {};

package/dist/types/marketData/aggregation.d.ts

@@ -0,0 +1,38 @@
+import { Kline } from './types';
+/**
+ * Given a target timeframe and a set of supported timeframes, select the
+ * best sub-timeframe to aggregate from.
+ *
+ * Strategy:
+ * - **W/M targets**: always use `'D'` (calendar-based grouping).
+ * - **All others**: pick the largest supported timeframe whose duration
+ *   evenly divides the target duration (using `TIMEFRAME_SECONDS`).
+ *
+ * @returns The best sub-timeframe, or `null` if none found.
+ */
+export declare function selectSubTimeframe(targetTimeframe: string, supportedTimeframes: Set<string>): string | null;
+/**
+ * Compute how many sub-candles fit into one aggregated candle.
+ *
+ * For fixed-duration aggregation: `targetSeconds / subSeconds`.
+ * For calendar-based (W/M from D): returns `Infinity` to signal variable grouping.
+ */
+export declare function getAggregationRatio(targetTimeframe: string, subTimeframe: string): number;
+/**
+ * Aggregate sub-candles into higher-timeframe candles.
+ *
+ * Three modes:
+ * 1. **Fixed-ratio** (intraday → higher intraday): groups every N consecutive
+ *    sub-candles, with session-boundary detection to avoid cross-session merging.
+ * 2. **Weekly from daily**: groups daily bars by ISO week number.
+ * 3. **Monthly from daily**: groups daily bars by calendar year+month.
+ *
+ * OHLCV merge:
+ * - `open` = first sub-candle's open
+ * - `high` = max of all highs
+ * - `low`  = min of all lows
+ * - `close` = last sub-candle's close
+ * - `volume` = sum
+ * - `closeTime` = last sub-candle's closeTime (preserves session-aware close)
+ */
+export declare function aggregateCandles(subCandles: Kline[], targetTimeframe: string, subTimeframe: string): Kline[];