@fin.cx/opendata 3.0.0 → 3.2.0

package/readme.md

@@ -1,154 +1,134 @@
 # @fin.cx/opendata
 
-🚀 **Real-time financial data and German business intelligence in one powerful TypeScript library**
+🚀 **Complete financial intelligence toolkit for TypeScript**
 
-Access live stock prices, cryptocurrencies, forex, commodities AND comprehensive German company data - all through a single, unified API.
+Access real-time stock prices, fundamental financial data, and comprehensive German company information - all through a single, unified API.
 
-## ⚠️ Breaking Changes
-
-### v2.1 - Enhanced Stock Market API (Current)
+## Installation
 
-**The stock market API has been significantly enhanced with a new unified request system.**
+```bash
+npm install @fin.cx/opendata
+# or
+pnpm add @fin.cx/opendata
+```
 
-**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
+## Quick Start
 
-**Migration:**
-```typescript
-// OLD (v2.0 and earlier)
-const price = await service.getPrice({ ticker: 'AAPL' });
-const prices = await service.getPrices({ tickers: ['AAPL', 'MSFT'] });
+### ✨ Unified Stock Data API (Recommended)
 
-// NEW (v2.1+) - Unified API
-const price = await service.getData({ type: 'current', ticker: 'AAPL' });
-const prices = await service.getData({ type: 'batch', tickers: ['AAPL', 'MSFT'] });
+Get complete stock data with automatic enrichment - the elegant way:
 
-// NEW - Historical data
-const history = await service.getData({
-  type: 'historical',
-  ticker: 'AAPL',
-  from: new Date('2024-01-01'),
-  to: new Date('2024-12-31')
+```typescript
+import { StockDataService, YahooFinanceProvider, SecEdgarProvider } from '@fin.cx/opendata';
+
+// 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
 });
 
