@fin.cx/opendata 3.5.0 → 3.6.0

package/readme.md

@@ -1,801 +1,405 @@
 # @fin.cx/opendata
 
-🚀 **Complete financial intelligence toolkit for TypeScript**
+`@fin.cx/opendata` is a TypeScript toolbox for serious data plumbing: market data, SEC fundamentals, German company registry workflows, and locally synced law corpora. It is built for programmers who want scriptable APIs, local persistence, and real workflows instead of a thin wrapper around one remote endpoint.
 
-Access real-time stock prices, fundamental financial data, and comprehensive German company information - all through a single, unified API.
+It currently gives you four practical lanes in one package:
+
+- `StockPriceService` for stock and crypto prices with caching, retries, failover, historical ranges, and intraday support
+- `FundamentalsService` and `StockDataService` for SEC fundamentals and combined price + fundamentals payloads
+- `OpenData` for German company ingestion plus browser-driven Handelsregister lookup and document download
+- `LawService` for syncing and searching German, EU, and US law texts in a local embedded database
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
 ## Installation
 
 ```bash
-npm install @fin.cx/opendata
-# or
 pnpm add @fin.cx/opendata
 ```
 
-## Quick Start
+## What You Get
 
-### ✨ Unified Stock Data API (Recommended)
+### Market Data
 
-Get complete stock data with automatic enrichment - the elegant way:
+- `StockPriceService`
+  Fetches current, batch, historical, and intraday price data.
+- `FundamentalsService`
+  Fetches SEC EDGAR fundamentals for US-listed companies.
+- `StockDataService`
+  Combines price + fundamentals and enriches fundamentals with metrics like `marketCap`, `priceToEarnings`, and `priceToBook`.
+- `MarketstackProvider`
+  Authenticated stock market provider with current, batch, historical, and intraday support.
+- `CoinGeckoProvider`
+  Crypto market provider behind the same stock-price interface.
+- `SecEdgarProvider`
+  Fundamentals provider backed by SEC EDGAR company facts.
 
-```typescript
-import { StockDataService, YahooFinanceProvider, SecEdgarProvider } from '@fin.cx/opendata';
+### German Company Data
 
-// Initialize unified service
-const stockData = new StockDataService();
+- `OpenData`
+  Starts a local embedded database, imports the public German company JSONL dump, and exposes a `handelsregister` helper for company lookup and file download.
 
-// Register providers
-stockData.registerPriceProvider(new YahooFinanceProvider());
-stockData.registerFundamentalsProvider(new SecEdgarProvider({
-  userAgent: 'YourCompany youremail@example.com'
-}));
+### Laws
 
-// ✨ Get complete stock data with ONE method call
-const apple = await stockData.getStockData('AAPL');
+- `LawService`
+  Syncs laws into a local embedded database and lets you search them later.
+- `LawRecord`
+  The stored law document model returned by sync and search operations.
 
-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
-});
+## Before You Start
 
-// Batch fetch with automatic enrichment
-const stocks = await stockData.getBatchStockData(['AAPL', 'MSFT', 'GOOGL']);
+- No stock or fundamentals providers are pre-registered. You must register them before calling the services.
+- `MarketstackProvider` requires an API key.
+- `SecEdgarProvider` requires a valid `User-Agent` string in the format `Company Name email@example.com`.
+- `CoinGeckoProvider` works without an API key, but a key gives you better rate limits.
+- `OpenData` requires `nogitDir`, `downloadDir`, and `germanBusinessDataDir`.
+- `OpenData.start()` is required before using `OpenData.handelsregister` or `buildInitialDb()`.
+- `LawService` stores data locally. It auto-starts on demand, but explicit `start()` and `stop()` keep lifecycle handling cleaner.
+- EU law syncing and Handelsregister access use a headless browser under the hood.
+- `StockDataService` defaults to a 24 hour price cache. If you want fresher quote caching, pass `cache.priceTTL` explicitly or use `StockPriceService` directly.
 
-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
+## Quick Start
 
-### 📈 Price-Only Data (Alternative)
+### Combined Stock Data
 
-If you only need prices without fundamentals:
+Use `StockDataService` when you want one call that returns both the latest price and SEC fundamentals.
 
-```typescript
-import { StockDataService, YahooFinanceProvider } from '@fin.cx/opendata';
+```ts
+import {
+  MarketstackProvider,
+  SecEdgarProvider,
+  StockDataService,
+} from '@fin.cx/opendata';
 
-const stockData = new StockDataService();
-stockData.registerPriceProvider(new YahooFinanceProvider());
+const stocks = new StockDataService({
+  cache: {
+    priceTTL: 60_000,
+  },
+});
 
-// Get just the price
-const price = await stockData.getPrice('AAPL');
-console.log(`${price.ticker}: $${price.price}`);
+stocks.registerPriceProvider(
+  new MarketstackProvider(process.env.MARKETSTACK_API_KEY!)
+);
 
-// Or use StockPriceService directly for more control
-import { StockPriceService } from '@fin.cx/opendata';
+stocks.registerFundamentalsProvider(
+  new SecEdgarProvider({
+    userAgent: 'Acme Inc. dev@acme.dev',
+  })
+);
 
-const stockService = new StockPriceService({ ttl: 60000 });
-stockService.register(new YahooFinanceProvider());
+const apple = await stocks.getStockData('AAPL');
 
-const apple = await stockService.getData({ type: 'current', ticker: 'AAPL' });
-console.log(`${apple.companyFullName}: $${apple.price}`);
+console.log({
+  ticker: apple.ticker,
+  price: apple.price.price,
+  provider: apple.price.provider,
+  companyName: apple.fundamentals?.companyName,
+  marketCap: apple.fundamentals?.marketCap,
+  priceToEarnings: apple.fundamentals?.priceToEarnings,
+  fetchedAt: apple.fetchedAt,
+});
 ```
 
