@fin.cx/opendata 3.1.0 → 3.2.0

package/readme.md

@@ -14,64 +14,110 @@ pnpm add @fin.cx/opendata
 
 ## Quick Start
 
-### 📈 Stock Market Data
+### ✨ Unified Stock Data API (Recommended)
 
-Get real-time prices with company information included automatically:
+Get complete stock data with automatic enrichment - the elegant way:
 
 ```typescript
-import { StockPriceService, MarketstackProvider } from '@fin.cx/opendata';
+import { StockDataService, YahooFinanceProvider, SecEdgarProvider } from '@fin.cx/opendata';
 
-// Initialize service with smart caching
-const stockService = new StockPriceService({
-  ttl: 60000,       // Cache TTL (historical cached forever)
-  maxEntries: 10000
+// Initialize unified service
+const stockData = new StockDataService();
+
+// Register providers
+stockData.registerPriceProvider(new YahooFinanceProvider());
+stockData.registerFundamentalsProvider(new SecEdgarProvider({
+  userAgent: 'YourCompany youremail@example.com'
+}));
+
+// ✨ Get complete stock data with ONE method call
+const apple = await stockData.getStockData('AAPL');
+
+console.log({
+  company: apple.fundamentals.companyName,      // "Apple Inc."
+  price: apple.price.price,                     // $270.37
+  marketCap: apple.fundamentals.marketCap,      // $4.13T (auto-calculated!)
+  peRatio: apple.fundamentals.priceToEarnings,  // 28.42 (auto-calculated!)
+  pbRatio: apple.fundamentals.priceToBook,      // 45.12 (auto-calculated!)
+  eps: apple.fundamentals.earningsPerShareDiluted,  // $6.13
+  revenue: apple.fundamentals.revenue            // $385.6B
 });
 
-// Register provider with API key
-stockService.register(new MarketstackProvider('YOUR_API_KEY'));
+// Batch fetch with automatic enrichment
+const stocks = await stockData.getBatchStockData(['AAPL', 'MSFT', 'GOOGL']);
 
-// Get current price with company name (zero extra API calls!)
-const apple = await stockService.getData({ type: 'current', ticker: 'AAPL' });
+stocks.forEach(stock => {
+  console.log(`${stock.ticker}: $${stock.price.price.toFixed(2)}, ` +
+              `P/E ${stock.fundamentals?.priceToEarnings?.toFixed(2)}`);
+});
+// Output:
+// AAPL: $270.37, P/E 28.42
+// MSFT: $425.50, P/E 34.21
+// GOOGL: $142.15, P/E 25.63
+```
+
+**Why use the unified API?**
+- ✅ **Single service** for both prices and fundamentals
+- ✅ **Automatic enrichment** - Market cap, P/E, P/B calculated automatically
+- ✅ **One method call** - No manual `enrichWithPrice()` calls
+- ✅ **Simplified code** - Less boilerplate, more readable
+- ✅ **Type-safe** - Full TypeScript support
+
+### 📈 Price-Only Data (Alternative)
 
+If you only need prices without fundamentals:
+
+```typescript
+import { StockDataService, YahooFinanceProvider } from '@fin.cx/opendata';
+
+const stockData = new StockDataService();
+stockData.registerPriceProvider(new YahooFinanceProvider());
+
+// Get just the price
+const price = await stockData.getPrice('AAPL');
+console.log(`${price.ticker}: $${price.price}`);
+
+// Or use StockPriceService directly for more control
+import { StockPriceService } from '@fin.cx/opendata';
+
+const stockService = new StockPriceService({ ttl: 60000 });
+stockService.register(new YahooFinanceProvider());
+
+const apple = await stockService.getData({ type: 'current', ticker: 'AAPL' });
 console.log(`${apple.companyFullName}: $${apple.price}`);
-// Output: "Apple Inc (NASDAQ:AAPL): $270.37"
 ```
 
-### 💰 Fundamental Financial Data
+### 💰 Fundamentals-Only Data (Alternative)
 
