@fin.cx/opendata 2.0.0 → 3.0.0

package/readme.md

@@ -4,7 +4,49 @@
 
 Access live stock prices, cryptocurrencies, forex, commodities AND comprehensive German company data - all through a single, unified API.
 
-## ⚠️ Breaking Change in v2.0
+## ⚠️ Breaking Changes
+
+### v2.1 - Enhanced Stock Market API (Current)
+
+**The stock market API has been significantly enhanced with a new unified request system.**
+
+**What Changed:**
+- New discriminated union request types (`IStockDataRequest`)
+- Enhanced `IStockPrice` interface with OHLCV data and metadata
+- New `getData()` method replaces legacy `getPrice()` and `getPrices()`
+- Historical data support with date ranges
+- Exchange filtering via MIC codes
+- Smart caching with data-type aware TTL
+
+**Migration:**
+```typescript
+// OLD (v2.0 and earlier)
+const price = await service.getPrice({ ticker: 'AAPL' });
+const prices = await service.getPrices({ tickers: ['AAPL', 'MSFT'] });
+
+// NEW (v2.1+) - Unified API
+const price = await service.getData({ type: 'current', ticker: 'AAPL' });
+const prices = await service.getData({ type: 'batch', tickers: ['AAPL', 'MSFT'] });
+
+// NEW - Historical data
+const history = await service.getData({
+  type: 'historical',
+  ticker: 'AAPL',
+  from: new Date('2024-01-01'),
+  to: new Date('2024-12-31')
+});
+
+// NEW - Exchange filtering
+const price = await service.getData({
+  type: 'current',
+  ticker: 'VOD',
+  exchange: 'XLON' // London Stock Exchange
+});
+```
+
+**Note:** Legacy `getPrice()` and `getPrices()` methods still work but are deprecated.
+
+### v2.0 - Directory Configuration
 
 **Directory paths are now MANDATORY when using German business data features.** The package no longer creates `.nogit/` directories automatically. You must explicitly configure all directory paths when instantiating `OpenData`:
 
@@ -28,17 +70,17 @@ pnpm add @fin.cx/opendata
 
 ## Quick Start
 
-### 📈 Stock Market Data
+### 📈 Stock Market Data (v2.1+ Enhanced)
 
-Get market data with EOD (End-of-Day) pricing:
+Get comprehensive market data with EOD, historical, and OHLCV data:
 
 ```typescript
 import { StockPriceService, MarketstackProvider } from '@fin.cx/opendata';
 
-// Initialize the service with caching
+// Initialize the service with smart caching
 const stockService = new StockPriceService({
-  ttl: 60000,      // Cache for 1 minute
-  maxEntries: 1000 // Max cached symbols
+  ttl: 60000,       // Default cache TTL (historical data cached forever)
+  maxEntries: 10000  // Increased for historical data
 });
 
 // Register Marketstack provider with API key
@@ -47,19 +89,55 @@ stockService.register(new MarketstackProvider('YOUR_API_KEY'), {
   retryAttempts: 3
 });
 
-// Get single stock price
-const apple = await stockService.getPrice({ ticker: 'AAPL' });
+// Get current price (new unified API)
+const apple = await stockService.getData({ type: 'current', ticker: 'AAPL' });
 console.log(`Apple: $${apple.price} (${apple.changePercent.toFixed(2)}%)`);
+console.log(`OHLCV: O=${apple.open} H=${apple.high} L=${apple.low} V=${apple.volume}`);
+console.log(`Company: ${apple.companyName}`);        // "Apple Inc"
+console.log(`Full: ${apple.companyFullName}`);       // "Apple Inc (NASDAQ:AAPL)"
+
+// Get historical data (1 year of daily prices)
+const history = await stockService.getData({
+  type: 'historical',
+  ticker: 'AAPL',
+  from: new Date('2024-01-01'),
+  to: new Date('2024-12-31'),
+  sort: 'DESC' // Newest first
+});
+console.log(`Fetched ${history.length} trading days`);
 
-// Get multiple prices at once (batch fetching)
-const prices = await stockService.getPrices({
-  tickers: ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA']
+// Exchange-specific data (London vs NYSE)
+const vodLondon = await stockService.getData({
+  type: 'current',
+  ticker: 'VOD',
+  exchange: 'XLON' // London Stock Exchange
 });
 
-// 125,000+ tickers across 72+ exchanges worldwide
-const internationalStocks = await stockService.getPrices({
-  tickers: ['AAPL', 'VOD.LON', 'SAP.DEX', 'TM', 'BABA']
+const vodNYSE = await stockService.getData({
+  type: 'current',
+  ticker: 'VOD',
+  exchange: 'XNYS' // New York Stock Exchange
 });
+
+// Batch current prices with company names
+const prices = await stockService.getData({
+  type: 'batch',
+  tickers: ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA']
+});
+
+// Display with company names (automatically included - zero extra API calls!)
+for (const stock of prices) {
+  console.log(`${stock.companyName}: $${stock.price}`);
+  // Output:
+  // Apple Inc: $271.40
+  // Microsoft Corporation: $525.76
+  // Alphabet Inc - Class A: $281.48
+  // Amazon.com Inc: $222.86
+  // Tesla Inc: $440.10
+}
+
+// Use companyFullName for richer context
+console.log(prices[0].companyFullName); // "Apple Inc (NASDAQ:AAPL)"
 ```
 
 ### 🏢 German Business Data
