@fin.cx/opendata 3.5.1 → 4.0.0

package/readme.md

@@ -1,787 +1,438 @@
 # @fin.cx/opendata
 
-🚀 **Complete financial intelligence toolkit for TypeScript**
+`@fin.cx/opendata` is a TypeScript toolbox for open business and market data: stock and crypto prices, SEC fundamentals, and lookups in the German registers through the register portal of the federal states. It is built for programmers who want scriptable APIs 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 gives you three 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
+- `HandelsregisterClient`, from `@fin.cx/opendata/handelsregister`, for single lookups in the commercial, cooperative, partnership, association and civil-law partnership registers over plain HTTP, without any storage
+
+## 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
+
+### Market Data
+
+- `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.
+
+### German Registers
+
+Everything here comes from `@fin.cx/opendata/handelsregister`. That entry point imports nothing else of the package, needs no database, no browser and no download folder, and keeps nothing between calls.
+
+- `HandelsregisterClient`
+  Searches the register portal (handelsregister.de) by name or register number and retrieves one register sheet with its structured register content (SI) parsed into a typed result.
+- `SlidingWindowGate`
+  Holds the portal's limit of 60 searches and retrievals per hour. The client asks it before every counted request.
+- `parseStructuredContent()` and `parseSearchResults()`
+  The parsers on their own, for an SI file or a result page someone saved from the portal. They make no request.
+- `registerCourts`, `findRegisterCourt()`, `parseRegisterReferenceText()`, `formatRegisterReference()`
+  The 150 register courts with their XJustiz codes, and helpers for register references as businesses print them (`Amtsgericht Bremen HRB 35230 HB`).
+
+## Before You Start
+
+- 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.
+- `HandelsregisterClient` needs a gate. The portal's terms allow at most 60 searches or retrievals of entities per hour from one installation, so share one `SlidingWindowGate` (or a gate of your own) among every client that reaches the portal from the same address.
+- The portal's terms allow single lookups for information purposes. Systematic retrieval to build or update a copy of the registers is not allowed, and neither is publishing the data under the name "Handelsregister" (§ 8 Abs. 2 HGB).
+- `StockDataService` defaults to a 24 hour price cache. If you want fresher quote caching, pass `cache.priceTTL` explicitly or use `StockPriceService` directly.
 
-### ✨ Unified Stock Data API (Recommended)
+## Quick Start
 
-Get complete stock data with automatic enrichment - the elegant way:
+### Combined Stock Data
 
-```typescript
-import { StockDataService, SecEdgarProvider } from '@fin.cx/opendata';
+Use `StockDataService` when you want one call that returns both the latest price and SEC fundamentals.
 
-// Initialize unified service
-const stockData = new StockDataService();
+```ts
+import {
+  MarketstackProvider,
+  SecEdgarProvider,
+  StockDataService,
+} from '@fin.cx/opendata';
 
-// Register providers
-stockData.registerFundamentalsProvider(new SecEdgarProvider({
-  userAgent: 'YourCompany youremail@example.com'
-}));
+const stocks = new StockDataService({
+  cache: {
+    priceTTL: 60_000,
+  },
+});
 
-// ✨ Get complete stock data with ONE method call
-const apple = await stockData.getStockData('AAPL');
+stocks.registerPriceProvider(
+  new MarketstackProvider(process.env.MARKETSTACK_API_KEY!)
+);
 
-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
-});
+stocks.registerFundamentalsProvider(
+  new SecEdgarProvider({
+    userAgent: 'Acme Inc. dev@acme.dev',
+  })
+);
 
-// Batch fetch with automatic enrichment
-const stocks = await stockData.getBatchStockData(['AAPL', 'MSFT', 'GOOGL']);
+const apple = await stocks.getStockData('AAPL');
 
-stocks.forEach(stock => {
-  console.log(`${stock.ticker}: $${stock.price.price.toFixed(2)}, ` +
-              `P/E ${stock.fundamentals?.priceToEarnings?.toFixed(2)}`);
+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,
 });
-// Output:
-// AAPL: $270.37, P/E 28.42
-// MSFT: $425.50, P/E 34.21
-// GOOGL: $142.15, P/E 25.63
 ```
 
