@fin.cx/opendata 2.0.0 → 3.0.0

package/ts/stocks/interfaces/provider.ts

@@ -1,16 +1,15 @@
-import type { IStockPrice, IStockQuoteRequest, IStockBatchQuoteRequest } from './stockprice.js';
+import type { IStockPrice, IStockDataRequest } from './stockprice.js';
 
 export interface IStockProvider {
   name: string;
   priority: number;
-  
-  fetchPrice(request: IStockQuoteRequest): Promise<IStockPrice>;
-  fetchPrices(request: IStockBatchQuoteRequest): Promise<IStockPrice[]>;
+
+  fetchData(request: IStockDataRequest): Promise<IStockPrice | IStockPrice[]>;
   isAvailable(): Promise<boolean>;
-  
+
   supportsMarket?(market: string): boolean;
   supportsTicker?(ticker: string): boolean;
-  
+
   readonly requiresAuth: boolean;
   readonly rateLimit?: {
     requestsPerMinute: number;

package/ts/stocks/interfaces/stockprice.ts

@@ -1,5 +1,4 @@
-import * as plugins from '../../plugins.js';
-
+// Enhanced stock price interface with additional OHLCV data
 export interface IStockPrice {
   ticker: string;
   price: number;
@@ -12,11 +11,20 @@ export interface IStockPrice {
   marketState: 'PRE' | 'REGULAR' | 'POST' | 'CLOSED';
   exchange?: string;
   exchangeName?: string;
+
+  // Phase 1 enhancements
+  volume?: number;           // Trading volume
+  open?: number;            // Opening price
+  high?: number;            // Day high
+  low?: number;             // Day low
+  adjusted?: boolean;       // If price is split/dividend adjusted
+  dataType: 'eod' | 'intraday' | 'live'; // What kind of data this is
+  fetchedAt: Date;          // When we fetched (vs data timestamp)
+
+  // Company identification
+  companyName?: string;      // Company name (e.g., "Apple Inc.")
+  companyFullName?: string;  // Full company name with exchange (e.g., "Apple Inc. (NASDAQ:AAPL)")
 }
-type CheckStockPrice = plugins.tsclass.typeFest.IsEqual<
-  IStockPrice,
-  plugins.tsclass.finance.IStockPrice
->;
 
 export interface IStockPriceError {
   ticker: string;
@@ -25,12 +33,62 @@ export interface IStockPriceError {
   timestamp: Date;
 }
 
-export interface IStockQuoteRequest {
+// Pagination support for large datasets
+export interface IPaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    currentPage: number;
+    totalPages: number;
+    totalRecords: number;
+    hasMore: boolean;
+    limit: number;
+    offset: number;
+  };
+}
+
+// Phase 1: Discriminated union types for different request types
+export type TIntervalType = '1min' | '5min' | '10min' | '15min' | '30min' | '1hour';
+export type TSortOrder = 'ASC' | 'DESC';
+
+// Current price request (latest EOD or live)
+export interface IStockCurrentRequest {
+  type: 'current';
+  ticker: string;
+  exchange?: string; // MIC code like 'XNAS', 'XNYS', 'XLON'
+}
+
+// Historical price request (date range)
+export interface IStockHistoricalRequest {
+  type: 'historical';
+  ticker: string;
+  from: Date;
+  to: Date;
+  exchange?: string;
+  sort?: TSortOrder;
+  limit?: number; // Max results per page (default 1000)
+  offset?: number; // For pagination
+}
+
+// Intraday price request (real-time intervals)
+export interface IStockIntradayRequest {
+  type: 'intraday';
   ticker: string;
-  includeExtendedHours?: boolean;
+  interval: TIntervalType;
+  exchange?: string;
+  limit?: number; // Number of bars to return
+  date?: Date; // Specific date for historical intraday
 }
 
-export interface IStockBatchQuoteRequest {
+// Batch current prices request
+export interface IStockBatchCurrentRequest {
+  type: 'batch';
   tickers: string[];
-  includeExtendedHours?: boolean;
+  exchange?: string;
 }
+
+// Union type for all stock data requests
+export type IStockDataRequest =
+  | IStockCurrentRequest
+  | IStockHistoricalRequest
+  | IStockIntradayRequest
+  | IStockBatchCurrentRequest;

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

@@ -1,22 +1,37 @@
 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,
+  IStockDataRequest,
+  IStockCurrentRequest,
+  IStockHistoricalRequest,
+  IStockIntradayRequest,
+  IStockBatchCurrentRequest
+} 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 +55,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 +101,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 current price for ${request.ticker}:`, error);
+      throw new Error(`Marketstack: Failed to fetch current price for ${request.ticker}: ${error.message}`);
+    }
+  }
+
+  /**
+   * Fetch historical EOD prices for a ticker with date range
+   */
+  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 price for ${request.ticker}:`, error);
-      throw new Error(`Marketstack: Failed to fetch price for ${request.ticker}: ${error.message}`);
+      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 latest EOD prices for multiple tickers
+   * 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)
    */
-  public async fetchPrices(request: IStockBatchQuoteRequest): Promise<IStockPrice[]> {
+  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 +217,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,8 +230,8 @@ 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}`);
     }
   }
 
@@ -165,7 +284,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 +293,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 +312,65 @@ 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,
+
+      // Company identification
+      companyName: data.company_name || data.name || undefined,
+      companyFullName: this.buildCompanyFullName(data)
     };
 
     return stockPrice;
   }
+
+  /**
+   * Build full company name with exchange and ticker information
+   * Example: "Apple Inc (NASDAQ:AAPL)"
+   */
+  private buildCompanyFullName(data: any): string | undefined {
+    // Check if API already provides full name
+    if (data.full_name || data.long_name) {
+      return data.full_name || data.long_name;
+    }
+
+    // Build from available data
+    const companyName = data.company_name || data.name;
+    const exchangeCode = data.exchange_code; // e.g., "NASDAQ"
+    const symbol = data.symbol; // e.g., "AAPL"
+
+    if (!companyName) {
+      return undefined;
+    }
+
+    // If we have exchange and symbol, build full name: "Apple Inc (NASDAQ:AAPL)"
+    if (exchangeCode && symbol) {
+      return `${companyName} (${exchangeCode}:${symbol})`;
+    }
+
+    // If we only have symbol: "Apple Inc (AAPL)"
+    if (symbol) {
+      return `${companyName} (${symbol})`;
+    }
+
+    // Otherwise just return company name
+    return companyName;
+  }
+
+  /**
+   * 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

@@ -1,6 +1,11 @@
 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,
+  IStockDataRequest,
+  IStockCurrentRequest,
+  IStockBatchCurrentRequest
+} from '../interfaces/stockprice.js';
 
 export class YahooFinanceProvider implements IStockProvider {
   public name = 'Yahoo Finance';
@@ -17,7 +22,28 @@ export class YahooFinanceProvider implements IStockProvider {
 
   constructor(private config?: IProviderConfig) {}
 
-  public async fetchPrice(request: IStockQuoteRequest): Promise<IStockPrice> {
+  /**
+   * Unified data fetching method
+   */
+  public async fetchData(request: IStockDataRequest): Promise<IStockPrice | IStockPrice[]> {
+    switch (request.type) {
+      case 'current':
+        return this.fetchCurrentPrice(request);
+      case 'batch':
+        return this.fetchBatchCurrentPrices(request);
+      case 'historical':
+        throw new Error('Yahoo Finance provider does not support historical data. Use Marketstack provider instead.');
+      case 'intraday':
+        throw new Error('Yahoo Finance provider does not support intraday data yet. Use Marketstack provider instead.');
+      default:
+        throw new Error(`Unsupported request type: ${(request as any).type}`);
+    }
+  }
+
+  /**
+   * Fetch current price for a single ticker
+   */
+  private async fetchCurrentPrice(request: IStockCurrentRequest): Promise<IStockPrice> {
     try {
       const url = `${this.baseUrl}/v8/finance/chart/${request.ticker}`;
       const response = await plugins.smartrequest.SmartRequest.create()
@@ -52,7 +78,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;
@@ -62,7 +90,10 @@ export class YahooFinanceProvider implements IStockProvider {
     }
   }
 
-  public async fetchPrices(request: IStockBatchQuoteRequest): Promise<IStockPrice[]> {
+  /**
+   * Fetch batch current prices
+   */
+  private async fetchBatchCurrentPrices(request: IStockBatchCurrentRequest): Promise<IStockPrice[]> {
     try {
       const symbols = request.tickers.join(',');
       const url = `${this.baseUrl}/v8/finance/spark?symbols=${symbols}&range=1d&interval=5m`;
@@ -101,7 +132,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()
         });
       }
 
@@ -119,7 +152,7 @@ export class YahooFinanceProvider implements IStockProvider {
   public async isAvailable(): Promise<boolean> {
     try {
       // Test with a well-known ticker
-      await this.fetchPrice({ ticker: 'AAPL' });
+      await this.fetchData({ type: 'current', ticker: 'AAPL' });
       return true;
     } catch (error) {
       console.warn('Yahoo Finance provider is not available:', error);