@@ -100,15 +178,19 @@ await openData.buildInitialDb();
 
 ## Features
 
-### 🎯 Stock Market Module
+### 🎯 Stock Market Module (v2.1 Enhanced)
 
-- **Marketstack API** - End-of-Day (EOD) data for 125,000+ tickers across 72+ exchanges
-- **Stock prices** for stocks, ETFs, indices, and more
-- **Batch operations** - fetch 100+ symbols in one request
-- **Smart caching** - configurable TTL, automatic invalidation
-- **Extensible provider system** - easily add new data sources
-- **Retry logic** - configurable retry attempts and delays
-- **Type-safe** - full TypeScript support with detailed interfaces
+- **Company Names** - Automatic company name extraction with zero extra API calls (e.g., "Apple Inc (NASDAQ:AAPL)")
+- **Historical Data** - Up to 15 years of daily EOD prices with automatic pagination
+- **Exchange Filtering** - Query specific exchanges via MIC codes (XNAS, XLON, XNYS, etc.)
+- **OHLCV Data** - Open, High, Low, Close, Volume for comprehensive analysis
+- **Smart Caching** - Data-type aware TTL (historical cached forever, EOD 24h, live 30s)
+- **Marketstack API** - 500,000+ tickers across 72+ exchanges worldwide
+- **Batch Operations** - Fetch 100+ symbols in one request
+- **Unified API** - Discriminated union types for type-safe requests
+- **Extensible Providers** - Easy to add new data sources
+- **Retry Logic** - Configurable attempts and delays
+- **Type-Safe** - Full TypeScript support with detailed interfaces
 
 ### 🇩🇪 German Business Intelligence
 
@@ -120,6 +202,151 @@ await openData.buildInitialDb();
 
 ## Advanced Examples
 