-**Why use the unified API?**
-- ✅ **Single service** for both prices and fundamentals
-- ✅ **Automatic enrichment** - Market cap, P/E, P/B calculated automatically
-- ✅ **One method call** - No manual `enrichWithPrice()` calls
-- ✅ **Simplified code** - Less boilerplate, more readable
-- ✅ **Type-safe** - Full TypeScript support
-
-### 📈 Price-Only Data (Alternative)
-
-If you only need prices without fundamentals:
-
-```typescript
-import { StockDataService, MarketstackProvider } from '@fin.cx/opendata';
-
-const stockData = new StockDataService();
-stockData.registerPriceProvider(new MarketstackProvider('YOUR_API_KEY'));
-
-// Get just the price
-const price = await stockData.getPrice('AAPL');
-console.log(`${price.ticker}: $${price.price}`);
-
-// Or use StockPriceService directly for more control
-import { StockPriceService } from '@fin.cx/opendata';
+You can also batch this:
 
-const stockService = new StockPriceService({ ttl: 60000 });
-stockService.register(new MarketstackProvider('YOUR_API_KEY'));
-
-const apple = await stockService.getData({ type: 'current', ticker: 'AAPL' });
-console.log(`${apple.companyFullName}: $${apple.price}`);
+```ts
+const batch = await stocks.getBatchStockData(['AAPL', 'MSFT', 'NVDA']);
 ```
 
-### 🪙 Cryptocurrency Prices
-
-Get real-time crypto prices with the CoinGecko provider:
-
-```typescript
-import { StockPriceService, CoinGeckoProvider } from '@fin.cx/opendata';
+### Price-Only Stocks And Intraday Data
 
-const stockService = new StockPriceService({ ttl: 30000 });
+Use `StockPriceService` if you want smarter per-request caching and direct access to current, historical, and intraday request types.
 
-// Optional: Pass API key for higher rate limits
-// const provider = new CoinGeckoProvider('your-api-key');
-const provider = new CoinGeckoProvider();
+```ts
+import { MarketstackProvider, StockPriceService } from '@fin.cx/opendata';
 
-stockService.register(provider);
+const prices = new StockPriceService();
+prices.register(new MarketstackProvider(process.env.MARKETSTACK_API_KEY!));
 
-// 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()}`);
+const current = await prices.getPrice({ ticker: 'AAPL' });
 
-// Or use CoinGecko ID directly
-const ethereum = await stockService.getPrice({ ticker: 'ethereum' });
-
-// Batch fetch multiple cryptos
-const cryptos = await stockService.getPrices({
-  tickers: ['BTC', 'ETH', 'USDT', 'BNB', 'SOL']
-});
-
-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,
 });
-```
-
-### 💰 Fundamentals-Only Data (Alternative)
-
-If you only need fundamentals without prices:
-
-```typescript
-import { StockDataService, SecEdgarProvider } from '@fin.cx/opendata';
-
-const stockData = new StockDataService();
-stockData.registerFundamentalsProvider(new SecEdgarProvider({
-  userAgent: 'YourCompany youremail@example.com'
-}));
-
-// Get just fundamentals
-const fundamentals = await stockData.getFundamentals('AAPL');
 
 console.log({
-  company: fundamentals.companyName,
-  eps: fundamentals.earningsPerShareDiluted,
-  revenue: fundamentals.revenue,
-  sharesOutstanding: fundamentals.sharesOutstanding
+  live: current.price,
+  candles: intraday.length,
+  historicalRows: historical.length,
 });
