pinets 0.9.4 → 0.9.6

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

@@ -12,7 +12,9 @@ export declare class Context {
     cache: any;
     taState: any;
     isSecondaryContext: boolean;
+    chartTimezone: string | null;
     dataVersion: number;
+    __maxLoops: number;
     NA: any;
     lang: any;
     length: number;

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

@@ -31,6 +31,23 @@ export declare class PineTS {
     private _isSecondaryContext;
     markAsSecondary(): void;
     private _syminfo;
+    private _chartTimezone;
+    /**
+     * Set the chart display timezone (like TradingView's timezone picker).
+     * This only affects log timestamp formatting — it does NOT change the timezone
+     * used by computation functions (timestamp(), dayofmonth, hour, etc.), which
+     * always use the exchange timezone from syminfo.timezone.
+     * @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;
     constructor(source: IProvider | any[], tickerId?: string, timeframe?: string, limit?: number, sDate?: number, eDate?: number);
     setDebugSettings({ ln, debug }: {
         ln: boolean;

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,5 +1,10 @@
-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();
@@ -9,13 +14,18 @@ export declare class BinanceProvider implements IProvider {
      * Caches the working endpoint for future calls.
      */
     private getBaseUrl;
-    getMarketDataInterval(tickerId: string, timeframe: string, sDate: number, eDate: number): Promise<any>;
+    /**
+     * Fetch a single chunk of raw kline data from the Binance API (no closeTime normalization).
+     * Used internally by pagination methods that assemble chunks before normalizing.
+     */
+    private _fetchRawChunk;
+    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;
@@ -40,8 +48,25 @@ export type ISymbolInfo = {
     target_price_low: number;
     target_price_median: number;
 };
+/**
+ * Market data provider interface.
+ *
+ * ## closeTime convention
+ * 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.
+ *
+ * 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
      */
@@ -89,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[];

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

@@ -0,0 +1,106 @@
+/**
+ * Standardized candlestick / kline data shape used by all providers.
+ */
+export 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;
+}
+/**
+ * Interval duration in milliseconds, keyed by normalized interval strings.
+ * Used by providers for pagination and date-range estimation.
+ *
+ * These use Binance-style interval keys ('1m', '1h', '1d', etc.)
+ * which are also the de-facto standard across most market data APIs.
+ */
+export declare const INTERVAL_DURATION_MS: Record<string, number>;
+/**
+ * Period types for timeframe-aware date arithmetic.
+ */
+export type PeriodType = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month';
+/**
+ * Duration in seconds for each canonical timeframe.
+ *
+ * Uses seconds (not minutes) to naturally accommodate TradingView's
+ * sub-minute timeframes ('1S', '5S', etc.) without fractional values.
+ * D/W/M values are approximate — used for ratio math, not calendar grouping.
+ */
+export declare const TIMEFRAME_SECONDS: Record<string, number>;
+/**
+ * Map from canonical timeframe to { periodType, multiplier }.
+ * Used by aggregation to determine grouping strategy.
+ */
+export declare const TIMEFRAME_PERIOD_INFO: Record<string, {
+    periodType: PeriodType;
+    multiplier: number;
+}>;
+/**
+ * Compute the start of the next period given an openTime (fixed duration math).
+ *
+ * For intraday / daily / weekly: adds fixed duration.
+ * For monthly: uses calendar math to land on the 1st of the next month.
+ *
+ * **Suitable for 24/7 crypto markets** where there are no session gaps.
+ * For stock/regulated markets, prefer `computeSessionClose()` or
+ * the Alpaca Calendar API which account for session boundaries,
+ * early closes, and holidays.
+ *
+ * @param openTimeMs - The bar's open time in epoch milliseconds
+ * @param periodType - The period unit ('minute', 'hour', 'day', 'week', 'month')
+ * @param multiplier - How many units per bar (e.g., 3 for 3Min, 4 for 4Hour). Default: 1
+ */
+export declare function computeNextPeriodStart(openTimeMs: number, periodType: PeriodType, multiplier?: number): number;
+/**
+ * Convert a local date + time string in a given IANA timezone to UTC milliseconds.
+ *
+ * Uses `Intl.DateTimeFormat` for DST-correct conversion — no external dependencies.
+ *
+ * @param dateStr - Date in "YYYY-MM-DD" format
+ * @param timeStr - Time in "HH:MM" format (24h)
+ * @param timezone - IANA timezone name (e.g. "America/New_York", "Etc/UTC")
+ * @returns UTC epoch milliseconds
+ */
+export declare function localTimeToUTC(dateStr: string, timeStr: string, timezone: string): number;
+/**
+ * Compute the session close time for a bar.
+ *
+ * For providers without a per-day calendar API (like FMP), this computes
+ * closeTime from the session string and exchange timezone.
+ *
+ * Logic by period type:
+ * - **24x7 session**: closeTime = openTime + barDuration (no gaps)
+ * - **Intraday** (minute, hour): min(openTime + barDuration, sessionEndOnThatDay)
+ * - **Daily** (day): same date at session end time in timezone
+ * - **Weekly** (week): Friday of that week at session end (approximation: no holiday calendar)
+ * - **Monthly** (month): last weekday of month at session end (approximation: no holiday calendar)
+ *
+ * @param openTimeMs - Bar open time in UTC epoch milliseconds
+ * @param session - Session string, e.g. "0930-1600" or "24x7"
+ * @param timezone - IANA timezone name, e.g. "America/New_York"
+ * @param periodType - The period unit
+ * @param multiplier - How many units per bar (default: 1)
+ */
+export declare function computeSessionClose(openTimeMs: number, session: string, timezone: string, periodType: PeriodType, multiplier?: number): number;
+/**
+ * Normalize closeTime for 24/7 crypto providers (Binance, Mock).
+ *
+ * Many crypto APIs (e.g. Binance) return closeTime as `nextBarOpen - 1ms`.
+ * For 24/7 markets, `nextBar.openTime == sessionClose`, so this is correct:
+ * - For bars 0..N-2: closeTime = next bar's openTime (exact for 24/7)
+ * - For the last bar: closeTime = raw closeTime + 1ms (best estimate)
+ *
+ * **Not suitable for stock/regulated market providers** — those must use
+ * `computeSessionClose()` or the Alpaca Calendar API for session-aware close times.
+ *
+ * Mutates the array in place.
+ */
+export declare function normalizeCloseTime(data: Kline[]): void;

package/dist/types/namespaces/Log.d.ts

@@ -4,6 +4,7 @@ export declare class Log {
     constructor(context: Context);
     private logFormat;
     param(source: any, index?: number, name?: string): any;
+    private _formatTimestamp;
     warning(message: string, ...args: any[]): void;
     error(message: string, ...args: any[]): void;
     info(message: string, ...args: any[]): void;