+### Phase 1: Historical Data Analysis
+
+Fetch and analyze historical price data:
+
+```typescript
+// Get 1 year of historical data
+const history = await stockService.getData({
+  type: 'historical',
+  ticker: 'AAPL',
+  from: new Date('2024-01-01'),
+  to: new Date('2024-12-31'),
+  sort: 'DESC' // Newest first (default)
+});
+
+// Calculate statistics
+const prices = history.map(p => p.price);
+const high52Week = Math.max(...prices);
+const low52Week = Math.min(...prices);
+const avgPrice = prices.reduce((a, b) => a + b) / prices.length;
+
+console.log(`52-Week Analysis for AAPL:`);
+console.log(`High:    $${high52Week.toFixed(2)}`);
+console.log(`Low:     $${low52Week.toFixed(2)}`);
+console.log(`Average: $${avgPrice.toFixed(2)}`);
+console.log(`Days:    ${history.length}`);
+
+// Calculate daily returns
+for (let i = 0; i < history.length - 1; i++) {
+  const todayPrice = history[i].price;
+  const yesterdayPrice = history[i + 1].price;
+  const dailyReturn = ((todayPrice - yesterdayPrice) / yesterdayPrice) * 100;
+  console.log(`${history[i].timestamp.toISOString().split('T')[0]}: ${dailyReturn.toFixed(2)}%`);
+}
+```
+
+### Phase 1: Exchange-Specific Trading
+
+Compare prices across different exchanges:
+
+```typescript
+// Vodafone trades on both London and NYSE
+const exchanges = [
+  { mic: 'XLON', name: 'London Stock Exchange' },
+  { mic: 'XNYS', name: 'New York Stock Exchange' }
+];
+
+for (const exchange of exchanges) {
+  try {
+    const price = await stockService.getData({
+      type: 'current',
+      ticker: 'VOD',
+      exchange: exchange.mic
+    });
+
+    console.log(`${exchange.name}:`);
+    console.log(`  Price: ${price.price} ${price.currency}`);
+    console.log(`  Volume: ${price.volume?.toLocaleString()}`);
+    console.log(`  Exchange: ${price.exchangeName}`);
+  } catch (error) {
+    console.log(`${exchange.name}: Not available`);
+  }
+}
+```
+
+### Phase 1: OHLCV Technical Analysis
+
+Use OHLCV data for technical indicators:
+
+```typescript
+const history = await stockService.getData({
+  type: 'historical',
+  ticker: 'TSLA',
+  from: new Date('2024-11-01'),
+  to: new Date('2024-11-30')
+});
+
+// Calculate daily trading range
+for (const day of history) {
+  const range = day.high - day.low;
+  const rangePercent = (range / day.low) * 100;
+
+  console.log(`${day.timestamp.toISOString().split('T')[0]}:`);
+  console.log(`  Open:   $${day.open}`);
+  console.log(`  High:   $${day.high}`);
+  console.log(`  Low:    $${day.low}`);
+  console.log(`  Close:  $${day.price}`);
+  console.log(`  Volume: ${day.volume?.toLocaleString()}`);
+  console.log(`  Range:  $${range.toFixed(2)} (${rangePercent.toFixed(2)}%)`);
+}
+
+// Calculate Simple Moving Average (SMA)
+const calculateSMA = (data: IStockPrice[], period: number) => {
+  const sma: number[] = [];
+  for (let i = period - 1; i < data.length; i++) {
+    const sum = data.slice(i - period + 1, i + 1)
+      .reduce((acc, p) => acc + p.price, 0);
+    sma.push(sum / period);
+  }
+  return sma;
+};
+
+const sma20 = calculateSMA(history, 20);
+const sma50 = calculateSMA(history, 50);
+
+console.log(`20-day SMA: $${sma20[0].toFixed(2)}`);
+console.log(`50-day SMA: $${sma50[0].toFixed(2)}`);
+```
+
+### Phase 1: Smart Caching Performance
+
+Leverage smart caching for efficiency:
+
+```typescript
+// Historical data is cached FOREVER (never changes)
+console.time('First historical fetch');
+const history1 = await stockService.getData({
+  type: 'historical',
+  ticker: 'AAPL',
+  from: new Date('2024-01-01'),
+  to: new Date('2024-12-31')
+});
+console.timeEnd('First historical fetch');
+// Output: First historical fetch: 2341ms
+
+console.time('Second historical fetch (cached)');
+const history2 = await stockService.getData({
+  type: 'historical',
+  ticker: 'AAPL',
+  from: new Date('2024-01-01'),
+  to: new Date('2024-12-31')
+});
+console.timeEnd('Second historical fetch (cached)');
+// Output: Second historical fetch (cached): 2ms (1000x faster!)
+
+// EOD data cached for 24 hours
+const currentPrice = await stockService.getData({
+  type: 'current',
+  ticker: 'MSFT'
+});
+// Subsequent calls within 24h served from cache
+
+// Cache statistics
+console.log(`Cache size: ${stockService['cache'].size} entries`);
+```
+
 ### Market Dashboard
 
 Create an EOD market overview:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '2.0.0',
+  version: '3.0.0',
   description: '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 stock market data from multiple providers.'
 }

package/ts/stocks/classes.stockservice.ts

@@ -1,6 +1,24 @@
 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,