-// NEW - Exchange filtering
-const price = await service.getData({
-  type: 'current',
-  ticker: 'VOD',
-  exchange: 'XLON' // London Stock Exchange
+// Batch fetch with automatic enrichment
+const stocks = await stockData.getBatchStockData(['AAPL', 'MSFT', 'GOOGL']);
+
+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
 ```
 
-**Note:** Legacy `getPrice()` and `getPrices()` methods still work but are deprecated.
+**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
 
-### v2.0 - Directory Configuration
+### 📈 Price-Only Data (Alternative)
 
-**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`:
+If you only need prices without fundamentals:
 
 ```typescript
-const openData = new OpenData({
-  nogitDir: '/path/to/your/data',
-  downloadDir: '/path/to/your/data/downloads',
-  germanBusinessDataDir: '/path/to/your/data/germanbusinessdata'
-});
-```
+import { StockDataService, YahooFinanceProvider } from '@fin.cx/opendata';
 
-This change enables the package to work in read-only filesystems (like Deno compiled binaries) and gives you full control over where data is stored.
+const stockData = new StockDataService();
+stockData.registerPriceProvider(new YahooFinanceProvider());
 
-## Installation
+// Get just the price
+const price = await stockData.getPrice('AAPL');
+console.log(`${price.ticker}: $${price.price}`);
 
-```bash
-npm install @fin.cx/opendata
-# or
-pnpm add @fin.cx/opendata
-```
+// Or use StockPriceService directly for more control
+import { StockPriceService } from '@fin.cx/opendata';
 
-## Quick Start
-
-### 📈 Stock Market Data (v2.1+ Enhanced)
+const stockService = new StockPriceService({ ttl: 60000 });
+stockService.register(new YahooFinanceProvider());
 
-Get comprehensive market data with EOD, historical, and OHLCV data:
-
-```typescript
-import { StockPriceService, MarketstackProvider } from '@fin.cx/opendata';
+const apple = await stockService.getData({ type: 'current', ticker: 'AAPL' });
+console.log(`${apple.companyFullName}: $${apple.price}`);
+```
 
-// Initialize the service with smart caching
-const stockService = new StockPriceService({
-  ttl: 60000,       // Default cache TTL (historical data cached forever)
-  maxEntries: 10000  // Increased for historical data
-});
+### 💰 Fundamentals-Only Data (Alternative)
 
-// Register Marketstack provider with API key
-stockService.register(new MarketstackProvider('YOUR_API_KEY'), {
-  priority: 100,
-  retryAttempts: 3
-});
+If you only need fundamentals without prices:
 
-// 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)"
+```typescript
+import { StockDataService, SecEdgarProvider } from '@fin.cx/opendata';
 
-// 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`);
+const stockData = new StockDataService();
+stockData.registerFundamentalsProvider(new SecEdgarProvider({
+  userAgent: 'YourCompany youremail@example.com'
+}));
 
-// Exchange-specific data (London vs NYSE)
-const vodLondon = await stockService.getData({
-  type: 'current',
-  ticker: 'VOD',
-  exchange: 'XLON' // London Stock Exchange
-});
+// Get just fundamentals
+const fundamentals = await stockData.getFundamentals('AAPL');
 
-const vodNYSE = await stockService.getData({
-  type: 'current',
-  ticker: 'VOD',
-  exchange: 'XNYS' // New York Stock Exchange
+console.log({
+  company: fundamentals.companyName,
+  eps: fundamentals.earningsPerShareDiluted,
+  revenue: fundamentals.revenue,
+  sharesOutstanding: fundamentals.sharesOutstanding
 });
 
-// Batch current prices with company names
-const prices = await stockService.getData({
-  type: 'batch',
-  tickers: ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA']
-});
+// Or use FundamentalsService directly
+import { FundamentalsService } from '@fin.cx/opendata';
 
-// 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
-}
+const fundamentalsService = new FundamentalsService();
+fundamentalsService.register(new SecEdgarProvider({
+  userAgent: 'YourCompany youremail@example.com'
+}));
 
-// Use companyFullName for richer context
-console.log(prices[0].companyFullName); // "Apple Inc (NASDAQ:AAPL)"
+const data = await fundamentalsService.getFundamentals('AAPL');
 ```
 
-### 🏢 German Business Data
+### 🏢 German Business Intelligence
 
-Access comprehensive data on German companies:
+Access comprehensive German company data:
 
 ```typescript
 import { OpenData } from '@fin.cx/opendata';
 import * as path from 'path';
 
-// REQUIRED: Configure directory paths
+// Configure directory paths
 const openData = new OpenData({
   nogitDir: path.join(process.cwd(), '.nogit'),
   downloadDir: path.join(process.cwd(), '.nogit', 'downloads'),
@@ -156,55 +136,119 @@ const openData = new OpenData({
 });
 await openData.start();
 
-// Create a business record
-const company = new openData.CBusinessRecord();
-company.data = {
-  name: "TechStart GmbH",
-  city: "Berlin",
-  registrationId: "HRB 123456",
-  // ... more fields
-};
-await company.save();
-
-// Search companies by city
-const berlinCompanies = await openData.db
-  .collection('businessrecords')
-  .find({ city: "Berlin" })
-  .toArray();
+// Search for companies
+const results = await openData.handelsregister.searchCompany("Siemens AG");
 
-// Import bulk data from official sources
-await openData.buildInitialDb();
+// Get detailed information with documents
+const details = await openData.handelsregister.getSpecificCompany({
+  court: "Munich",
+  type: "HRB",
+  number: "6684"
+});
 ```
 
 ## Features
 
-### 🎯 Stock Market Module (v2.1 Enhanced)
+### 📊 Stock Market Module
 
-- **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
+- **Real-Time Prices** - Live and EOD stock prices from Yahoo Finance and Marketstack
+- **Company Names** - Automatic company name extraction (e.g., "Apple Inc (NASDAQ:AAPL)")
+- **Historical Data** - Up to 15 years of daily EOD prices with pagination
+- **OHLCV Data** - Open, High, Low, Close, Volume for technical analysis
+- **Exchange Filtering** - Query specific exchanges via MIC codes (XNAS, XLON, XNYS)
 - **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
+- **Type-Safe API** - Full TypeScript support with discriminated unions
+- **Multi-Provider** - Automatic fallback between providers
+
+### 💰 Fundamental Data Module
+
+- **SEC EDGAR Integration** - FREE fundamental data directly from SEC filings
+- **Comprehensive Metrics** - EPS, Revenue, Assets, Liabilities, Cash Flow, and more
+- **All US Public Companies** - Complete coverage of SEC-registered companies
+- **Historical Filings** - Data back to ~2009
+- **CIK Lookup** - Automatic ticker-to-CIK mapping with smart caching
+- **Calculated Ratios** - Market Cap, P/E, P/B ratios when combined with prices
+- **No API Key Required** - Direct access to SEC's public API
+- **Rate Limit Management** - Built-in 10 req/sec rate limiting
 
 ### 🇩🇪 German Business Intelligence
 
-- **MongoDB integration** for scalable data storage
-- **Bulk JSONL import** from official German data sources
-- **Handelsregister automation** - automated document retrieval
-- **CRUD operations** with validation
-- **Streaming processing** for multi-GB datasets
+- **MongoDB Integration** - Scalable data storage for millions of records
+- **Bulk JSONL Import** - Process multi-GB datasets efficiently
+- **Handelsregister Automation** - Automated document retrieval
+- **CRUD Operations** - Full database management with validation
+- **Streaming Processing** - Handle large datasets without memory issues
 
 ## Advanced Examples
 
-### Phase 1: Historical Data Analysis
+### Combined Market Analysis (Unified API)
 
-Fetch and analyze historical price data:
+Analyze multiple companies with automatic enrichment:
+
+```typescript
+import { StockDataService, YahooFinanceProvider, SecEdgarProvider } from '@fin.cx/opendata';
+
+// Setup unified service
+const stockData = new StockDataService();
+stockData.registerPriceProvider(new YahooFinanceProvider());
+stockData.registerFundamentalsProvider(new SecEdgarProvider({
+  userAgent: 'YourCompany youremail@example.com'
+}));
+
+// 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) {
+  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:
 
 ```typescript
 // Get 1 year of historical data
@@ -213,7 +257,7 @@ const history = await stockService.getData({
   ticker: 'AAPL',
   from: new Date('2024-01-01'),
   to: new Date('2024-12-31'),
-  sort: 'DESC' // Newest first (default)
+  sort: 'DESC' // Newest first
 });
 
 // Calculate statistics
@@ -223,50 +267,31 @@ 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:
+console.log(`  High:    $${high52Week.toFixed(2)}`);
+console.log(`  Low:     $${low52Week.toFixed(2)}`);
+console.log(`  Average: $${avgPrice.toFixed(2)}`);
+console.log(`  Days:    ${history.length}`);
 
-```typescript
-// Vodafone trades on both London and NYSE
-const exchanges = [
-  { mic: 'XLON', name: 'London Stock Exchange' },
-  { mic: 'XNYS', name: 'New York Stock Exchange' }
-];
+// Calculate Simple Moving Average
+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;
+};
 
-for (const exchange of exchanges) {
-  try {
-    const price = await stockService.getData({
-      type: 'current',
-      ticker: 'VOD',
-      exchange: exchange.mic
-    });
+const sma20 = calculateSMA(history, 20);
+const sma50 = calculateSMA(history, 50);
 
-    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`);
-  }
-}
+console.log(`\nMoving Averages:`);
+console.log(`  20-day SMA: $${sma20[0].toFixed(2)}`);
+console.log(`  50-day SMA: $${sma50[0].toFixed(2)}`);
 ```
 
-### Phase 1: OHLCV Technical Analysis
+### OHLCV Technical Analysis
 
 Use OHLCV data for technical indicators:
 
@@ -280,8 +305,8 @@ const history = await stockService.getData({
 
 // Calculate daily trading range
 for (const day of history) {
-  const range = day.high - day.low;
-  const rangePercent = (range / day.low) * 100;
+  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}`);
@@ -291,73 +316,54 @@ for (const day of history) {
   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
+### Fundamental Data Screening
 
-Leverage smart caching for efficiency:
+Screen stocks based on fundamental metrics:
 
 ```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
+const tickers = ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA', 'META', 'NVDA'];
 
-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!)
+// Fetch fundamentals for all tickers
+const allFundamentals = await fundamentalsService.getBatchFundamentals(tickers);
 
-// EOD data cached for 24 hours
-const currentPrice = await stockService.getData({
-  type: 'current',
-  ticker: 'MSFT'
+// Get current prices
+const prices = await stockService.getData({
+  type: 'batch',
+  tickers: tickers
 });
-// Subsequent calls within 24h served from cache
 
-// Cache statistics
-console.log(`Cache size: ${stockService['cache'].size} entries`);
+// Create price map
+const priceMap = new Map(prices.map(p => [p.ticker, p.price]));
+
+// Enrich with prices
+const enriched = await fundamentalsService.enrichBatchWithPrices(
+  allFundamentals,
+  priceMap
+);
+
+// Screen for value stocks (P/E < 25, P/B < 5)
+const valueStocks = enriched.filter(f =>
+  f.priceToEarnings && f.priceToEarnings < 25 &&
+  f.priceToBook && f.priceToBook < 5
+);
+
+console.log('Value Stocks:');
+valueStocks.forEach(stock => {
+  console.log(`\n${stock.companyName} (${stock.ticker})`);
+  console.log(`  P/E Ratio: ${stock.priceToEarnings!.toFixed(2)}`);
+  console.log(`  P/B Ratio: ${stock.priceToBook!.toFixed(2)}`);
+  console.log(`  Market Cap: $${(stock.marketCap! / 1e9).toFixed(2)}B`);
+});
 ```
 
 ### Market Dashboard
 
-Create an EOD market overview:
+Create a comprehensive market overview:
 
 ```typescript
 const indicators = [
-  // Indices
-  { ticker: '^GSPC', name: 'S&P 500' },
-  { ticker: '^DJI', name: 'DOW Jones' },
-
-  // Tech Giants
   { ticker: 'AAPL', name: 'Apple' },
   { ticker: 'MSFT', name: 'Microsoft' },
   { ticker: 'GOOGL', name: 'Alphabet' },
@@ -365,7 +371,8 @@ const indicators = [
   { ticker: 'TSLA', name: 'Tesla' }
 ];
 
-const prices = await stockService.getPrices({
+const prices = await stockService.getData({
+  type: 'batch',
   tickers: indicators.map(i => i.ticker)
 });
 
@@ -376,197 +383,125 @@ prices.forEach(price => {
   const color = price.change >= 0 ? '\x1b[32m' : '\x1b[31m';
 
   console.log(
-    `${indicator.name.padEnd(15)} ${price.price.toFixed(2).padStart(10)} ` +
+    `${price.companyName!.padEnd(25)} $${price.price.toFixed(2).padStart(8)} ` +
     `${color}${arrow} ${price.changePercent.toFixed(2)}%\x1b[0m`
   );
 });
 ```
 
-### Provider Health and Statistics
+### Exchange-Specific Trading
 
-Monitor your provider health and track usage:
+Compare prices across different exchanges:
 
 ```typescript
-// Check provider health
-const health = await stockService.checkProvidersHealth();
-console.log(`Marketstack: ${health.get('Marketstack') ? '✅' : '❌'}`);
-
-// Get provider statistics
-const stats = stockService.getProviderStats();
-const marketstackStats = stats.get('Marketstack');
-console.log('Marketstack Stats:', {
-  successCount: marketstackStats.successCount,
-  errorCount: marketstackStats.errorCount,
-  lastError: marketstackStats.lastError
-});
+// 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`);
+  }
+}
 ```
 
-### Handelsregister Integration
+## Configuration
 
-Automate German company data retrieval:
+### Stock Service Options
 
 ```typescript
-import { OpenData } from '@fin.cx/opendata';
-import * as path from 'path';
-
-// Configure paths first
-const openData = new OpenData({
-  nogitDir: path.join(process.cwd(), '.nogit'),
-  downloadDir: path.join(process.cwd(), '.nogit', 'downloads'),
-  germanBusinessDataDir: path.join(process.cwd(), '.nogit', 'germanbusinessdata')
+const stockService = new StockPriceService({
+  ttl: 60000,         // Default cache TTL in ms
+  maxEntries: 10000   // Max cached entries
 });
-await openData.start();
-
-// Search for a company
-const results = await openData.handelsregister.searchCompany("Siemens AG");
 
-// Get detailed information and documents
-const details = await openData.handelsregister.getSpecificCompany({
-  court: "Munich",
-  type: "HRB",
-  number: "6684"
+// Marketstack - EOD data (requires API key)
+stockService.register(new MarketstackProvider('YOUR_API_KEY'), {
+  enabled: true,
+  priority: 100,
+  timeout: 10000,
+  retryAttempts: 3,
+  retryDelay: 1000
 });
 
-// Downloaded files include:
-// - XML data (SI files)
-// - PDF documents (AD files)
-for (const file of details.files) {
-  await file.writeToDir('./downloads');
-}
+// Yahoo Finance - Real-time data (no API key)
+stockService.register(new YahooFinanceProvider(), {
+  enabled: true,
+  priority: 50
+});
 ```
 
-### Combined Data Analysis
-
-Merge financial and business data:
+### Fundamentals Service Options
 
 ```typescript
-import { OpenData, StockPriceService, MarketstackProvider } from '@fin.cx/opendata';
-import * as path from 'path';
-
-// Configure OpenData with paths
-const openData = new OpenData({
-  nogitDir: path.join(process.cwd(), '.nogit'),
-  downloadDir: path.join(process.cwd(), '.nogit', 'downloads'),
-  germanBusinessDataDir: path.join(process.cwd(), '.nogit', 'germanbusinessdata')
+const fundamentalsService = new FundamentalsService({
+  ttl: 90 * 24 * 60 * 60 * 1000,  // 90 days (quarterly refresh)
+  maxEntries: 10000
 });
-await openData.start();
-
-// Setup stock service
-const stockService = new StockPriceService({ ttl: 60000, maxEntries: 1000 });
-stockService.register(new MarketstackProvider('YOUR_API_KEY'));
-
-// Find all public German companies (AG)
-const publicCompanies = await openData.db
-  .collection('businessrecords')
-  .find({ legalForm: 'AG' })
-  .toArray();
-
-// Enrich with stock data
-for (const company of publicCompanies) {
-  try {
-    // Map company to ticker (custom logic needed)
-    const ticker = mapCompanyToTicker(company.data.name);
-
-    if (ticker) {
-      const stock = await stockService.getPrice({ ticker });
 
-      // Add financial metrics
-      company.data.stockPrice = stock.price;
-      company.data.marketCap = stock.price * getSharesOutstanding(ticker);
-      company.data.priceChange = stock.changePercent;
-
-      await company.save();
-    }
-  } catch (error) {
-    // Handle missing tickers gracefully
-  }
-}
+// SEC EDGAR provider (FREE - no API key!)
+fundamentalsService.register(new SecEdgarProvider({
+  userAgent: 'YourCompany youremail@example.com',
+  cikCacheTTL: 30 * 24 * 60 * 60 * 1000,      // 30 days
+  fundamentalsCacheTTL: 90 * 24 * 60 * 60 * 1000,  // 90 days
+  timeout: 30000
+}));
 ```
 
-## Configuration
-
-### Directory Configuration (Required for German Business Data)
+### Directory Configuration (German Business Data)
 
-**All directory paths are mandatory when using `OpenData`.** Here are examples for different environments:
+All directory paths are mandatory when using German business data features:
 
-#### Development Environment
 ```typescript
 import { OpenData } from '@fin.cx/opendata';
 import * as path from 'path';
 
+// Development
 const openData = new OpenData({
   nogitDir: path.join(process.cwd(), '.nogit'),
   downloadDir: path.join(process.cwd(), '.nogit', 'downloads'),
   germanBusinessDataDir: path.join(process.cwd(), '.nogit', 'germanbusinessdata')
 });
-```
 
-#### Production Environment
-```typescript
-import { OpenData } from '@fin.cx/opendata';
-import * as path from 'path';
-
-const openData = new OpenData({
+// Production
+const openDataProd = new OpenData({
   nogitDir: '/var/lib/myapp/data',
   downloadDir: '/var/lib/myapp/data/downloads',
   germanBusinessDataDir: '/var/lib/myapp/data/germanbusinessdata'
 });
 ```
 
-#### Deno Compiled Binaries (or other read-only filesystems)
-```typescript
-import { OpenData } from '@fin.cx/opendata';
-
-// Use OS temp directory or user data directory
-const dataDir = Deno.env.get('HOME') + '/.myapp/data';
-
-const openData = new OpenData({
-  nogitDir: dataDir,
-  downloadDir: dataDir + '/downloads',
-  germanBusinessDataDir: dataDir + '/germanbusinessdata'
-});
-```
-
-### Stock Service Options
-
-```typescript
-const stockService = new StockPriceService({
-  ttl: 60000,         // Cache for 1 minute
-  maxEntries: 1000    // Max cached symbols
-});
-
-// Marketstack - EOD data, requires API key
-stockService.register(new MarketstackProvider('YOUR_API_KEY'), {
-  enabled: true,
-  priority: 100,
-  timeout: 10000,
-  retryAttempts: 3,
-  retryDelay: 1000
-});
-```
-
-### MongoDB Setup
+### Environment Variables
 
-Set environment variables for German business data:
+Set environment variables for API keys and database:
 
 ```env
+# Marketstack API (for EOD stock data)
+MARKETSTACK_COM_TOKEN=your_api_key_here
+
+# MongoDB (for German business data)
 MONGODB_URL=mongodb://localhost:27017
 MONGODB_NAME=opendata
 MONGODB_USER=myuser
 MONGODB_PASS=mypass
 ```
 
-### Marketstack API Key
-
-Get your free API key at [marketstack.com](https://marketstack.com) and set it in your environment:
-
-```env
-MARKETSTACK_COM_TOKEN=your_api_key_here
-```
-
 ## API Reference
 
-### Stock Types
+### Stock Price Interfaces
 
 ```typescript
 interface IStockPrice {
@@ -581,62 +516,154 @@ interface IStockPrice {
   marketState: 'PRE' | 'REGULAR' | 'POST' | 'CLOSED';
   exchange?: string;
   exchangeName?: string;
+
+  // OHLCV data
+  volume?: number;
+  open?: number;
+  high?: number;
+  low?: number;
+  adjusted?: boolean;
+  dataType: 'eod' | 'intraday' | 'live';
+  fetchedAt: Date;
+
+  // Company identification
+  companyName?: string;       // "Apple Inc"
+  companyFullName?: string;   // "Apple Inc (NASDAQ:AAPL)"
+}
+```
+
+### Fundamental Data Interfaces
+
+```typescript
+interface IStockFundamentals {
+  ticker: string;
+  cik: string;
+  companyName: string;
+  provider: string;
+  timestamp: Date;
+  fetchedAt: Date;
+
+  // Per-share metrics
+  earningsPerShareBasic?: number;
+  earningsPerShareDiluted?: number;
+  sharesOutstanding?: number;
+
+  // Income statement (annual USD)
+  revenue?: number;
+  netIncome?: number;
+  operatingIncome?: number;
+  grossProfit?: number;
+
+  // Balance sheet (annual USD)
+  assets?: number;
+  liabilities?: number;
+  stockholdersEquity?: number;
+  cash?: number;
+  propertyPlantEquipment?: number;
+
+  // Calculated metrics (requires price)
+  marketCap?: number;        // price × sharesOutstanding
+  priceToEarnings?: number;  // price / EPS
+  priceToBook?: number;      // marketCap / stockholdersEquity
+
+  // Metadata
+  fiscalYear?: string;
+  fiscalQuarter?: string;
+  filingDate?: Date;
+  form?: '10-K' | '10-Q' | string;
 }
 ```
 
 ### Key Methods
 
 **StockPriceService**
-- `getPrice(request)` - Single stock price with automatic provider selection
-- `getPrices(request)` - Batch prices (100+ symbols in one request)
+- `getData(request)` - Unified method for all stock data (current, historical, batch)
+- `getPrice(request)` - Convenience method for single current price
+- `getPrices(request)` - Convenience method for batch current prices
 - `register(provider, config)` - Add data provider with priority and retry config
 - `checkProvidersHealth()` - Test all providers and return health status
 - `getProviderStats()` - Get success/error statistics for each provider
 - `clearCache()` - Clear price cache
 - `setCacheTTL(ttl)` - Update cache TTL dynamically
 
+**FundamentalsService**
+- `getFundamentals(ticker)` - Get fundamental data for single ticker
+- `getBatchFundamentals(tickers)` - Get fundamentals for multiple tickers
+- `enrichWithPrice(fundamentals, price)` - Calculate market cap, P/E, P/B ratios
+- `enrichBatchWithPrices(fundamentals, priceMap)` - Batch enrich with prices
+- `register(provider, config)` - Add fundamentals provider
+- `checkProvidersHealth()` - Test all providers
+- `getProviderStats()` - Get success/error statistics
+- `clearCache()` - Clear fundamentals cache
+
+**SecEdgarProvider**
+- ✅ FREE - No API key required
+- ✅ All US public companies
+- ✅ Comprehensive US GAAP financial metrics
+- ✅ Historical data back to ~2009
+- ✅ Direct access to SEC filings (10-K, 10-Q)
+- ✅ Smart caching (CIK: 30 days, Fundamentals: 90 days)
+- ✅ Rate limiting (10 requests/second)
+- ℹ️ Requires User-Agent header in format: "Company Name Email"
+
 **MarketstackProvider**
-- ✅ End-of-Day (EOD) data
-- ✅ 125,000+ tickers across 72+ exchanges worldwide
-- ✅ Batch fetching support (multiple symbols in one request)
-- ✅ Comprehensive data: open, high, low, close, volume, splits, dividends
+- ✅ End-of-Day (EOD) stock prices
+- ✅ 500,000+ tickers across 72+ exchanges worldwide
+- ✅ Historical data with pagination
+- ✅ Batch fetching support
+- ✅ OHLCV data (Open, High, Low, Close, Volume)
+- ✅ Company names included automatically
 - ⚠️ Requires API key (free tier: 100 requests/month)
-- ⚠️ EOD data only (not real-time)
+
+**YahooFinanceProvider**
+- ✅ Real-time stock prices
+- ✅ No API key required
+- ✅ Global coverage
+- ✅ Company names included
+- ⚠️ Rate limits may apply
 
 **OpenData**
 - `start()` - Initialize MongoDB connection
 - `buildInitialDb()` - Import bulk data
 - `CBusinessRecord` - Business record class
-- `handelsregister` - Registry automation
+- `handelsregister` - German registry automation
 
 ## Provider Architecture
 
-The library uses a flexible provider system that makes it easy to add new data sources:
+Add custom data providers easily:
 
 ```typescript
 class MyCustomProvider implements IStockProvider {
   name = 'My Provider';
   priority = 50;
   requiresAuth = true;
-
-  async fetchPrice(request: IStockQuoteRequest): Promise<IStockPrice> {
-    // Your implementation
-  }
-
-  async fetchPrices(request: IStockBatchQuoteRequest): Promise<IStockPrice[]> {
-    // Batch implementation
+  rateLimit = { requestsPerMinute: 60 };
+
+  async fetchData(request: IStockDataRequest): Promise<IStockPrice | IStockPrice[]> {
+    // Implement unified data fetching
+    switch (request.type) {
+      case 'current':
+        return this.fetchCurrentPrice(request);
+      case 'batch':
+        return this.fetchBatchPrices(request);
+      case 'historical':
+        return this.fetchHistoricalPrices(request);
+      default:
+        throw new Error(`Unsupported request type`);
+    }
   }
 
   async isAvailable(): Promise<boolean> {
     // Health check
+    return true;
   }
 
   supportsMarket(market: string): boolean {
-    // Market validation
+    return ['US', 'UK', 'DE'].includes(market);
   }
 
   supportsTicker(ticker: string): boolean {
-    // Ticker validation
+    return /^[A-Z]{1,5}$/.test(ticker);
   }
 }
 
@@ -645,30 +672,53 @@ stockService.register(new MyCustomProvider());
 
 ## Performance
 
-- **Batch fetching**: Get 100+ EOD prices in one API request
-- **Smart caching**: Instant repeated queries with configurable TTL
-- **Rate limit aware**: Automatic retry logic for API limits
-- **Concurrent processing**: Handle 1000+ business records/second
+- **Batch Fetching**: Get 100+ prices in one API request
+- **Smart Caching**: Data-type aware TTL (historical cached forever, EOD 24h, live 30s)
+- **Rate Limit Management**: Automatic retry logic for API limits
+- **Concurrent Processing**: Handle 1000+ records/second
 - **Streaming**: Process GB-sized datasets without memory issues
+- **Provider Fallback**: Automatic failover between data sources
 
 ## Testing
 
 Run the comprehensive test suite:
 
 ```bash
-npm test
+pnpm test
 ```
 
-Test stock provider:
+Test specific modules:
 
 ```bash
-npx tstest test/test.marketstack.node.ts --verbose
+# Stock price providers
+pnpm tstest test/test.marketstack.node.ts --verbose
+pnpm tstest test/test.stocks.ts --verbose
+
+# Fundamental data
+pnpm tstest test/test.secedgar.provider.node.ts --verbose
+pnpm tstest test/test.fundamentals.service.node.ts --verbose
+
+# German business data
+pnpm tstest test/test.handelsregister.ts --verbose
 ```
 
-Test German business data:
+## Getting API Keys
 
-```bash
-npx tstest test/test.handelsregister.ts --verbose
+### Marketstack (EOD Stock Data)
+
+1. Visit [marketstack.com](https://marketstack.com)
+2. Sign up for a free account (100 requests/month)
+3. Get your API key from the dashboard
+4. Set environment variable: `MARKETSTACK_COM_TOKEN=your_key_here`
+
+### SEC EDGAR (Fundamental Data)
+
+**No API key required!** SEC EDGAR is completely free and public. Just provide your company name and email in the User-Agent:
+
+```typescript
+new SecEdgarProvider({
+  userAgent: 'YourCompany youremail@example.com'
+});
 ```
 
 ## License and Legal Information