@fin.cx/opendata 2.1.0 → 3.1.0

package/ts/00_commitinfo_data.ts

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

@@ -0,0 +1,404 @@
+import * as plugins from '../plugins.js';
+import type {
+  IFundamentalsProvider,
+  IFundamentalsProviderConfig,
+  IFundamentalsProviderRegistry,
+  IStockFundamentals,
+  IFundamentalsRequest
+} from './interfaces/fundamentals.js';
+
+interface IProviderEntry {
+  provider: IFundamentalsProvider;
+  config: IFundamentalsProviderConfig;
+  lastError?: Error;
+  lastErrorTime?: Date;
+  successCount: number;
+  errorCount: number;
+}
+
+interface ICacheEntry {
+  fundamentals: IStockFundamentals | IStockFundamentals[];
+  timestamp: Date;
+  ttl: number;
+}
+
+/**
+ * Service for managing fundamental data providers and caching
+ * Parallel to StockPriceService but for fundamental data instead of prices
+ */
+export class FundamentalsService implements IFundamentalsProviderRegistry {
+  private providers = new Map<string, IProviderEntry>();
+  private cache = new Map<string, ICacheEntry>();
+  private logger = console;
+
+  private cacheConfig = {
+    ttl: 90 * 24 * 60 * 60 * 1000, // 90 days default (fundamentals change quarterly)
+    maxEntries: 10000
+  };
+
+  constructor(cacheConfig?: { ttl?: number; maxEntries?: number }) {
+    if (cacheConfig) {
+      this.cacheConfig = { ...this.cacheConfig, ...cacheConfig };
+    }
+  }
+
+  /**
+   * Register a fundamentals provider
+   */
+  public register(provider: IFundamentalsProvider, config?: IFundamentalsProviderConfig): void {
+    const defaultConfig: IFundamentalsProviderConfig = {
+      enabled: true,
+      priority: provider.priority,
+      timeout: 30000, // Longer timeout for fundamental data
+      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 fundamentals provider: ${provider.name}`);
+  }
+
+  /**
+   * Unregister a provider
+   */
+  public unregister(providerName: string): void {
+    this.providers.delete(providerName);
+    console.log(`Unregistered fundamentals provider: ${providerName}`);
+  }
+
+  /**
+   * Get a specific provider by name
+   */
+  public getProvider(name: string): IFundamentalsProvider | undefined {
+    return this.providers.get(name)?.provider;
+  }
+
+  /**
+   * Get all registered providers
+   */
+  public getAllProviders(): IFundamentalsProvider[] {
+    return Array.from(this.providers.values()).map(entry => entry.provider);
+  }
+
+  /**
+   * Get enabled providers sorted by priority
+   */
+  public getEnabledProviders(): IFundamentalsProvider[] {
+    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);
+  }
+
+  /**
+   * Get fundamental data for a single ticker
+   */
+  public async getFundamentals(ticker: string): Promise<IStockFundamentals> {
+    const result = await this.getData({
+      type: 'fundamentals-current',
+      ticker
+    });
+    return result as IStockFundamentals;
+  }
+
+  /**
+   * Get fundamental data for multiple tickers
+   */
+  public async getBatchFundamentals(tickers: string[]): Promise<IStockFundamentals[]> {
+    const result = await this.getData({
+      type: 'fundamentals-batch',
+      tickers
+    });
+    return result as IStockFundamentals[];
+  }
+
+  /**
+   * Unified data fetching method
+   */
+  public async getData(
+    request: IFundamentalsRequest
+  ): Promise<IStockFundamentals | IStockFundamentals[]> {
+    const cacheKey = this.getCacheKey(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 fundamentals providers available');
+    }
+
+    let lastError: Error | undefined;
+
+    for (const provider of providers) {
+      const entry = this.providers.get(provider.name)!;
+
+      try {
+        const result = await this.fetchWithRetry(
+          () => provider.fetchData(request),
+          entry.config
+        );
+
+        entry.successCount++;
+
+        // Use provider-specific cache TTL or default
+        const ttl = entry.config.cacheTTL || this.cacheConfig.ttl;
+        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}`
+    );
+  }
+
+  /**
+   * Enrich fundamentals with calculated metrics using current price
+   */
+  public async enrichWithPrice(
+    fundamentals: IStockFundamentals,
+    price: number
+  ): Promise<IStockFundamentals> {
+    const enriched = { ...fundamentals };
+
+    // Calculate market cap: price × shares outstanding
+    if (fundamentals.sharesOutstanding) {
+      enriched.marketCap = price * fundamentals.sharesOutstanding;
+    }
+
+    // Calculate P/E ratio: price / EPS
+    if (fundamentals.earningsPerShareDiluted && fundamentals.earningsPerShareDiluted > 0) {
+      enriched.priceToEarnings = price / fundamentals.earningsPerShareDiluted;
+    }
+
+    // Calculate price-to-book: market cap / stockholders equity
+    if (enriched.marketCap && fundamentals.stockholdersEquity && fundamentals.stockholdersEquity > 0) {
+      enriched.priceToBook = enriched.marketCap / fundamentals.stockholdersEquity;
+    }
+
+    return enriched;
+  }
+
+  /**
+   * Enrich batch fundamentals with prices
+   */
+  public async enrichBatchWithPrices(
+    fundamentalsList: IStockFundamentals[],
+    priceMap: Map<string, number>
+  ): Promise<IStockFundamentals[]> {
+    return Promise.all(
+      fundamentalsList.map(fundamentals => {
+        const price = priceMap.get(fundamentals.ticker);
+        if (price) {
+          return this.enrichWithPrice(fundamentals, price);
+        }
+        return Promise.resolve(fundamentals);
+      })
+    );
+  }
+
+  /**
+   * 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('Fundamentals cache cleared');
+  }
+
+  /**
+   * Set cache TTL
+   */
+  public setCacheTTL(ttl: number): void {
+    this.cacheConfig.ttl = ttl;
+    console.log(`Fundamentals 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
+   */
+  private async fetchWithRetry<T>(
+    fetchFn: () => Promise<T>,
+    config: IFundamentalsProviderConfig
+  ): 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');
+  }
+
+  /**
+   * Generate cache key for request
+   */
+  private getCacheKey(request: IFundamentalsRequest): string {
+    switch (request.type) {
+      case 'fundamentals-current':
+        return `fundamentals:${request.ticker}`;
+      case 'fundamentals-batch':
+        const tickers = request.tickers.sort().join(',');
+        return `fundamentals-batch:${tickers}`;
+      default:
+        return `unknown:${JSON.stringify(request)}`;
+    }
+  }
+
+  /**
+   * Get from cache if not expired
+   */
+  private getFromCache(key: string): IStockFundamentals | IStockFundamentals[] | 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.fundamentals;
+  }
+
+  /**
+   * Add to cache with TTL
+   */
+  private addToCache(
+    key: string,
+    fundamentals: IStockFundamentals | IStockFundamentals[],
+    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, {
+      fundamentals,
+      timestamp: new Date(),
+      ttl: ttl || this.cacheConfig.ttl
+    });
+  }
+
+  /**
+   * Get human-readable request description
+   */
+  private getRequestDescription(request: IFundamentalsRequest): string {
+    switch (request.type) {
+      case 'fundamentals-current':
+        return `fundamentals for ${request.ticker}`;
+      case 'fundamentals-batch':
+        return `fundamentals for ${request.tickers.length} tickers`;
+      default:
+        return 'fundamentals data';
+    }
+  }
+}

package/ts/stocks/classes.stockservice.ts

@@ -2,8 +2,6 @@ import * as plugins from '../plugins.js';
 import type { IStockProvider, IProviderConfig, IProviderRegistry } from './interfaces/provider.js';
 import type {
   IStockPrice,
-  IStockQuoteRequest,
-  IStockBatchQuoteRequest,
   IStockPriceError,
   IStockDataRequest,
   IStockCurrentRequest,
@@ -13,6 +11,15 @@ import type {
   TIntervalType
 } from './interfaces/stockprice.js';
 
+// Simple request interfaces for convenience methods
+interface ISimpleQuoteRequest {
+  ticker: string;
+}
+
+interface ISimpleBatchRequest {
+  tickers: string[];
+}
+
 interface IProviderEntry {
   provider: IStockProvider;
   config: IProviderConfig;
@@ -122,132 +129,26 @@ export class StockPriceService implements IProviderRegistry {
       .map(entry => entry.provider);
   }
 
-  public async getPrice(request: IStockQuoteRequest): Promise<IStockPrice> {
-    const cacheKey = this.getCacheKey(request);
-    const cached = this.getFromCache(cacheKey) as IStockPrice | null;
-
-    if (cached) {
-      console.log(`Cache hit for ${request.ticker}`);
-      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)!;
-
-      try {
-        const price = await this.fetchWithRetry(
-          () => provider.fetchPrice(request),
-          entry.config
-        );
-
-        entry.successCount++;
-
-        // 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) {
-        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}`
-        );
-      }
-    }
-
-    throw new Error(
-      `Failed to fetch price for ${request.ticker} from all providers. Last error: ${lastError?.message}`
-    );
+  /**
+   * 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;
   }
 
-  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) as IStockPrice | null;
-
-      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 with smart TTL
-        for (const price of fetchedPrices) {
-          const cacheKey = this.getCacheKey({
-            ticker: price.ticker,
-            includeExtendedHours: request.includeExtendedHours
-          });
-          const ttl = this.getCacheTTL(price.dataType);
-          this.addToCache(cacheKey, price, ttl);
-        }
-
-        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}`
-        );
-      }
-    }
-
-    if (fetchedPrices.length === 0 && lastError) {
-      throw new Error(
-        `Failed to fetch prices from all providers. Last error: ${lastError.message}`
-      );
-    }
-
-    return [...cachedPrices, ...fetchedPrices];
+  /**
+   * 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[];
   }
 
   /**
@@ -272,15 +173,9 @@ export class StockPriceService implements IProviderRegistry {
     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),
+          () => provider.fetchData(request),
           entry.config
         ) as IStockPrice | IStockPrice[];
 
@@ -420,13 +315,6 @@ 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}`;
-  }
-
   /**
    * New cache key generation for discriminated union requests
    */

package/ts/stocks/index.ts

@@ -1,10 +1,13 @@
 // Export all interfaces
 export * from './interfaces/stockprice.js';
 export * from './interfaces/provider.js';
+export * from './interfaces/fundamentals.js';
 
-// Export main service
+// Export main services
 export * from './classes.stockservice.js';
+export * from './classes.fundamentalsservice.js';
 
 // Export providers
 export * from './providers/provider.yahoo.js';
-export * from './providers/provider.marketstack.js';
+export * from './providers/provider.marketstack.js';
+export * from './providers/provider.secedgar.js';