@fin.cx/opendata 3.2.2 → 3.4.0

package/dist_ts/stocks/providers/provider.marketstack.d.ts

@@ -1,28 +1,35 @@
 import type { IStockProvider, IProviderConfig } from '../interfaces/provider.js';
 import type { IStockPrice, IStockDataRequest } from '../interfaces/stockprice.js';
 /**
- * Marketstack API v2 Provider - Enhanced
+ * Marketstack API v2 Provider - Professional Plan with Intelligent Intraday Support
  * Documentation: https://docs.apilayer.com/marketstack/docs/marketstack-api-v2-v-2-0-0
  *
  * Features:
+ * - Intelligent endpoint selection based on market hours
+ * - Real-time intraday pricing with multiple intervals (1min, 5min, 10min, 15min, 30min, 1hour)
  * - End-of-Day (EOD) stock prices with historical data
- * - Intraday pricing with multiple intervals (1min, 5min, 15min, 30min, 1hour)
+ * - Market state detection (PRE, REGULAR, POST, CLOSED)
  * - Exchange filtering via MIC codes (XNAS, XNYS, XLON, etc.)
  * - Supports 500,000+ tickers across 72+ exchanges worldwide
  * - OHLCV data (Open, High, Low, Close, Volume)
  * - Pagination for large datasets
+ * - Automatic fallback from intraday to EOD on errors
  * - Requires API key authentication
  *
+ * Intelligent Endpoint Selection:
+ * - During market hours (PRE/REGULAR/POST): Uses intraday endpoints for fresh data
+ * - After market close (CLOSED): Uses EOD endpoints to save API credits
+ * - Automatic fallback to EOD if intraday fails (rate limits, plan restrictions, etc.)
+ *
  * Rate Limits:
  * - Free Plan: 100 requests/month (EOD only)
- * - Basic Plan: 10,000 requests/month
- * - Professional Plan: 100,000 requests/month (intraday access)
+ * - Basic Plan: 10,000 requests/month (EOD only)
+ * - Professional Plan: 100,000 requests/month (intraday + EOD)
  *
- * Phase 1 Enhancements:
- * - Historical data retrieval with date ranges
- * - Exchange filtering
- * - OHLCV data support
- * - Pagination handling
+ * Intraday Access:
+ * - Intervals below 15min (1min, 5min, 10min) require Professional Plan or higher
+ * - Real-time data from IEX Exchange for US tickers
+ * - Symbol formatting: Periods replaced with hyphens for intraday (BRK.B → BRK-B)
  */
 export declare class MarketstackProvider implements IStockProvider {
     private config?;
@@ -42,21 +49,44 @@ export declare class MarketstackProvider implements IStockProvider {
      */
     fetchData(request: IStockDataRequest): Promise<IStockPrice[] | IStockPrice>;
     /**
-     * Fetch current/latest EOD price for a single ticker (new API)
+     * Fetch current/latest price with intelligent endpoint selection
+     * Uses intraday during market hours (PRE, REGULAR, POST) for fresh data
+     * Uses EOD after market close (CLOSED) to save API credits
      */
     private fetchCurrentPrice;
+    /**
+     * Fetch current price using intraday endpoint (during market hours)
+     * Uses 1min interval for most recent data
+     */
+    private fetchCurrentPriceIntraday;
+    /**
+     * Fetch current price using EOD endpoint (after market close)
+     */
+    private fetchCurrentPriceEod;
     /**
      * Fetch historical EOD prices for a ticker with date range
      */
     private fetchHistoricalPrices;
     /**
-     * Fetch intraday prices with specified interval (Phase 2 placeholder)
+     * Fetch intraday prices with specified interval
+     * Supports intervals: 1min, 5min, 10min, 15min, 30min, 1hour
+     * Note: Intervals below 15min require Professional Plan or higher
      */
     private fetchIntradayPrices;
     /**
-     * Fetch current prices for multiple tickers (new API)
+     * Fetch current prices for multiple tickers with intelligent endpoint selection
+     * Uses intraday during market hours (PRE, REGULAR, POST) for fresh data
+     * Uses EOD after market close (CLOSED) to save API credits
      */
     private fetchBatchCurrentPrices;
+    /**
+     * Fetch batch current prices using intraday endpoint
+     */
+    private fetchBatchCurrentPricesIntraday;
+    /**
+     * Fetch batch current prices using EOD endpoint
+     */
+    private fetchBatchCurrentPricesEod;
     /**
      * Check if the Marketstack API is available and accessible
      */
@@ -72,6 +102,9 @@ export declare class MarketstackProvider implements IStockProvider {
     supportsTicker(ticker: string): boolean;
     /**
      * Map Marketstack API response to IStockPrice interface
+     * @param data - API response data
+     * @param dataType - Type of data (eod, intraday, live)
+     * @param explicitMarketState - Override market state (used for intraday data fetched during known market hours)
      */
     private mapToStockPrice;
     /**
@@ -83,4 +116,32 @@ export declare class MarketstackProvider implements IStockProvider {
      * Format date to YYYY-MM-DD for API requests
      */
     private formatDate;
+    /**
+     * Get US market state based on Eastern Time
+     * Regular hours: 9:30 AM - 4:00 PM ET
+     * Pre-market: 4:00 AM - 9:30 AM ET
+     * After-hours: 4:00 PM - 8:00 PM ET
+     *
+     * @param timestampMs - Optional timestamp in milliseconds (defaults to current time)
+     * @returns Market state: PRE, REGULAR, POST, or CLOSED
+     */
+    private getUsMarketState;
+    /**
+     * Determine if intraday endpoint should be used based on market state
+     * Uses intraday for PRE, REGULAR, and POST market states
+     * Uses EOD for CLOSED state to save API credits
+     *
+     * @param marketState - Current market state
+     * @returns true if intraday endpoint should be used
+     */
+    private shouldUseIntradayEndpoint;
+    /**
+     * Format ticker symbol for intraday endpoints
+     * Marketstack intraday API requires periods to be replaced with hyphens
+     * Example: BRK.B → BRK-B
+     *
+     * @param symbol - Original ticker symbol
+     * @returns Formatted symbol for intraday endpoints
+     */
+    private formatSymbolForIntraday;
 }