@fin.cx/opendata 2.0.0 → 2.1.0

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

@@ -1,22 +1,41 @@
 import * as plugins from '../../plugins.js';
 import type { IStockProvider, IProviderConfig } from '../interfaces/provider.js';
-import type { IStockPrice, IStockQuoteRequest, IStockBatchQuoteRequest } from '../interfaces/stockprice.js';
+import type {
+  IStockPrice,
+  IStockQuoteRequest,
+  IStockBatchQuoteRequest,
+  IStockDataRequest,
+  IStockCurrentRequest,
+  IStockHistoricalRequest,
+  IStockIntradayRequest,
+  IStockBatchCurrentRequest,
+  IPaginatedResponse,
+  TSortOrder
+} from '../interfaces/stockprice.js';
 
 /**
- * Marketstack API v2 Provider
- * Documentation: https://marketstack.com/documentation_v2
+ * Marketstack API v2 Provider - Enhanced
+ * Documentation: https://docs.apilayer.com/marketstack/docs/marketstack-api-v2-v-2-0-0
  *
  * Features:
- * - End-of-Day (EOD) stock prices
- * - Supports 125,000+ tickers across 72+ exchanges worldwide
+ * - End-of-Day (EOD) stock prices with historical data
+ * - Intraday pricing with multiple intervals (1min, 5min, 15min, 30min, 1hour)
+ * - 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
  * - Requires API key authentication
  *
  * Rate Limits:
  * - Free Plan: 100 requests/month (EOD only)
  * - Basic Plan: 10,000 requests/month
- * - Professional Plan: 100,000 requests/month
+ * - Professional Plan: 100,000 requests/month (intraday access)
  *
- * Note: This provider returns EOD data, not real-time prices
+ * Phase 1 Enhancements:
+ * - Historical data retrieval with date ranges
+ * - Exchange filtering
+ * - OHLCV data support
+ * - Pagination handling
  */
 export class MarketstackProvider implements IStockProvider {
   public name = 'Marketstack';
@@ -40,11 +59,34 @@ export class MarketstackProvider implements IStockProvider {
   }
 
   /**
-   * Fetch latest EOD price for a single ticker
+   * Unified data fetching method supporting all request types
    */
-  public async fetchPrice(request: IStockQuoteRequest): Promise<IStockPrice> {
+  public async fetchData(request: IStockDataRequest): Promise<IStockPrice[] | IStockPrice> {
+    switch (request.type) {
+      case 'current':
+        return this.fetchCurrentPrice(request);
+      case 'historical':
+        return this.fetchHistoricalPrices(request);
+      case 'intraday':
+        return this.fetchIntradayPrices(request);
+      case 'batch':
+        return this.fetchBatchCurrentPrices(request);
+      default:
+        throw new Error(`Unsupported request type: ${(request as any).type}`);
+    }
+  }
+
+  /**
+   * Fetch current/latest EOD price for a single ticker (new API)
+   */
+  private async fetchCurrentPrice(request: IStockCurrentRequest): Promise<IStockPrice> {
     try {
-      const url = `${this.baseUrl}/tickers/${request.ticker}/eod/latest?access_key=${this.apiKey}`;
+      let url = `${this.baseUrl}/tickers/${request.ticker}/eod/latest?access_key=${this.apiKey}`;
+
+      // Add exchange filter if specified
+      if (request.exchange) {
+        url += `&exchange=${request.exchange}`;
+      }
 
       const response = await plugins.smartrequest.SmartRequest.create()
         .url(url)
@@ -63,20 +105,101 @@ export class MarketstackProvider implements IStockProvider {
         throw new Error(`No data found for ticker ${request.ticker}`);
       }
 
-      return this.mapToStockPrice(responseData);
+      return this.mapToStockPrice(responseData, 'eod');
     } catch (error) {
-      this.logger.error(`Failed to fetch price for ${request.ticker}:`, error);
-      throw new Error(`Marketstack: Failed to fetch price for ${request.ticker}: ${error.message}`);
+      this.logger.error(`Failed to fetch current price for ${request.ticker}:`, error);
+      throw new Error(`Marketstack: Failed to fetch current price for ${request.ticker}: ${error.message}`);
     }
   }
 
   /**
-   * Fetch latest EOD prices for multiple tickers
+   * Fetch historical EOD prices for a ticker with date range
    */
-  public async fetchPrices(request: IStockBatchQuoteRequest): Promise<IStockPrice[]> {
+  private async fetchHistoricalPrices(request: IStockHistoricalRequest): Promise<IStockPrice[]> {
+    try {
+      const allPrices: IStockPrice[] = [];
+      let offset = request.offset || 0;
+      const limit = request.limit || 1000; // Max per page
+      const maxRecords = 10000; // Safety limit
+
+      while (true) {
+        let url = `${this.baseUrl}/eod?access_key=${this.apiKey}`;
+        url += `&symbols=${request.ticker}`;
+        url += `&date_from=${this.formatDate(request.from)}`;
+        url += `&date_to=${this.formatDate(request.to)}`;
+        url += `&limit=${limit}`;
+        url += `&offset=${offset}`;
+
+        if (request.exchange) {
+          url += `&exchange=${request.exchange}`;
+        }
+
+        if (request.sort) {
+          url += `&sort=${request.sort}`;
+        }
+
+        const response = await plugins.smartrequest.SmartRequest.create()
+          .url(url)
+          .timeout(this.config?.timeout || 15000)
+          .get();
+
+        const responseData = await response.json() as any;
+
+        // Check for API errors
+        if (responseData.error) {
+          throw new Error(`Marketstack API error: ${responseData.error.message || JSON.stringify(responseData.error)}`);
+        }
+
+        if (!responseData?.data || !Array.isArray(responseData.data)) {
+          throw new Error('Invalid response format from Marketstack API');
+        }
+
+        // Map data to stock prices
+        for (const data of responseData.data) {
+          try {
+            allPrices.push(this.mapToStockPrice(data, 'eod'));
+          } catch (error) {
+            this.logger.warn(`Failed to parse historical data for ${data.symbol}:`, error);
+          }
+        }
+
+        // Check if we have more pages
+        const pagination = responseData.pagination;
+        const hasMore = pagination && offset + limit < pagination.total;
+
+        // Safety check: don't fetch more than maxRecords
+        if (!hasMore || allPrices.length >= maxRecords) {
+          break;
+        }
+
+        offset += limit;
+      }
+
+      return allPrices;
+    } catch (error) {
+      this.logger.error(`Failed to fetch historical prices for ${request.ticker}:`, error);
+      throw new Error(`Marketstack: Failed to fetch historical prices for ${request.ticker}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Fetch intraday prices with specified interval (Phase 2 placeholder)
+   */
+  private async fetchIntradayPrices(request: IStockIntradayRequest): Promise<IStockPrice[]> {
+    throw new Error('Intraday data support coming in Phase 2. For now, use EOD data with type: "current" or "historical"');
+  }
+
+  /**
+   * Fetch current prices for multiple tickers (new API)
+   */
+  private async fetchBatchCurrentPrices(request: IStockBatchCurrentRequest): Promise<IStockPrice[]> {
     try {
       const symbols = request.tickers.join(',');
-      const url = `${this.baseUrl}/eod/latest?access_key=${this.apiKey}&symbols=${symbols}`;
+      let url = `${this.baseUrl}/eod/latest?access_key=${this.apiKey}&symbols=${symbols}`;
+
+      if (request.exchange) {
+        url += `&exchange=${request.exchange}`;
+      }
 
       const response = await plugins.smartrequest.SmartRequest.create()
         .url(url)
@@ -98,7 +221,7 @@ export class MarketstackProvider implements IStockProvider {
 
       for (const data of responseData.data) {
         try {
-          prices.push(this.mapToStockPrice(data));
+          prices.push(this.mapToStockPrice(data, 'eod'));
         } catch (error) {
           this.logger.warn(`Failed to parse data for ${data.symbol}:`, error);
           // Continue processing other tickers
@@ -111,11 +234,35 @@ export class MarketstackProvider implements IStockProvider {
 
       return prices;
     } catch (error) {
-      this.logger.error(`Failed to fetch batch prices:`, error);
-      throw new Error(`Marketstack: Failed to fetch batch prices: ${error.message}`);
+      this.logger.error(`Failed to fetch batch current prices:`, error);
+      throw new Error(`Marketstack: Failed to fetch batch current prices: ${error.message}`);
     }
   }
 
+  /**
+   * Legacy: Fetch latest EOD price for a single ticker
+   * @deprecated Use fetchData with IStockDataRequest instead
+   */
+  public async fetchPrice(request: IStockQuoteRequest): Promise<IStockPrice> {
+    // Map legacy request to new format
+    return this.fetchCurrentPrice({
+      type: 'current',
+      ticker: request.ticker
+    });
+  }
+
+  /**
+   * Legacy: Fetch latest EOD prices for multiple tickers
+   * @deprecated Use fetchData with IStockDataRequest instead
+   */
+  public async fetchPrices(request: IStockBatchQuoteRequest): Promise<IStockPrice[]> {
+    // Map legacy request to new format
+    return this.fetchBatchCurrentPrices({
+      type: 'batch',
+      tickers: request.tickers
+    });
+  }
+
   /**
    * Check if the Marketstack API is available and accessible
    */
@@ -165,7 +312,7 @@ export class MarketstackProvider implements IStockProvider {
   /**
    * Map Marketstack API response to IStockPrice interface
    */
-  private mapToStockPrice(data: any): IStockPrice {
+  private mapToStockPrice(data: any, dataType: 'eod' | 'intraday' | 'live' = 'eod'): IStockPrice {
     if (!data.close) {
       throw new Error('Missing required price data');
     }
@@ -174,12 +321,13 @@ export class MarketstackProvider implements IStockProvider {
     // EOD data: previous close is typically open price of the same day
     // For better accuracy, we'd need previous day's close, but that requires another API call
     const currentPrice = data.close;
-    const previousClose = data.open;
+    const previousClose = data.open || currentPrice;
     const change = currentPrice - previousClose;
     const changePercent = previousClose !== 0 ? (change / previousClose) * 100 : 0;
 
     // Parse timestamp
     const timestamp = data.date ? new Date(data.date) : new Date();
+    const fetchedAt = new Date();
 
     const stockPrice: IStockPrice = {
       ticker: data.symbol.toUpperCase(),
@@ -192,9 +340,28 @@ export class MarketstackProvider implements IStockProvider {
       provider: this.name,
       marketState: 'CLOSED', // EOD data is always for closed markets
       exchange: data.exchange,
-      exchangeName: data.exchange_code || data.name
+      exchangeName: data.exchange_code || data.name,
+
+      // Phase 1 enhancements: OHLCV data
+      volume: data.volume,
+      open: data.open,
+      high: data.high,
+      low: data.low,
+      adjusted: data.adj_close !== undefined, // If adj_close exists, price is adjusted
+      dataType: dataType,
+      fetchedAt: fetchedAt
     };
 
     return stockPrice;
   }
+
+  /**
+   * Format date to YYYY-MM-DD for API requests
+   */
+  private formatDate(date: Date): string {
+    const year = date.getFullYear();
+    const month = String(date.getMonth() + 1).padStart(2, '0');
+    const day = String(date.getDate()).padStart(2, '0');
+    return `${year}-${month}-${day}`;
+  }
 }

package/ts/stocks/providers/provider.yahoo.ts

@@ -52,7 +52,9 @@ export class YahooFinanceProvider implements IStockProvider {
         provider: this.name,
         marketState: this.determineMarketState(meta),
         exchange: meta.exchange,
-        exchangeName: meta.exchangeName
+        exchangeName: meta.exchangeName,
+        dataType: 'live', // Yahoo provides real-time/near real-time data
+        fetchedAt: new Date()
       };
 
       return stockPrice;
@@ -101,7 +103,9 @@ export class YahooFinanceProvider implements IStockProvider {
           provider: this.name,
           marketState: sparkData.marketState || 'REGULAR',
           exchange: sparkData.exchange,
-          exchangeName: sparkData.exchangeName
+          exchangeName: sparkData.exchangeName,
+          dataType: 'live', // Yahoo provides real-time/near real-time data
+          fetchedAt: new Date()
         });
       }