-Access comprehensive financial metrics from SEC filings - completely FREE:
+If you only need fundamentals without prices:
 
 ```typescript
-import { SecEdgarProvider, FundamentalsService } from '@fin.cx/opendata';
+import { StockDataService, SecEdgarProvider } from '@fin.cx/opendata';
 
-// Setup SEC EDGAR provider (no API key required!)
-const secEdgar = new SecEdgarProvider({
+const stockData = new StockDataService();
+stockData.registerFundamentalsProvider(new SecEdgarProvider({
   userAgent: 'YourCompany youremail@example.com'
-});
-
-const fundamentalsService = new FundamentalsService();
-fundamentalsService.register(secEdgar);
+}));
 
-// Fetch fundamentals for Apple
-const fundamentals = await fundamentalsService.getFundamentals('AAPL');
+// Get just fundamentals
+const fundamentals = await stockData.getFundamentals('AAPL');
 
 console.log({
-  company: fundamentals.companyName,             // "Apple Inc."
-  eps: fundamentals.earningsPerShareDiluted,    // $6.13
-  revenue: fundamentals.revenue,                 // $385.6B
-  sharesOutstanding: fundamentals.sharesOutstanding  // 15.3B
+  company: fundamentals.companyName,
+  eps: fundamentals.earningsPerShareDiluted,
+  revenue: fundamentals.revenue,
+  sharesOutstanding: fundamentals.sharesOutstanding
 });
 
-// Calculate market cap and P/E ratio
-const price = await stockService.getData({ type: 'current', ticker: 'AAPL' });
-const enriched = await fundamentalsService.enrichWithPrice(fundamentals, price.price);
+// Or use FundamentalsService directly
+import { FundamentalsService } from '@fin.cx/opendata';
 
-console.log({
-  marketCap: `$${(enriched.marketCap! / 1_000_000_000_000).toFixed(2)}T`,
-  peRatio: enriched.priceToEarnings!.toFixed(2),
-  pbRatio: enriched.priceToBook?.toFixed(2)
-});
-// Output: { marketCap: "$2.65T", peRatio: "28.42", pbRatio: "45.12" }
+const fundamentalsService = new FundamentalsService();
+fundamentalsService.register(new SecEdgarProvider({
+  userAgent: 'YourCompany youremail@example.com'
+}));
+
+const data = await fundamentalsService.getFundamentals('AAPL');
 ```
 
 ### 🏢 German Business Intelligence