-### 🪙 Cryptocurrency Prices
-
-Get real-time crypto prices with the CoinGecko provider:
-
-```typescript
-import { StockPriceService, CoinGeckoProvider } from '@fin.cx/opendata';
+You can also batch this:
 
-const stockService = new StockPriceService({ ttl: 30000 });
+```ts
+const batch = await stocks.getBatchStockData(['AAPL', 'MSFT', 'NVDA']);
+```
 
-// Optional: Pass API key for higher rate limits
-// const provider = new CoinGeckoProvider('your-api-key');
-const provider = new CoinGeckoProvider();
+### Price-Only Stocks And Intraday Data
 
-stockService.register(provider);
+Use `StockPriceService` if you want smarter per-request caching and direct access to current, historical, and intraday request types.
 
-// Fetch single crypto price (using ticker symbol)
-const btc = await stockService.getPrice({ ticker: 'BTC' });
-console.log(`${btc.ticker}: $${btc.price.toLocaleString()}`);
-console.log(`24h Change: ${btc.changePercent.toFixed(2)}%`);
-console.log(`24h Volume: $${btc.volume?.toLocaleString()}`);
+```ts
+import { MarketstackProvider, StockPriceService } from '@fin.cx/opendata';
 
-// Or use CoinGecko ID directly
-const ethereum = await stockService.getPrice({ ticker: 'ethereum' });
+const prices = new StockPriceService();
+prices.register(new MarketstackProvider(process.env.MARKETSTACK_API_KEY!));
 
-// Batch fetch multiple cryptos
-const cryptos = await stockService.getPrices({
-  tickers: ['BTC', 'ETH', 'USDT', 'BNB', 'SOL']
-});
+const current = await prices.getPrice({ ticker: 'AAPL' });
 