-
-// Or use FundamentalsService directly
-import { FundamentalsService } from '@fin.cx/opendata';
-
-const fundamentalsService = new FundamentalsService();
-fundamentalsService.register(new SecEdgarProvider({
-  userAgent: 'YourCompany youremail@example.com'
-}));
-
-const data = await fundamentalsService.getFundamentals('AAPL');
 ```
 
-### 🏢 German Business Intelligence
+Supported stock request shapes:
 
-Access comprehensive German company data:
+- `{ 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 { OpenData } from '@fin.cx/opendata';
-import * as path from 'path';
+`StockPriceService` also exposes operational helpers like `checkProvidersHealth()`, `getProviderStats()`, `clearCache()`, and `getCacheStats()`.
 
-// 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();
-
-// Search for companies
-const results = await openData.handelsregister.searchCompany("Siemens AG");
-
-// Get detailed information with documents
-const details = await openData.handelsregister.getSpecificCompany({
-  court: "Munich",
-  type: "HRB",
-  number: "6684"
-});
-```
+### Crypto Prices With The Same Interface
 
-## Features
+`CoinGeckoProvider` plugs into `StockPriceService`, so crypto lookups use the same request model as stock lookups.
 
-### 📊 Stock & Crypto Market Module
+```ts
+import { CoinGeckoProvider, StockPriceService } from '@fin.cx/opendata';
 
-- **Real-Time Prices** - Live and EOD prices from 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
+const prices = new StockPriceService({ ttl: 30_000 });
+prices.register(new CoinGeckoProvider(process.env.COINGECKO_API_KEY));
 
-### 💰 Fundamental Data Module
+const btc = await prices.getPrice({ ticker: 'BTC' });
+const top = await prices.getPrices({ tickers: ['BTC', 'ETH', 'SOL'] });
 
-- **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
+console.log(btc.price, top.map((item) => item.ticker));
+```
 
-- **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
+You can also pass CoinGecko ids like `bitcoin` or `ethereum` instead of ticker symbols.
 
-## Advanced Examples
+### Fundamentals Only
 
-### Combined Market Analysis (Unified API)
+Use `FundamentalsService` when you only care about SEC filing data.
 
-Analyze multiple companies with automatic enrichment:
+```ts
+import { FundamentalsService, SecEdgarProvider } from '@fin.cx/opendata';
 
-```typescript
-import { StockDataService, MarketstackProvider, SecEdgarProvider } from '@fin.cx/opendata';
+const fundamentals = new FundamentalsService();
+fundamentals.register(
+  new SecEdgarProvider({
+    userAgent: 'Acme Inc. dev@acme.dev',
+  })
+);
 
-// Setup unified service
-const stockData = new StockDataService();
-stockData.registerPriceProvider(new MarketstackProvider('YOUR_API_KEY'));
-stockData.registerFundamentalsProvider(new SecEdgarProvider({
-  userAgent: 'YourCompany youremail@example.com'
-}));
+const apple = await fundamentals.getFundamentals('AAPL');
 
-// 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
+### Register Lookups (Handelsregister)
 
-Screen stocks by financial metrics:
+`HandelsregisterClient` speaks to the register portal of the federal states over plain HTTP, the way a browser would: it opens the search form, sends the search, reads the result list and, for one entry, downloads the structured register content (SI, an XJustiz XML file) and parses it.
 
-```typescript
-// Fetch data for multiple tickers
-const tickers = ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'META', 'NVDA', 'TSLA'];
-const stocks = await stockData.getBatchStockData(tickers);
+```ts
+import {
+  HandelsregisterClient,
+  HandelsregisterError,
+  SlidingWindowGate,
+  findRegisterCourt,
+  formatRegisterReference,
+} from '@fin.cx/opendata/handelsregister';
 
-// 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
-});
+// one gate for the whole installation: 60 searches or retrievals per hour
+const gate = new SlidingWindowGate();
 
-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 register = new HandelsregisterClient({
+  gate,
+  userAgent: 'Example Books (+https://example.com/contact)',
 });
-```
-
-### Historical Data Analysis
-
-Fetch and analyze historical price trends:
 