@@ -136,44 +182,70 @@ const details = await openData.handelsregister.getSpecificCompany({
 
 ## Advanced Examples
 
-### Combined Market Analysis
+### Combined Market Analysis (Unified API)
 
-Combine price data with fundamentals for comprehensive analysis:
+Analyze multiple companies with automatic enrichment:
 
 ```typescript
-import { StockPriceService, MarketstackProvider, SecEdgarProvider, FundamentalsService } from '@fin.cx/opendata';
-
-// Setup services
-const stockService = new StockPriceService({ ttl: 60000 });
-stockService.register(new MarketstackProvider('YOUR_API_KEY'));
+import { StockDataService, YahooFinanceProvider, SecEdgarProvider } from '@fin.cx/opendata';
 
-const fundamentalsService = new FundamentalsService();
-fundamentalsService.register(new SecEdgarProvider({
+// Setup unified service
+const stockData = new StockDataService();
+stockData.registerPriceProvider(new YahooFinanceProvider());
+stockData.registerFundamentalsProvider(new SecEdgarProvider({
   userAgent: 'YourCompany youremail@example.com'
 }));
 
-// Analyze multiple companies
+// Analyze multiple companies with ONE call
 const tickers = ['AAPL', 'MSFT', 'GOOGL', 'AMZN'];
+const stocks = await stockData.getBatchStockData(tickers);
+
+// All metrics are automatically calculated!
+stocks.forEach(stock => {
+  if (stock.fundamentals) {
+    console.log(`\n${stock.fundamentals.companyName} (${stock.ticker})`);
+    console.log(`  Price: $${stock.price.price.toFixed(2)}`);
+    console.log(`  Market Cap: $${(stock.fundamentals.marketCap! / 1e9).toFixed(2)}B`);
+    console.log(`  P/E Ratio: ${stock.fundamentals.priceToEarnings!.toFixed(2)}`);
+    console.log(`  Revenue: $${(stock.fundamentals.revenue! / 1e9).toFixed(2)}B`);
+    console.log(`  EPS: $${stock.fundamentals.earningsPerShareDiluted!.toFixed(2)}`);
+  }
+});
 
+// Or analyze one-by-one with automatic enrichment
 for (const ticker of tickers) {
-  // Get price and fundamentals in parallel
-  const [price, fundamentals] = await Promise.all([
-    stockService.getData({ type: 'current', ticker }),
-    fundamentalsService.getFundamentals(ticker)
-  ]);
-
-  // Calculate metrics
-  const enriched = await fundamentalsService.enrichWithPrice(fundamentals, price.price);
-
-  console.log(`\n${fundamentals.companyName} (${ticker})`);
-  console.log(`  Price: $${price.price.toFixed(2)}`);
-  console.log(`  Market Cap: $${(enriched.marketCap! / 1e9).toFixed(2)}B`);
-  console.log(`  P/E Ratio: ${enriched.priceToEarnings!.toFixed(2)}`);
-  console.log(`  Revenue: $${(fundamentals.revenue! / 1e9).toFixed(2)}B`);
-  console.log(`  EPS: $${fundamentals.earningsPerShareDiluted!.toFixed(2)}`);
+  const stock = await stockData.getStockData(ticker);
+
+  // Everything is already enriched - no manual calculations needed!
+  console.log(`${ticker}: P/E ${stock.fundamentals?.priceToEarnings?.toFixed(2)}`);
 }
 ```
 
+### Fundamental Data Screening
+
+Screen stocks by financial metrics:
+
+```typescript
+// Fetch data for multiple tickers
+const tickers = ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'META', 'NVDA', 'TSLA'];
+const stocks = await stockData.getBatchStockData(tickers);
+
+// Filter by criteria (all metrics auto-calculated!)
+const valueStocks = stocks.filter(stock => {
+  const f = stock.fundamentals;
+  return f &&
+    f.priceToEarnings! < 30 &&          // P/E under 30
+    f.priceToBook! < 10 &&              // P/B under 10
+    f.revenue! > 100_000_000_000;       // Revenue > $100B
+});
+
+console.log('\n💎 Value Stocks:');
+valueStocks.forEach(stock => {
+  console.log(`${stock.ticker}: P/E ${stock.fundamentals!.priceToEarnings!.toFixed(2)}, ` +
+              `P/B ${stock.fundamentals!.priceToBook!.toFixed(2)}`);
+});
+```
+
 ### Historical Data Analysis
 
 Fetch and analyze historical price trends:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '3.1.0',
+  version: '3.2.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.baseproviderservice.ts

@@ -0,0 +1,296 @@
+import * as plugins from '../plugins.js';
+
+/**
+ * Base provider entry for tracking provider state
+ */
+export interface IBaseProviderEntry<TProvider> {
+  provider: TProvider;
+  config: IBaseProviderConfig;
+  lastError?: Error;
+  lastErrorTime?: Date;
+  successCount: number;
+  errorCount: number;
+}
+
+/**
+ * Base provider configuration
+ */
+export interface IBaseProviderConfig {
+  enabled: boolean;
+  priority: number;
+  timeout?: number;
+  retryAttempts?: number;
+  retryDelay?: number;
+  cacheTTL?: number;
+}
+
+/**
+ * Base provider interface
+ */
+export interface IBaseProvider {
+  name: string;
+  priority: number;
+  isAvailable(): Promise<boolean>;
+  readonly requiresAuth: boolean;
+  readonly rateLimit?: {
+    requestsPerMinute: number;
+    requestsPerDay?: number;
+  };
+}
+
+/**
+ * Cache entry for any data type
+ */
+export interface IBaseCacheEntry<TData> {
+  data: TData;
+  timestamp: Date;
+  ttl: number;
+}
+
+/**
+ * Base service for managing data providers with caching
+ * Shared logic extracted from StockPriceService and FundamentalsService
+ */
+export abstract class BaseProviderService<TProvider extends IBaseProvider, TData> {
+  protected providers = new Map<string, IBaseProviderEntry<TProvider>>();
+  protected cache = new Map<string, IBaseCacheEntry<TData>>();
+  protected logger = console;
+
+  protected cacheConfig = {
+    ttl: 60000, // Default 60 seconds
+    maxEntries: 10000
+  };
+
+  constructor(cacheConfig?: { ttl?: number; maxEntries?: number }) {
+    if (cacheConfig) {
+      this.cacheConfig = { ...this.cacheConfig, ...cacheConfig };
+    }
+  }
+
+  /**
+   * Register a provider
+   */
+  public register(provider: TProvider, config?: Partial<IBaseProviderConfig>): void {
+    const defaultConfig: IBaseProviderConfig = {
+      enabled: true,
+      priority: provider.priority,
+      timeout: 30000,
+      retryAttempts: 2,
+      retryDelay: 1000,
+      cacheTTL: this.cacheConfig.ttl
+    };
+
+    const mergedConfig = { ...defaultConfig, ...config };
+
+    this.providers.set(provider.name, {
+      provider,
+      config: mergedConfig,
+      successCount: 0,
+      errorCount: 0
+    });
+
+    console.log(`Registered provider: ${provider.name}`);
+  }
+
+  /**
+   * Unregister a provider
+   */
+  public unregister(providerName: string): void {
+    this.providers.delete(providerName);
+    console.log(`Unregistered provider: ${providerName}`);
+  }
+
+  /**
+   * Get a specific provider by name
+   */
+  public getProvider(name: string): TProvider | undefined {
+    return this.providers.get(name)?.provider;
+  }
+
+  /**
+   * Get all registered providers
+   */
+  public getAllProviders(): TProvider[] {
+    return Array.from(this.providers.values()).map(entry => entry.provider);
+  }
+
+  /**
+   * Get enabled providers sorted by priority
+   */
+  public getEnabledProviders(): TProvider[] {
+    return Array.from(this.providers.values())
+      .filter(entry => entry.config.enabled)
+      .sort((a, b) => (b.config.priority || 0) - (a.config.priority || 0))
+      .map(entry => entry.provider);
+  }
+
+  /**
+   * Check health of all providers
+   */
+  public async checkProvidersHealth(): Promise<Map<string, boolean>> {
+    const health = new Map<string, boolean>();
+
+    for (const [name, entry] of this.providers) {
+      if (!entry.config.enabled) {
+        health.set(name, false);
+        continue;
+      }
+
+      try {
+        const isAvailable = await entry.provider.isAvailable();
+        health.set(name, isAvailable);
+      } catch (error) {
+        health.set(name, false);
+        console.error(`Health check failed for ${name}:`, error);
+      }
+    }
+
+    return health;
+  }
+
+  /**
+   * Get provider statistics
+   */
+  public getProviderStats(): Map<
+    string,
+    {
+      successCount: number;
+      errorCount: number;
+      lastError?: string;
+      lastErrorTime?: Date;
+    }
+  > {
+    const stats = new Map();
+
+    for (const [name, entry] of this.providers) {
+      stats.set(name, {
+        successCount: entry.successCount,
+        errorCount: entry.errorCount,
+        lastError: entry.lastError?.message,
+        lastErrorTime: entry.lastErrorTime
+      });
+    }
+
+    return stats;
+  }
+
+  /**
+   * Clear all cached data
+   */
+  public clearCache(): void {
+    this.cache.clear();
+    console.log('Cache cleared');
+  }
+
+  /**
+   * Set cache TTL
+   */
+  public setCacheTTL(ttl: number): void {
+    this.cacheConfig.ttl = ttl;
+    console.log(`Cache TTL set to ${ttl}ms`);
+  }
+
+  /**
+   * Get cache statistics
+   */
+  public getCacheStats(): {
+    size: number;
+    maxEntries: number;
+    ttl: number;
+  } {
+    return {
+      size: this.cache.size,
+      maxEntries: this.cacheConfig.maxEntries,
+      ttl: this.cacheConfig.ttl
+    };
+  }
+
+  /**
+   * Fetch with retry logic
+   */
+  protected async fetchWithRetry<T>(
+    fetchFn: () => Promise<T>,
+    config: IBaseProviderConfig
+  ): Promise<T> {
+    const maxAttempts = config.retryAttempts || 1;
+    let lastError: Error | undefined;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await fetchFn();
+      } catch (error) {
+        lastError = error as Error;
+
+        if (attempt < maxAttempts) {
+          const delay = (config.retryDelay || 1000) * attempt;
+          console.log(`Retry attempt ${attempt} after ${delay}ms`);
+          await plugins.smartdelay.delayFor(delay);
+        }
+      }
+    }
+
+    throw lastError || new Error('Unknown error during fetch');
+  }
+
+  /**
+   * Get from cache if not expired
+   */
+  protected getFromCache(key: string): TData | 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 (entry.ttl !== Infinity && age > entry.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return entry.data;
+  }
+
+  /**
+   * Add to cache with TTL
+   */
+  protected addToCache(key: string, data: TData, ttl?: number): void {
+    // Enforce max entries limit
+    if (this.cache.size >= this.cacheConfig.maxEntries) {
+      // Remove oldest entry
+      const oldestKey = this.cache.keys().next().value;
+      if (oldestKey) {
+        this.cache.delete(oldestKey);
+      }
+    }
+
+    this.cache.set(key, {
+      data,
+      timestamp: new Date(),
+      ttl: ttl || this.cacheConfig.ttl
+    });
+  }
+
+  /**
+   * Track successful fetch for provider
+   */
+  protected trackSuccess(providerName: string): void {
+    const entry = this.providers.get(providerName);
+    if (entry) {
+      entry.successCount++;
+    }
+  }
+
+  /**
+   * Track failed fetch for provider
+   */
+  protected trackError(providerName: string, error: Error): void {
+    const entry = this.providers.get(providerName);
+    if (entry) {
+      entry.errorCount++;
+      entry.lastError = error;
+      entry.lastErrorTime = new Date();
+    }
+  }
+}