-cryptos.forEach(crypto => {
-  console.log(`${crypto.ticker}: $${crypto.price.toFixed(2)} (${crypto.changePercent >= 0 ? '+' : ''}${crypto.changePercent.toFixed(2)}%)`);
-});
-
-// Historical crypto prices
-const history = await stockService.getData({
+const historical = await prices.getData({
   type: 'historical',
-  ticker: 'BTC',
+  ticker: 'AAPL',
   from: new Date('2025-01-01'),
-  to: new Date('2025-01-31')
+  to: new Date('2025-01-31'),
+  sort: 'DESC',
 });
 
-// Intraday crypto prices (hourly)
-const intraday = await stockService.getData({
+const intraday = await prices.getData({
   type: 'intraday',
-  ticker: 'ETH',
+  ticker: 'AAPL',
   interval: '1hour',
-  limit: 24 // Last 24 hours
+  limit: 24,
+});
+
+console.log({
+  live: current.price,
+  candles: intraday.length,
+  historicalRows: historical.length,
 });
 ```
 
-### 💰 Fundamentals-Only Data (Alternative)
+Supported stock request shapes:
 
-If you only need fundamentals without prices:
+- `{ type: 'current', ticker, exchange? }`
+- `{ type: 'batch', tickers, exchange? }`
+- `{ type: 'historical', ticker, from, to, exchange?, sort?, limit?, offset? }`
+- `{ type: 'intraday', ticker, interval, exchange?, limit?, date? }`
 
-```typescript
-import { StockDataService, SecEdgarProvider } from '@fin.cx/opendata';
+`StockPriceService` also exposes operational helpers like `checkProvidersHealth()`, `getProviderStats()`, `clearCache()`, and `getCacheStats()`.
 
-const stockData = new StockDataService();
-stockData.registerFundamentalsProvider(new SecEdgarProvider({
-  userAgent: 'YourCompany youremail@example.com'
-}));
+### Crypto Prices With The Same Interface
 
-// Get just fundamentals
-const fundamentals = await stockData.getFundamentals('AAPL');
+`CoinGeckoProvider` plugs into `StockPriceService`, so crypto lookups use the same request model as stock lookups.
 
-console.log({
-  company: fundamentals.companyName,
-  eps: fundamentals.earningsPerShareDiluted,
-  revenue: fundamentals.revenue,
-  sharesOutstanding: fundamentals.sharesOutstanding
-});
+```ts
+import { CoinGeckoProvider, StockPriceService } from '@fin.cx/opendata';
 
-// Or use FundamentalsService directly
-import { FundamentalsService } from '@fin.cx/opendata';
+const prices = new StockPriceService({ ttl: 30_000 });
+prices.register(new CoinGeckoProvider(process.env.COINGECKO_API_KEY));
 
-const fundamentalsService = new FundamentalsService();
-fundamentalsService.register(new SecEdgarProvider({
-  userAgent: 'YourCompany youremail@example.com'
-}));
+const btc = await prices.getPrice({ ticker: 'BTC' });
+const top = await prices.getPrices({ tickers: ['BTC', 'ETH', 'SOL'] });
 
-const data = await fundamentalsService.getFundamentals('AAPL');
+console.log(btc.price, top.map((item) => item.ticker));
 ```
 
-### 🏢 German Business Intelligence
+You can also pass CoinGecko ids like `bitcoin` or `ethereum` instead of ticker symbols.
 
-Access comprehensive German company data:
+### Fundamentals Only
 
-```typescript
-import { OpenData } from '@fin.cx/opendata';
-import * as path from 'path';
+Use `FundamentalsService` when you only care about SEC filing data.
 
-// Configure directory 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')
-});
-await openData.start();
+```ts
+import { FundamentalsService, SecEdgarProvider } from '@fin.cx/opendata';
 
-// Search for companies
-const results = await openData.handelsregister.searchCompany("Siemens AG");
+const fundamentals = new FundamentalsService();
+fundamentals.register(
+  new SecEdgarProvider({
+    userAgent: 'Acme Inc. dev@acme.dev',
+  })
+);
 
-// Get detailed information with documents
-const details = await openData.handelsregister.getSpecificCompany({
-  court: "Munich",
-  type: "HRB",
-  number: "6684"
-});
-```
+const apple = await fundamentals.getFundamentals('AAPL');
 
-## Features
-
-### 📊 Stock & Crypto Market Module
-
-- **Real-Time Prices** - Live and EOD prices from Yahoo Finance, Marketstack, and CoinGecko
-- **Cryptocurrency Support** - 13M+ crypto tokens with 24/7 market data via CoinGecko
-- **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)
-- **Batch Operations** - Fetch 100+ symbols in one request
-- **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** - 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
-
-### Combined Market Analysis (Unified API)
-
-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)}`);
-  }
+console.log({
+  companyName: apple.companyName,
+  revenue: apple.revenue,
+  netIncome: apple.netIncome,
+  earningsPerShareDiluted: apple.earningsPerShareDiluted,
+  filingDate: apple.filingDate,
 });
-
-// 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
+### German Company Data And Handelsregister Automation
 
-Screen stocks by financial metrics:
+`OpenData` is the local workflow layer for German company data. It creates its directories, boots an embedded SmartDB-backed database, and starts a browser automation session for Handelsregister access.
 
-```typescript
-// Fetch data for multiple tickers
-const tickers = ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'META', 'NVDA', 'TSLA'];
-const stocks = await stockData.getBatchStockData(tickers);
+```ts
+import { OpenData } from '@fin.cx/opendata';
+import * as path from 'node:path';
 
-// 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
-});
+const nogitDir = path.join(process.cwd(), '.nogit');
 