-```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
-});
+// by name: every row the portal lists, in its order, never narrowed down to one
+const found = await register.search({ name: 'Task Venture Capital', seat: 'Bremen' });
+const choices = found.matches.map((match) => ({
+  reference: formatRegisterReference(match.reference), // 'Amtsgericht Bremen HRB 35230 HB'
+  name: match.name,
+  sheet: match.sheetStatus, // 'current' or 'closed'
+  formerNames: match.formerNames,
+}));
+if (found.truncated) {
+  // the portal stops at 100 hits: add the seat, the court or the register number
+}
 
-// 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);
+// one register sheet, with its structured content
+const court = findRegisterCourt('Amtsgericht Bremen');
+if (court) {
+  const entry = await register.getEntry({ courtCode: court.code, type: 'HRB', number: '35230 HB' });
+  const content = entry.structuredContent; // null when the portal offers none for this entry
+  if (content) {
+    const facts = {
+      name: content.name,
+      legalForm: content.legalForm?.short, // 'GmbH'
+      address: content.address,
+      status: content.status?.state, // 'active', 'deleted', 'in_liquidation', 'insolvent', 'merged'
+      representatives: content.representatives, // [{ name, function, functionCode, kind }]
+      retrievedAt: entry.retrievedAt,
+      notice: entry.notice.en, // the portal's note: the structured content is not binding
+    };
   }
-  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')
-});
-
-// 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)}%)`);
 }
-```
-
-### Fundamental Data Screening
-
-Screen stocks based on fundamental metrics:
-
-```typescript
-const tickers = ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'TSLA', 'META', 'NVDA'];
-
-// Fetch fundamentals for all tickers
-const allFundamentals = await fundamentalsService.getBatchFundamentals(tickers);
-
-// 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]));
-
-// 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 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' }
-];
-
-const prices = await stockService.getData({
-  type: 'batch',
-  tickers: indicators.map(i => i.ticker)
-});
-
-// 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`);
+// every failure is typed
+try {
+  await register.getEntry({ courtCode: 'H1101', type: 'HRB', number: '35230' });
+} catch (error) {
+  if (error instanceof HandelsregisterError && error.code === 'rate_limited') {
+    const nextPossibleAt = new Date(error.retryAt ?? Date.now());
   }
 }
 ```
 
-## Configuration
+Searches take a name or a register number:
 
-### Stock Service Options
+- `{ name, match?: 'all' | 'any' | 'exact', seat?, type?, courtCode?, includeClosed? }`
+- `{ type, number, courtCode?, includeClosed? }` where `type` is `HRA`, `HRB`, `GnR`, `PR`, `VR` or `GsR` and `number` may carry the location suffix (`999924 B`, `999928 NM`). The portal is searched by the digits, so rows with any suffix come back. Without `courtCode`, every court's entry with that number is returned.
 
-```typescript
-const stockService = new StockPriceService({
-  ttl: 60000,         // Default cache TTL in ms
-  maxEntries: 10000   // Max cached entries
-});
+`getEntry({ courtCode, type, number })` identifies one sheet. It includes closed sheets, compares the location suffix when you give one, and never picks one of several: it fails with `not_found` or `ambiguous` and lists the candidates.
 
-// Marketstack - EOD data (requires API key)
-stockService.register(new MarketstackProvider('YOUR_API_KEY'), {
-  enabled: true,
-  priority: 100,
-  timeout: 10000,
-  retryAttempts: 3,
-  retryDelay: 1000
-});
-```
+#### What counts against the 60 per hour
 
-### Fundamentals Service Options
+| Call | Counted requests | Also loaded |
+| --- | --- | --- |
+| `search()` | 1 search | the search form and the result list |
+| `getEntry()` | 1 search, plus 1 retrieval when the portal offers structured content | the search form and the result list |
 
-```typescript
-const fundamentalsService = new FundamentalsService({
-  ttl: 90 * 24 * 60 * 60 * 1000,  // 90 days (quarterly refresh)
-  maxEntries: 10000
-});
+The client asks the gate before each counted request and before that step sends anything, so a refusal costs no traffic. A slot taken for a step that then fails before its request is sent stays taken; the count errs on the safe side. The client never repeats a request by itself, never caches, and never writes to the console. Every call opens its own visit to the portal and forgets it afterwards.
 
