@fin.cx/opendata 1.7.0 → 2.1.0

package/ts/stocks/classes.stockservice.ts

@@ -1,6 +1,17 @@
 import * as plugins from '../plugins.js';
 import type { IStockProvider, IProviderConfig, IProviderRegistry } from './interfaces/provider.js';
-import type { IStockPrice, IStockQuoteRequest, IStockBatchQuoteRequest, IStockPriceError } from './interfaces/stockprice.js';
+import type {
+  IStockPrice,
+  IStockQuoteRequest,
+  IStockBatchQuoteRequest,
+  IStockPriceError,
+  IStockDataRequest,
+  IStockCurrentRequest,
+  IStockHistoricalRequest,
+  IStockIntradayRequest,
+  IStockBatchCurrentRequest,
+  TIntervalType
+} from './interfaces/stockprice.js';
 
 interface IProviderEntry {
   provider: IStockProvider;
@@ -12,18 +23,19 @@ interface IProviderEntry {
 }
 
 interface ICacheEntry {
-  price: IStockPrice;
+  price: IStockPrice | IStockPrice[];
   timestamp: Date;
+  ttl: number; // Specific TTL for this entry
 }
 
 export class StockPriceService implements IProviderRegistry {
   private providers = new Map<string, IProviderEntry>();
   private cache = new Map<string, ICacheEntry>();
   private logger = console;
-  
+
   private cacheConfig = {
-    ttl: 60000, // 60 seconds default
-    maxEntries: 1000
+    ttl: 60000, // 60 seconds default (for backward compatibility)
+    maxEntries: 10000 // Increased for historical data
   };
 
   constructor(cacheConfig?: { ttl?: number; maxEntries?: number }) {
@@ -32,6 +44,43 @@ export class StockPriceService implements IProviderRegistry {
     }
   }
 
+  /**
+   * Get data-type aware TTL for smart caching
+   */
+  private getCacheTTL(dataType: 'eod' | 'historical' | 'intraday' | 'live', interval?: TIntervalType): number {
+    switch (dataType) {
+      case 'historical':
+        return Infinity; // Historical data never changes
+      case 'eod':
+        return 24 * 60 * 60 * 1000; // 24 hours (EOD is static after market close)
+      case 'intraday':
+        // Match cache TTL to interval
+        return this.getIntervalMs(interval);
+      case 'live':
+        return 30 * 1000; // 30 seconds for live data
+      default:
+        return this.cacheConfig.ttl; // Fallback to default
+    }
+  }
+
+  /**
+   * Convert interval to milliseconds
+   */
+  private getIntervalMs(interval?: TIntervalType): number {
+    if (!interval) return 60 * 1000; // Default 1 minute
+
+    const intervalMap: Record<TIntervalType, number> = {
+      '1min': 60 * 1000,
+      '5min': 5 * 60 * 1000,
+      '10min': 10 * 60 * 1000,
+      '15min': 15 * 60 * 1000,
+      '30min': 30 * 60 * 1000,
+      '1hour': 60 * 60 * 1000
+    };
+
+    return intervalMap[interval] || 60 * 1000;
+  }
+
   public register(provider: IStockProvider, config?: IProviderConfig): void {
     const defaultConfig: IProviderConfig = {
       enabled: true,
@@ -75,8 +124,8 @@ export class StockPriceService implements IProviderRegistry {
 
   public async getPrice(request: IStockQuoteRequest): Promise<IStockPrice> {
     const cacheKey = this.getCacheKey(request);
-    const cached = this.getFromCache(cacheKey);
-    
+    const cached = this.getFromCache(cacheKey) as IStockPrice | null;
+
     if (cached) {
       console.log(`Cache hit for ${request.ticker}`);
       return cached;
@@ -91,7 +140,7 @@ export class StockPriceService implements IProviderRegistry {
 
     for (const provider of providers) {
       const entry = this.providers.get(provider.name)!;
-      
+
       try {
         const price = await this.fetchWithRetry(
           () => provider.fetchPrice(request),
@@ -99,7 +148,11 @@ export class StockPriceService implements IProviderRegistry {
         );
 
         entry.successCount++;
-        this.addToCache(cacheKey, price);
+
+        // Use smart TTL based on data type
+        const ttl = this.getCacheTTL(price.dataType);
+        this.addToCache(cacheKey, price, ttl);
+
         console.log(`Successfully fetched ${request.ticker} from ${provider.name}`);
         return price;
       } catch (error) {
@@ -107,7 +160,7 @@ export class StockPriceService implements IProviderRegistry {
         entry.lastError = error as Error;
         entry.lastErrorTime = new Date();
         lastError = error as Error;
-        
+
         console.warn(
           `Provider ${provider.name} failed for ${request.ticker}: ${error.message}`
         );
@@ -126,8 +179,8 @@ export class StockPriceService implements IProviderRegistry {
     // Check cache for each ticker
     for (const ticker of request.tickers) {
       const cacheKey = this.getCacheKey({ ticker, includeExtendedHours: request.includeExtendedHours });
-      const cached = this.getFromCache(cacheKey);
-      
+      const cached = this.getFromCache(cacheKey) as IStockPrice | null;
+
       if (cached) {
         cachedPrices.push(cached);
       } else {
@@ -150,25 +203,26 @@ export class StockPriceService implements IProviderRegistry {
 
     for (const provider of providers) {
       const entry = this.providers.get(provider.name)!;
-      
+
       try {
         fetchedPrices = await this.fetchWithRetry(
-          () => provider.fetchPrices({ 
-            tickers: tickersToFetch, 
-            includeExtendedHours: request.includeExtendedHours 
+          () => provider.fetchPrices({
+            tickers: tickersToFetch,
+            includeExtendedHours: request.includeExtendedHours
           }),
           entry.config
         );
 
         entry.successCount++;
-        
-        // Cache the fetched prices
+
+        // Cache the fetched prices with smart TTL
         for (const price of fetchedPrices) {
-          const cacheKey = this.getCacheKey({ 
-            ticker: price.ticker, 
-            includeExtendedHours: request.includeExtendedHours 
+          const cacheKey = this.getCacheKey({
+            ticker: price.ticker,
+            includeExtendedHours: request.includeExtendedHours
           });
-          this.addToCache(cacheKey, price);
+          const ttl = this.getCacheTTL(price.dataType);
+          this.addToCache(cacheKey, price, ttl);
         }
 
         console.log(
@@ -180,7 +234,7 @@ export class StockPriceService implements IProviderRegistry {
         entry.lastError = error as Error;
         entry.lastErrorTime = new Date();
         lastError = error as Error;
-        
+
         console.warn(
           `Provider ${provider.name} failed for batch request: ${error.message}`
         );
@@ -196,6 +250,101 @@ export class StockPriceService implements IProviderRegistry {
     return [...cachedPrices, ...fetchedPrices];
   }
 
+  /**
+   * New unified data fetching method supporting all request types
+   */
+  public async getData(request: IStockDataRequest): Promise<IStockPrice | IStockPrice[]> {
+    const cacheKey = this.getDataCacheKey(request);
+    const cached = this.getFromCache(cacheKey);
+
+    if (cached) {
+      console.log(`Cache hit for ${this.getRequestDescription(request)}`);
+      return cached;
+    }
+
+    const providers = this.getEnabledProviders();
+    if (providers.length === 0) {
+      throw new Error('No stock price providers available');
+    }
+
+    let lastError: Error | undefined;
+
+    for (const provider of providers) {
+      const entry = this.providers.get(provider.name)!;
+
+      // Check if provider supports the new fetchData method
+      if (typeof (provider as any).fetchData !== 'function') {
+        console.warn(`Provider ${provider.name} does not support new API, skipping`);
+        continue;
+      }
+
+      try {
+        const result = await this.fetchWithRetry(
+          () => (provider as any).fetchData(request),
+          entry.config
+        ) as IStockPrice | IStockPrice[];
+
+        entry.successCount++;
+
+        // Determine TTL based on request type
+        const ttl = this.getRequestTTL(request, result);
+        this.addToCache(cacheKey, result, ttl);
+
+        console.log(`Successfully fetched ${this.getRequestDescription(request)} from ${provider.name}`);
+        return result;
+      } catch (error) {
+        entry.errorCount++;
+        entry.lastError = error as Error;
+        entry.lastErrorTime = new Date();
+        lastError = error as Error;
+
+        console.warn(
+          `Provider ${provider.name} failed for ${this.getRequestDescription(request)}: ${error.message}`
+        );
+      }
+    }
+
+    throw new Error(
+      `Failed to fetch ${this.getRequestDescription(request)} from all providers. Last error: ${lastError?.message}`
+    );
+  }
+
+  /**
+   * Get TTL based on request type and result
+   */
+  private getRequestTTL(request: IStockDataRequest, result: IStockPrice | IStockPrice[]): number {
+    switch (request.type) {
+      case 'historical':
+        return Infinity; // Historical data never changes
+      case 'current':
+        return this.getCacheTTL('eod');
+      case 'batch':
+        return this.getCacheTTL('eod');
+      case 'intraday':
+        return this.getCacheTTL('intraday', request.interval);
+      default:
+        return this.cacheConfig.ttl;
+    }
+  }
+
+  /**
+   * Get human-readable description of request
+   */
+  private getRequestDescription(request: IStockDataRequest): string {
+    switch (request.type) {
+      case 'current':
+        return `current price for ${request.ticker}${request.exchange ? ` on ${request.exchange}` : ''}`;
+      case 'historical':
+        return `historical prices for ${request.ticker} from ${request.from.toISOString().split('T')[0]} to ${request.to.toISOString().split('T')[0]}`;
+      case 'intraday':
+        return `intraday ${request.interval} prices for ${request.ticker}`;
+      case 'batch':
+        return `batch prices for ${request.tickers.length} tickers`;
+      default:
+        return 'data';
+    }
+  }
+
   public async checkProvidersHealth(): Promise<Map<string, boolean>> {
     const health = new Map<string, boolean>();
     
@@ -271,19 +420,45 @@ export class StockPriceService implements IProviderRegistry {
     throw lastError || new Error('Unknown error during fetch');
   }
 
+  /**
+   * Legacy cache key generation
+   */
   private getCacheKey(request: IStockQuoteRequest): string {
     return `${request.ticker}:${request.includeExtendedHours || false}`;
   }
 
-  private getFromCache(key: string): IStockPrice | null {
+  /**
+   * New cache key generation for discriminated union requests
+   */
+  private getDataCacheKey(request: IStockDataRequest): string {
+    switch (request.type) {
+      case 'current':
+        return `current:${request.ticker}${request.exchange ? `:${request.exchange}` : ''}`;
+      case 'historical':
+        const fromStr = request.from.toISOString().split('T')[0];
+        const toStr = request.to.toISOString().split('T')[0];
+        return `historical:${request.ticker}:${fromStr}:${toStr}${request.exchange ? `:${request.exchange}` : ''}`;
+      case 'intraday':
+        const dateStr = request.date ? request.date.toISOString().split('T')[0] : 'latest';
+        return `intraday:${request.ticker}:${request.interval}:${dateStr}${request.exchange ? `:${request.exchange}` : ''}`;
+      case 'batch':
+        const tickers = request.tickers.sort().join(',');
+        return `batch:${tickers}${request.exchange ? `:${request.exchange}` : ''}`;
+      default:
+        return `unknown:${JSON.stringify(request)}`;
+    }
+  }
+
+  private getFromCache(key: string): IStockPrice | IStockPrice[] | null {
     const entry = this.cache.get(key);
-    
+
     if (!entry) {
       return null;
     }
 
+    // Check if cache entry has expired
     const age = Date.now() - entry.timestamp.getTime();
-    if (age > this.cacheConfig.ttl) {
+    if (entry.ttl !== Infinity && age > entry.ttl) {
       this.cache.delete(key);
       return null;
     }
@@ -291,7 +466,7 @@ export class StockPriceService implements IProviderRegistry {
     return entry.price;
   }
 
-  private addToCache(key: string, price: IStockPrice): void {
+  private addToCache(key: string, price: IStockPrice | IStockPrice[], ttl?: number): void {
     // Enforce max entries limit
     if (this.cache.size >= this.cacheConfig.maxEntries) {
       // Remove oldest entry
@@ -303,7 +478,8 @@ export class StockPriceService implements IProviderRegistry {
 
     this.cache.set(key, {
       price,
-      timestamp: new Date()
+      timestamp: new Date(),
+      ttl: ttl || this.cacheConfig.ttl
     });
   }
 }

package/ts/stocks/interfaces/stockprice.ts

@@ -1,5 +1,6 @@
 import * as plugins from '../../plugins.js';
 
+// Enhanced stock price interface with additional OHLCV data
 export interface IStockPrice {
   ticker: string;
   price: number;
@@ -12,6 +13,15 @@ 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)
 }
 type CheckStockPrice = plugins.tsclass.typeFest.IsEqual<
   IStockPrice,
@@ -25,11 +35,74 @@ export interface IStockPriceError {
   timestamp: Date;
 }
 
+// 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;
+  interval: TIntervalType;
+  exchange?: string;
+  limit?: number; // Number of bars to return
+  date?: Date; // Specific date for historical intraday
+}
+
+// Batch current prices request
+export interface IStockBatchCurrentRequest {
+  type: 'batch';
+  tickers: string[];
+  exchange?: string;
+}
+
+// Union type for all stock data requests
+export type IStockDataRequest =
+  | IStockCurrentRequest
+  | IStockHistoricalRequest
+  | IStockIntradayRequest
+  | IStockBatchCurrentRequest;
+
+// Legacy interfaces (for backward compatibility during migration)
+/** @deprecated Use IStockDataRequest with type: 'current' instead */
 export interface IStockQuoteRequest {
   ticker: string;
   includeExtendedHours?: boolean;
 }
 
+/** @deprecated Use IStockDataRequest with type: 'batch' instead */
 export interface IStockBatchQuoteRequest {
   tickers: string[];
   includeExtendedHours?: boolean;