+  IStockPriceError,
+  IStockDataRequest,
+  IStockCurrentRequest,
+  IStockHistoricalRequest,
+  IStockIntradayRequest,
+  IStockBatchCurrentRequest,
+  TIntervalType
+} from './interfaces/stockprice.js';
+
+// Simple request interfaces for convenience methods
+interface ISimpleQuoteRequest {
+  ticker: string;
+}
+
+interface ISimpleBatchRequest {
+  tickers: string[];
+}
 
 interface IProviderEntry {
   provider: IStockProvider;
@@ -12,18 +30,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 +51,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,
@@ -73,12 +129,37 @@ export class StockPriceService implements IProviderRegistry {
       .map(entry => entry.provider);
   }
 
-  public async getPrice(request: IStockQuoteRequest): Promise<IStockPrice> {
-    const cacheKey = this.getCacheKey(request);
+  /**
+   * Convenience method: Get current price for a single ticker
+   */
+  public async getPrice(request: ISimpleQuoteRequest): Promise<IStockPrice> {
+    const result = await this.getData({
+      type: 'current',
+      ticker: request.ticker
+    });
+    return result as IStockPrice;
+  }
+
+  /**
+   * Convenience method: Get current prices for multiple tickers
+   */
+  public async getPrices(request: ISimpleBatchRequest): Promise<IStockPrice[]> {
+    const result = await this.getData({
+      type: 'batch',
+      tickers: request.tickers
+    });
+    return result as IStockPrice[];
+  }
+
+  /**
+   * 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 ${request.ticker}`);
+      console.log(`Cache hit for ${this.getRequestDescription(request)}`);
       return cached;
     }
 
@@ -91,109 +172,72 @@ 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),
+        const result = await this.fetchWithRetry(
+          () => provider.fetchData(request),
           entry.config
-        );
+        ) as IStockPrice | IStockPrice[];
 
         entry.successCount++;
-        this.addToCache(cacheKey, price);
-        console.log(`Successfully fetched ${request.ticker} from ${provider.name}`);
-        return price;
+
+        // 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 ${request.ticker}: ${error.message}`
+          `Provider ${provider.name} failed for ${this.getRequestDescription(request)}: ${error.message}`
         );
       }
     }
 
     throw new Error(
-      `Failed to fetch price for ${request.ticker} from all providers. Last error: ${lastError?.message}`
+      `Failed to fetch ${this.getRequestDescription(request)} from all providers. Last error: ${lastError?.message}`
     );
   }
 
-  public async getPrices(request: IStockBatchQuoteRequest): Promise<IStockPrice[]> {
-    const cachedPrices: IStockPrice[] = [];
-    const tickersToFetch: string[] = [];
-
-    // Check cache for each ticker
-    for (const ticker of request.tickers) {
-      const cacheKey = this.getCacheKey({ ticker, includeExtendedHours: request.includeExtendedHours });
-      const cached = this.getFromCache(cacheKey);
-      
-      if (cached) {
-        cachedPrices.push(cached);
-      } else {
-        tickersToFetch.push(ticker);
-      }
-    }
-
-    if (tickersToFetch.length === 0) {
-      console.log(`All ${request.tickers.length} tickers served from cache`);
-      return cachedPrices;
-    }
-
-    const providers = this.getEnabledProviders();
-    if (providers.length === 0) {
-      throw new Error('No stock price providers available');
-    }
-
-    let lastError: Error | undefined;
-    let fetchedPrices: IStockPrice[] = [];
-
-    for (const provider of providers) {
-      const entry = this.providers.get(provider.name)!;
-      
-      try {
-        fetchedPrices = await this.fetchWithRetry(
-          () => provider.fetchPrices({ 
-            tickers: tickersToFetch, 
-            includeExtendedHours: request.includeExtendedHours 
-          }),
-          entry.config
-        );
-
-        entry.successCount++;
-        
-        // Cache the fetched prices
-        for (const price of fetchedPrices) {
-          const cacheKey = this.getCacheKey({ 
-            ticker: price.ticker, 
-            includeExtendedHours: request.includeExtendedHours 
-          });
-          this.addToCache(cacheKey, price);
-        }
-
-        console.log(
-          `Successfully fetched ${fetchedPrices.length} prices from ${provider.name}`
-        );
-        break;
-      } catch (error) {
-        entry.errorCount++;
-        entry.lastError = error as Error;
-        entry.lastErrorTime = new Date();
-        lastError = error as Error;
-        
-        console.warn(
-          `Provider ${provider.name} failed for batch request: ${error.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;
     }
+  }
 
-    if (fetchedPrices.length === 0 && lastError) {
-      throw new Error(
-        `Failed to fetch prices from all providers. Last error: ${lastError.message}`
-      );
+  /**
+   * 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';
     }
-
-    return [...cachedPrices, ...fetchedPrices];
   }
 
   public async checkProvidersHealth(): Promise<Map<string, boolean>> {
@@ -271,19 +315,38 @@ export class StockPriceService implements IProviderRegistry {
     throw lastError || new Error('Unknown error during fetch');
   }
 
-  private getCacheKey(request: IStockQuoteRequest): string {
-    return `${request.ticker}:${request.includeExtendedHours || false}`;
+  /**
+   * 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 | null {
+  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 +354,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 +366,8 @@ export class StockPriceService implements IProviderRegistry {
 
     this.cache.set(key, {
       price,
-      timestamp: new Date()
+      timestamp: new Date(),
+      ttl: ttl || this.cacheConfig.ttl
     });
   }
 }