-// 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
-}));
-```
+A refusal of `SlidingWindowGate` is a `HandelsregisterError` with the code `rate_limited` and `retryAt`, the moment the next request is possible. Like every error of the client it carries the refused `step` (`search` or `structured_content`) and the `countedRequests` made before it: a `getEntry()` refused at the retrieval has already counted its search. A gate of your own may refuse with any error; a `HandelsregisterError` gains the step and the count the same way, and any other error reaches the caller unchanged.
 
-### Directory Configuration (German Business Data)
+#### What a result holds
 
-All directory paths are mandatory when using German business data features:
+- `IRegisterMatch`, one row of the result list: `reference` (court with code and name, register type, number with suffix), `formerCourt`, `federalState`, `name`, `seat`, `sheetStatus` (`current`, `closed` or `other`, with the portal's word in `sheetStatusText`), `formerNames` and the `documents` the portal offers.
+- `IRegisterStructuredContent`, the parsed SI: `name`, `legalForm` (XUnternehmen code with short and long designation), `seat`, the business `address`, `register`, `status` (XJustiz status of the legal entity), `lastEntryOn`, `representatives` and `representationStated`, `producedAt`, `binding: false` and the portal's `notice`.
+- A closed sheet ("Geschlossenes Registerblatt") means the entry was deleted, or its sheet was closed when the entity moved to another court, changed its legal form or merged. The result list does not say which, and the portal offers no structured content for it.
+- The structured content states no date for the status itself; `lastEntryOn` is the date of the latest entry on the sheet.
+- Of people the parser reads the name and the function only. Birth dates, places of residence and private addresses never leave it.
+- Codes are decoded with tables taken from the code lists on XRepository on 2026-09-23. A code the tables do not know is kept as a code, without a designation.
 
-```typescript
-import { OpenData } from '@fin.cx/opendata';
-import * as path from 'path';
+#### What can happen
 
-// 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')
-});
+| Case | Result |
+| --- | --- |
+| No match | `search()` returns no matches; `getEntry()` fails with `not_found` |
+| Several matches in different courts | every row, in the portal's order |
+| More than 100 hits | the first 100 and `truncated: true` |
+| Renamed entity | the current name, earlier names in `formerNames` |
+| Deleted or moved entity | `sheetStatus: 'closed'`, no structured content |
+| Dissolved or insolvent entity | `status.state` `in_liquidation` or `insolvent`, and the liquidators among the representatives |
+| Branch of a company under foreign law | its foreign legal form and seat, and its permanent representatives |
+| Partnership, cooperative, association, civil-law partnership | register types `PR`, `GnR`, `VR`, `GsR` |
+| Number without suffix that fits several sheets | `ambiguous` with the candidates |
+| Suffix that fits no sheet | `not_found` with the sheets of the same number |
+| Structured content of another sheet | `unexpected_response` |
+| Portal answers with an HTTP error (blocked address, overload) | `refused` with `status` |
+| Portal shows its notice that it refuses retrievals from this address | `refused` with its words in `portalMessage` |
+| Portal too slow, unreachable, or call aborted | `timeout`, `unreachable`, `aborted` |
+| Portal changed its pages or answered in another language | `unexpected_response`, with the portal's own message in `portalMessage` when it showed one |
+| Structured content that cannot be read | `invalid_structured_content` |
 
-// Production
-const openDataProd = new OpenData({
-  nogitDir: '/var/lib/myapp/data',
-  downloadDir: '/var/lib/myapp/data/downloads',
-  germanBusinessDataDir: '/var/lib/myapp/data/germanbusinessdata'
-});
-```
+Errors of the client carry `countedRequests` and the `step` that failed, so you can say whether a request may have counted even when its answer did not arrive. Error messages contain no register data.
 
-### Environment Variables
+#### Parsing without a request
 
-Set environment variables for API keys and database:
+```ts
+import { parseStructuredContent } from '@fin.cx/opendata/handelsregister';
 
