@fin.cx/opendata/dist_ts/stocks/providers/provider.marketstack.d.ts

A comprehensive TypeScript library for accessing business data and real-time financial information. Features include German company data management with MongoDB integration, JSONL bulk processing, automated Handelsregister interactions, and real-time stoc

import type { IStockProvider, IProviderConfig } from '../interfaces/provider.js';
import type { IStockPrice, IStockDataRequest } from '../interfaces/stockprice.js';
/**
 * 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
 * - 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 (EOD only)
 * - Professional Plan: 100,000 requests/month (intraday + EOD)
 *
 * 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?;
    name: string;
    priority: number;
    readonly requiresAuth = true;
    readonly rateLimit: {
        requestsPerMinute: number;
        requestsPerDay: undefined;
    };
    private logger;
    private baseUrl;
    private apiKey;
    constructor(apiKey: string, config?: IProviderConfig | undefined);
    /**
     * Unified data fetching method supporting all request types
     */
    fetchData(request: IStockDataRequest): Promise<IStockPrice[] | IStockPrice>;
    /**
     * 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
     * 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 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
     */
    isAvailable(): Promise<boolean>;
    /**
     * Check if a market is supported
     * Marketstack supports 72+ exchanges worldwide
     */
    supportsMarket(market: string): boolean;
    /**
     * Check if a ticker format is supported
     */
    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;
    /**
     * Build full company name with exchange and ticker information
     * Example: "Apple Inc (NASDAQ:AAPL)"
     */
    private buildCompanyFullName;
    /**
     * 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;
}