-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)}`);
+const openData = new OpenData({
+  nogitDir,
+  downloadDir: path.join(nogitDir, 'downloads'),
+  germanBusinessDataDir: path.join(nogitDir, 'germanbusinessdata'),
 });
-```
 
-### Historical Data Analysis
+await openData.start();
 
-Fetch and analyze historical price trends:
+const matches = await openData.handelsregister.searchCompany('Siemens AG', 20);
 
-```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
+const company = await openData.handelsregister.getSpecificCompany({
+  court: 'Munich',
+  type: 'HRB',
+  number: '6684',
 });
 
-// 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 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;
-};
-
-const sma20 = calculateSMA(history, 20);
-const sma50 = calculateSMA(history, 50);
-
-console.log(`\nMoving Averages:`);
-console.log(`  20-day SMA: $${sma20[0].toFixed(2)}`);
-console.log(`  50-day SMA: $${sma50[0].toFixed(2)}`);
-```
-
-### 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')
+console.log({
+  searchHits: matches.length,
+  downloadedFiles: company.files.map((file) => file.path),
 });
 
-// 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)}%)`);
-}
+await openData.stop();
 ```
 
-### Fundamental Data Screening
+Useful `OpenData` workflows today:
 
-Screen stocks based on fundamental metrics:
+- `await openData.start()`
+- `await openData.buildInitialDb()` to ingest the public German company JSONL dataset
+- `await openData.handelsregister.searchCompany(name, limit)`
+- `await openData.handelsregister.getSpecificCompany({ court, type, number })`
+- `await openData.handelsregister.getSpecificCompanyByName(name)`
 
-```typescript
-const tickers = ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA', 'META', 'NVDA'];
+The download workflow currently fetches the Handelsregister files into a temporary folder and returns the files to you as `SmartFile` objects.
 
-// Fetch fundamentals for all tickers
-const allFundamentals = await fundamentalsService.getBatchFundamentals(tickers);
+### Law Syncing And Search
 
-// Get current prices
-const prices = await stockService.getData({
-  type: 'batch',
-  tickers: tickers
-});
-
-// Create price map
-const priceMap = new Map(prices.map(p => [p.ticker, p.price]));
+`LawService` stores synced laws in a local embedded database and supports three jurisdictions:
 
-// Enrich with prices
-const enriched = await fundamentalsService.enrichBatchWithPrices(
-  allFundamentals,
-  priceMap
-);
+- Germany via `gesetze-im-internet`
+- EU via `EUR-Lex`
+- US via GovInfo and Cornell LII
 
-// 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
-);
+```ts
+import { LawService } from '@fin.cx/opendata';
 
-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`);
+const laws = new LawService({
+  dbFolderPath: '.nogit/law-smartdb',
+  dbName: 'laws',
+  govInfoApiKey: process.env.GOVINFO_API_KEY,
 });
-```
-
-### Market Dashboard
-
-Create a comprehensive market overview:
 
-```typescript
-const indicators = [
-  { ticker: 'AAPL', name: 'Apple' },
-  { ticker: 'MSFT', name: 'Microsoft' },
-  { ticker: 'GOOGL', name: 'Alphabet' },
-  { ticker: 'AMZN', name: 'Amazon' },
-  { ticker: 'TSLA', name: 'Tesla' }
-];
+await laws.start();
 