-```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)
-
-**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());
+// an SI file a person downloaded from the portal themselves
+const content = parseStructuredContent(xmlText);
 ```
 
-## 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
+## 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()`
+
+### `HandelsregisterClient` (`@fin.cx/opendata/handelsregister`)
+
+- `new HandelsregisterClient({ gate, portalUrl?, userAgent?, requestTimeoutMs?, maxResponseBytes?, now? })`
+- `search(query, { signal? })`
+- `getEntry({ courtCode, type, number }, { signal? })`
+
+### `SlidingWindowGate`
+
+- `new SlidingWindowGate({ limit?, windowMs?, now? })`
+- `acquire({ kind })`
+- `remaining()`
+- `nextAllowedAt()`
+
+### Register helpers
+
+- `parseStructuredContent(xml)`
+- `parseSearchResults(html)`
+- `registerCourts`
+- `findRegisterCourt(codeOrName)`
+- `parseRegisterReferenceText(text)`
+- `parseRegisterNumber(text)`
+- `formatRegisterReference(reference)`
+- `structuredContentNotice`
+
+## Data Sources
+
+The package ships no market or register data. Prices and fundamentals come at run time from the providers you register (Marketstack, CoinGecko, SEC EDGAR), and register entries come at run time from the register portal of the federal states (handelsregister.de), one lookup at a time.
+
+The only data the package carries are the code tables that `@fin.cx/opendata/handelsregister` uses to decode the structured register content (`ts/handelsregister/data.codelists.ts`). They are official code lists, published on XRepository (https://www.xrepository.de), and were taken on 2026-09-23:
+
+| Table | Code list | Issued by |
+| --- | --- | --- |
+| `legalFormLabels` | `urn:xoev-de:xunternehmen:codeliste:rechtsformen_2.4` (Rechtsformen) | XUnternehmen |
+| `roleLabels` | `urn:xoev-de:xjustiz:codeliste:gds.rollenbezeichnung_3.6` (GDS.Rollenbezeichnung) | BLK-AG IT-Standards in der Justiz |
+| `entityStatusLabels` | `urn:xoev-de:xjustiz:codeliste:reg.status-rechtstraeger_2.0` (REG.Status_Rechtstraeger) | BLK-AG IT-Standards in der Justiz |
+| `stateKeyToIso` | `urn:xoev-de:bund:bfj:codeliste:bfj.staat_7.0` (BfJ Staat) | Bundesamt für Justiz, Bonn |
+| `registerCourts` | the register courts of the portal's search form, with their codes from `urn:xoev-de:xjustiz:codeliste:gds.gerichte` | BLK-AG IT-Standards in der Justiz |
+
+Codes and designations are reproduced as published, without changes. The tables hold a selection of each list, never an edited entry:
+
+- `legalFormLabels`: the concrete legal forms that one of the justice registers can carry, with the short and the long designation;
+- `roleLabels`: the 71 roles that occur in register content;
+- `entityStatusLabels`: the whole list;
+- `stateKeyToIso`: the key and the ISO 3166-1 alpha-2 code of each state or territory that has one;
+- `registerCourts`: the 150 register courts as the portal's search form named them on the same day.
+
+A later version of a code list may add codes. The parser keeps a code it does not know as a code, without a designation, and never guesses one.
+
+## 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.
+- The register lookup reads the portal's German pages and asks for German explicitly. It depends on the portal's current page structure: when that changes, calls end in `unexpected_response` rather than in guessed data.
+- The structured register content is a non-binding service of the portal; the current printout is binding. Results carry `binding: false` and the portal's note.
+- 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 market data tests hit live remote services, so they may depend on network access or optional API credentials. The register lookup is tested against minimal hand-written pages and structured content with synthetic values only; the tests never contact the register portal.
 
 ## 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.