-const prices = await stockService.getData({
-  type: 'batch',
-  tickers: indicators.map(i => i.ticker)
+const germanLaw = await laws.syncLaw({
+  jurisdiction: 'de',
+  identifier: 'aeg',
 });
 
-// Display with color-coded changes
-prices.forEach(price => {
-  const indicator = indicators.find(i => i.ticker === price.ticker);
-  const arrow = price.change >= 0 ? '↑' : '↓';
-  const color = price.change >= 0 ? '\x1b[32m' : '\x1b[31m';
-
-  console.log(
-    `${price.companyName!.padEnd(25)} $${price.price.toFixed(2).padStart(8)} ` +
-    `${color}${arrow} ${price.changePercent.toFixed(2)}%\x1b[0m`
-  );
-});
-```
-
-### 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`);
-  }
-}
-```
-
-## Configuration
-
-### Stock Service Options
-
-```typescript
-const stockService = new StockPriceService({
-  ttl: 60000,         // Default cache TTL in ms
-  maxEntries: 10000   // Max cached entries
+const euLaw = await laws.syncLaw({
+  jurisdiction: 'eu',
+  identifier: '32024R1689',
+  language: 'EN',
 });
 
-// Marketstack - EOD data (requires API key)
-stockService.register(new MarketstackProvider('YOUR_API_KEY'), {
-  enabled: true,
-  priority: 100,
-  timeout: 10000,
-  retryAttempts: 3,
-  retryDelay: 1000
+const usCode = await laws.syncLaw({
+  jurisdiction: 'us',
+  identifier: '8 U.S.C. § 1226',
 });
 
-// Yahoo Finance - Real-time data (no API key)
-stockService.register(new YahooFinanceProvider(), {
-  enabled: true,
-  priority: 50
+const results = await laws.searchLaws({
+  jurisdiction: 'eu',
+  query: 'Artificial Intelligence Act',
+  limit: 5,
 });
-```
-
-### Fundamentals Service Options
 
-```typescript
-const fundamentalsService = new FundamentalsService({
-  ttl: 90 * 24 * 60 * 60 * 1000,  // 90 days (quarterly refresh)
-  maxEntries: 10000
+console.log({
+  germany: germanLaw.title,
+  eu: euLaw.title,
+  us: usCode.title,
+  hits: results.length,
 });
 
-// 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
-}));
+await laws.stop();
 ```
 
-### Directory Configuration (German Business Data)
-
-All directory paths are mandatory when using German business data features:
+`LawService` also supports bulk sync:
 
-```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
-const openDataProd = new OpenData({
-  nogitDir: '/var/lib/myapp/data',
-  downloadDir: '/var/lib/myapp/data/downloads',
-  germanBusinessDataDir: '/var/lib/myapp/data/germanbusinessdata'
+```ts
+await laws.syncLaws({
+  jurisdiction: 'us',
+  usCollection: 'PLAW',
+  limit: 25,
+  since: new Date('2025-01-01'),
 });
 ```
 
-### Environment Variables
-
-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
-```
-
-## API Reference
-
-### Stock Price Interfaces
-
-```typescript
-interface IStockPrice {
-  ticker: string;
-  price: number;
-  currency: string;
-  change: number;
-  changePercent: number;
-  previousClose: number;
-  timestamp: Date;
-  provider: string;
-  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**
-- `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) 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)
-
-**YahooFinanceProvider**
-- ✅ Real-time stock prices
-- ✅ No API key required
-- ✅ Global coverage
-- ✅ Company names included
-- ⚠️ Rate limits may apply
-
-**CoinGeckoProvider**
-- ✅ Cryptocurrency prices (Bitcoin, Ethereum, 13M+ tokens)
-- ✅ Current, historical, and intraday data
-- ✅ 24/7 market data (crypto never closes)
-- ✅ OHLCV data with market cap and volume
-- ✅ Supports both ticker symbols (BTC, ETH) and CoinGecko IDs (bitcoin, ethereum)
-- ✅ 240+ networks, 1600+ exchanges
-- ℹ️ Optional API key (free tier: 30 requests/min, 10K/month)
-
-**OpenData**
-- `start()` - Initialize MongoDB connection
-- `buildInitialDb()` - Import bulk data
-- `CBusinessRecord` - Business record class
-- `handelsregister` - German registry automation
-
-## Provider Architecture
-
-Add custom data providers easily:
-
-```typescript
-class MyCustomProvider implements IStockProvider {
-  name = 'My Provider';
-  priority = 50;
-  requiresAuth = true;
-  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 {
-    return ['US', 'UK', 'DE'].includes(market);
-  }
-
-  supportsTicker(ticker: string): boolean {
-    return /^[A-Z]{1,5}$/.test(ticker);
-  }
-}
-
-stockService.register(new MyCustomProvider());
-```
-
-## Performance
-
-- **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
+Useful request patterns:
+
+- Germany: `identifier: 'aeg'`
+- EU: `identifier: '32024R1689'`, `language: 'EN'`
+- US public law package: `identifier: 'PLAW-119publ1'`, `usCollection: 'PLAW'`
+- US Code citation: `identifier: '8 U.S.C. § 1226'`
+
+## API At A Glance
+
+### `StockPriceService`
+
+- `register(provider, config?)`
+- `unregister(providerName)`
+- `getPrice({ ticker })`
+- `getPrices({ tickers })`
+- `getData(request)`
+- `checkProvidersHealth()`
+- `getProviderStats()`
+- `clearCache()`
+- `getCacheStats()`
+
+### `FundamentalsService`
+
+- `register(provider, config?)`
+- `getFundamentals(ticker)`
+- `getBatchFundamentals(tickers)`
+- `getData(request)`
+- `enrichWithPrice(fundamentals, price)`
+- `checkProvidersHealth()`
+- `getProviderStats()`
+- `clearCache()`
+
+### `StockDataService`
+
+- `registerPriceProvider(provider, config?)`
+- `registerFundamentalsProvider(provider, config?)`
+- `getPrice(ticker)`
+- `getPrices(tickers)`
+- `getFundamentals(ticker)`
+- `getBatchFundamentals(tickers)`
+- `getStockData(ticker | request)`
+- `getBatchStockData(tickers | request)`
+- `checkProvidersHealth()`
+- `getProviderStats()`
+- `clearCache()`
+
+### `OpenData`
+
+- `start()`
+- `stop()`
+- `buildInitialDb()`
+- `handelsregister.searchCompany(name, limit?)`
+- `handelsregister.getSpecificCompany({ court, type, number })`
+- `handelsregister.getSpecificCompanyByName(name)`
+
+### `LawService`
+
+- `start()`
+- `stop()`
+- `getLaw(request)`
+- `syncLaw(request)`
+- `syncLaws(request)`
+- `searchLaws({ query, jurisdiction?, limit? })`
+
+## Behavior And Caveats
+
+- Historical market data is cached aggressively because it is treated as immutable.
+- Intraday data uses interval-aware caching and tries incremental refreshes for recent data.
+- `StockDataService` is convenience-first. `StockPriceService` is the better low-level choice if you care about request-shape-specific cache behavior.
+- `OpenData` is a real workflow layer, not just types. It writes local data, launches a browser, and manages downloads.
+- Handelsregister and EUR-Lex integrations depend on current site structure. They are practical automation workflows, not guaranteed stable official APIs.
+- The most useful public `OpenData` features today are startup, JSONL import, and Handelsregister operations. Some extra validation/search helper methods exist in source but are still stubs.
+- `LawService` persists synced laws locally, so repeated searches can stay offline once the data has been synced.
+- There is no hosted backend in this package. Everything is meant to run from your own TypeScript/Node process.
 
 ## Testing
 
-Run the comprehensive test suite:
-
 ```bash
 pnpm test
 ```
 
-Test specific modules:
-
-```bash
-# 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
-```
-
-## Getting API Keys
-
-### 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'
-});
-```
+Some tests hit live remote services, so they may depend on network access, optional API credentials, or browser automation support.
 
 ## License and Legal Information
 
-This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./license) file.
 
 **Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
 ### Trademarks
 
-This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
 ### Company Information
 
-Task Venture Capital GmbH
-Registered at District court Bremen HRB 35230 HB, Germany
+Task Venture Capital GmbH  
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
 By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.