@fin.cx/opendata 3.6.0 → 4.1.0

package/readme.md

@@ -1,13 +1,13 @@
 # @fin.cx/opendata
 
-`@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.
+`@fin.cx/opendata` is a TypeScript toolbox for open business and market data: stock and crypto prices, SEC fundamentals, lookups in the German registers through the register portal of the federal states, and the statutory public holidays of the German federal states. It is built for programmers who want scriptable APIs and real workflows instead of a thin wrapper around one remote endpoint.
 
-It currently gives you four practical lanes in one package:
+It 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
+- `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
+- the holiday calendar, from `@fin.cx/opendata/holidays`, for the statutory public holidays of each German federal state and the working days of § 193 BGB, computed per year without data files or requests
 
 ## Issue Reporting and Security
 
@@ -36,17 +36,28 @@ pnpm add @fin.cx/opendata
 - `SecEdgarProvider`
   Fundamentals provider backed by SEC EDGAR company facts.
 
-### German Company Data
+### German Registers
 
-- `OpenData`
-  Starts a local embedded database, imports the public German company JSONL dump, and exposes a `handelsregister` helper for company lookup and file download.
+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.
 
-### Laws
+- `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`).
 
-- `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.
+### German Public Holidays
+
+Everything here comes from `@fin.cx/opendata/holidays`. That entry point imports nothing else of the package, has no dependencies, and makes no request.
+
+- `getPublicHolidays(year, state)`, `getPublicHolidaysOn(date, state)`
+  The statutory public holidays of a federal state in a year or on a date, each with its legal basis.
+- `isPublicHoliday()`, `isWorkingDay()`, `nextWorkingDay()`, `workingDayOnOrAfter()`
+  Holidays and working days in the sense of § 193 BGB: neither a Saturday, nor a Sunday, nor a statutory public holiday.
+- `easterSunday(year)`, `germanStates`, `findGermanState()`
 
 ## Before You Start
 
@@ -54,10 +65,8 @@ pnpm add @fin.cx/opendata
 - `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.
+- `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.
 
 ## Quick Start
@@ -194,118 +203,176 @@ console.log({
 });
 ```
 
-### German Company Data And Handelsregister Automation
+### Register Lookups (Handelsregister)
 
-`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.
+`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.
 
 ```ts
-import { OpenData } from '@fin.cx/opendata';
-import * as path from 'node:path';
+import {
+  HandelsregisterClient,
+  HandelsregisterError,
+  SlidingWindowGate,
+  findRegisterCourt,
+  formatRegisterReference,
+} from '@fin.cx/opendata/handelsregister';
+
+// one gate for the whole installation: 60 searches or retrievals per hour
+const gate = new SlidingWindowGate();
+
+const register = new HandelsregisterClient({
+  gate,
+  userAgent: 'Example Books (+https://example.com/contact)',
+});
 
-const nogitDir = path.join(process.cwd(), '.nogit');
+// 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
+}
+
+// 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
+    };
+  }
+}
+
+// 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());
+  }
+}
+```
 
-const openData = new OpenData({
-  nogitDir,
-  downloadDir: path.join(nogitDir, 'downloads'),
-  germanBusinessDataDir: path.join(nogitDir, 'germanbusinessdata'),
-});
+Searches take a name or a register number:
 
-await openData.start();
+- `{ 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.
 
-const matches = await openData.handelsregister.searchCompany('Siemens AG', 20);
+`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.
 
-const company = await openData.handelsregister.getSpecificCompany({
-  court: 'Munich',
-  type: 'HRB',
-  number: '6684',
-});
+#### What counts against the 60 per hour
 
-console.log({
-  searchHits: matches.length,
-  downloadedFiles: company.files.map((file) => file.path),
-});
+| 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 |
 
-await openData.stop();
-```
+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.
 
-Useful `OpenData` workflows today:
+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.
 
-- `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)`
+#### What a result holds
 
-The download workflow currently fetches the Handelsregister files into a temporary folder and returns the files to you as `SmartFile` objects.
+- `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.
 
-### Law Syncing And Search
+#### What can happen
 
-`LawService` stores synced laws in a local embedded database and supports three jurisdictions:
+| 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` |
 
-- Germany via `gesetze-im-internet`
-- EU via `EUR-Lex`
-- US via GovInfo and Cornell LII
+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.
+
+#### Parsing without a request
 
 ```ts
-import { LawService } from '@fin.cx/opendata';
+import { parseStructuredContent } from '@fin.cx/opendata/handelsregister';
 
-const laws = new LawService({
-  dbFolderPath: '.nogit/law-smartdb',
-  dbName: 'laws',
-  govInfoApiKey: process.env.GOVINFO_API_KEY,
-});
+// an SI file a person downloaded from the portal themselves
+const content = parseStructuredContent(xmlText);
+```
 
-await laws.start();
+#### Printed court names
 
-const germanLaw = await laws.syncLaw({
-  jurisdiction: 'de',
-  identifier: 'aeg',
-});
+`findRegisterCourt()` takes a court's code or its name as the portal or a business prints it: `AG Bremen`, `Amtsgericht Bremen – Registergericht`, `Registergericht Bremen`, `Handelsregister B des Amtsgerichts Bremen`, `Amtsgericht Frankfurt a. M.`, `Frankfurt/O.`, `Kempten` for `Kempten (Allgäu)`, `Freiburg i. Br.`, and `AG Berlin` or `Charlottenburg` for the register court of Berlin. Umlauts may be spelled out (`Muenchen`). It returns a court only when exactly one fits: `Frankfurt` alone could be either Frankfurt am Main or Frankfurt (Oder) and names no court.
 
-const euLaw = await laws.syncLaw({
-  jurisdiction: 'eu',
-  identifier: '32024R1689',
-  language: 'EN',
-});
+### Public Holidays
 
-const usCode = await laws.syncLaw({
-  jurisdiction: 'us',
-  identifier: '8 U.S.C. § 1226',
-});
+```ts
+import {
+  getPublicHolidays,
+  isWorkingDay,
+  nextWorkingDay,
+  workingDayOnOrAfter,
+} from '@fin.cx/opendata/holidays';
 
-const results = await laws.searchLaws({
-  jurisdiction: 'eu',
-  query: 'Artificial Intelligence Act',
-  limit: 5,
-});
+getPublicHolidays(2026, 'DE-NI');
+// [{ date: '2026-01-01', id: 'neujahr', name: 'Neujahr', state: 'DE-NI', scope: 'state',
+//    legalBasis: '§ 2 Abs. 1 NFeiertagsG' }, …, { date: '2026-10-31', id: 'reformationstag', … }, …]
 
-console.log({
-  germany: germanLaw.title,
-  eu: euLaw.title,
-  us: usCode.title,
-  hits: results.length,
-});
+isWorkingDay('2026-06-04', 'DE-HE', { regionalHolidays: 'ignore' }); // false: Fronleichnam
+nextWorkingDay('2026-04-02', 'DE-BY', { regionalHolidays: 'ignore' }); // '2026-04-07'
 
-await laws.stop();
+// § 193 BGB: a deadline that ends on a Saturday, Sunday or holiday ends on the next working day
+workingDayOnOrAfter('2026-05-14', 'DE-BY', { regionalHolidays: 'ignore' }); // '2026-05-15'
 ```
 
-`LawService` also supports bulk sync:
+States are ISO 3166-2 codes (`DE-BY`); `findGermanState('Bayern')` and `findGermanState('BY')` find one. Dates are plain calendar dates written `YYYY-MM-DD`, so no time zone can move them.
 
-```ts
-await laws.syncLaws({
-  jurisdiction: 'us',
-  usCollection: 'PLAW',
-  limit: 25,
-  since: new Date('2025-01-01'),
-});
-```
+#### Regional holidays
 
-Useful request patterns:
+Four holidays apply only in part of a state:
 
-- 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'`
+| Holiday | State | Where | Legal basis |
+| --- | --- | --- | --- |
+| Augsburger Friedensfest (8 August) | Bayern | Stadt Augsburg | Art. 1 Abs. 2 FTG |
+| Mariä Himmelfahrt (15 August) | Bayern | municipalities with a predominantly Catholic population, as the Bayerisches Landesamt für Statistik determines them after the last census | Art. 1 Abs. 1 Nr. 2, Abs. 3 FTG |
+| Fronleichnam | Sachsen | the municipalities listed in the annex of the FronleichnamsVO (former districts Bautzen, Hoyerswerda and Kamenz), after a merger only the respective part of the municipality | § 1 Abs. 1 SächsSFG, § 1 FronleichnamsVO |
+| Fronleichnam | Thüringen | the parts of Thüringen where Fronleichnam was a statutory holiday in 1994 | § 2 Abs. 2, § 10 Abs. 1 ThürFGtG |
+
+`getPublicHolidays()` lists them with `scope: 'regional'` and the `region` they apply to. The calendar holds no list of these municipalities: the Bavarian list follows the census and the Saxon and Thuringian ones name parts of municipalities, so a place cannot be matched to them reliably by a key. Every working-day question therefore says how to treat them:
+
+- `{ regionalHolidays: 'count' }` treats them as holidays. A period then never ends on a day that is a holiday at the place in question, at the price of ending one day later where it is not. Use it when the place is unknown.
+- `{ regionalHolidays: 'ignore' }` treats them as working days, when the place is known to lie outside that part.
+
+#### What the calendar covers
+
+- The statutory public holidays of the 16 federal states from 2018 on, and 3 October from Art. 2 Abs. 2 of the Unification Treaty. Every change since 2018 applies from its year: Reformationstag in Bremen, Hamburg, Niedersachsen and Schleswig-Holstein (2018), Frauentag in Berlin (2019) and Mecklenburg-Vorpommern (2023), Weltkindertag in Thüringen (2019), and the one-off holidays of Berlin on 8 May 2020, 8 May 2025 and 17 June 2028. Years before 2018 end in `HolidayCalendarError` with the code `unsupported_year`.
+- Later years follow the laws as they stood when this version read them (`holidayLawsReadOn`). Several states allow their government to declare one-off holidays by ordinance; one declared after that day needs a new version.
+- The Easter-based holidays follow Easter Sunday of the Gregorian calendar; Buß- und Bettag (Sachsen) is the Wednesday before the last Sunday before the first Sunday of Advent.
+- The laws of Berlin and Hessen also count every Sunday as a public holiday, and Brandenburg names Ostersonntag and Pfingstsonntag. The calendar lists the Sundays Brandenburg names; for working days every Sunday is excluded anyway.
+- Religious holidays that protect only church services or give employees time off (for example Fronleichnam outside its region in Sachsen, § 3 SächsSFG) and memorial days (Gedenktage) are no statutory public holidays and are not listed.
 
 ## API At A Glance
 
@@ -346,33 +413,97 @@ Useful request patterns:
 - `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? })`
+### `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`
+
+### Holiday calendar (`@fin.cx/opendata/holidays`)
+
+- `getPublicHolidays(year, state)`
+- `getPublicHolidaysOn(date, state)`
+- `isPublicHoliday(date, state, { regionalHolidays })`
+- `isWorkingDay(date, state, { regionalHolidays })`
+- `nextWorkingDay(date, state, { regionalHolidays })`
+- `workingDayOnOrAfter(date, state, { regionalHolidays })`
+- `easterSunday(year)`
+- `germanStates`, `findGermanState(codeOrName)`
+- `holidayCalendarFirstYear`, `holidayLawsReadOn`
+- `HolidayCalendarError` with the codes `invalid_date`, `unsupported_year`, `unknown_state` and `invalid_options`
+
+## 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 package carries two kinds of data: the holiday rules of `@fin.cx/opendata/holidays` (`ts/holidays/data.holidays.ts`), described at the end of this section, and the code tables that `@fin.cx/opendata/handelsregister` uses to decode the structured register content (`ts/handelsregister/data.codelists.ts`). The code tables 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.
+
+The holiday calendar is derived from the holiday laws of the federal states, read on 2026-09-24 in their official portals, from Art. 2 Abs. 2 of the Unification Treaty for 3 October, and it answers the question of § 193 BGB:
+
+| State | Law | Provision |
+| --- | --- | --- |
+| all | [Einigungsvertrag](https://www.gesetze-im-internet.de/einigvtr/art_2.html) | Art. 2 Abs. 2 (Tag der Deutschen Einheit) |
+| Baden-Württemberg | [Feiertagsgesetz (FTG)](https://www.landesrecht-bw.de/perma?j=FeiertG_BW_!_1) | § 1 |
+| Bayern | [Feiertagsgesetz (FTG)](https://www.gesetze-bayern.de/Content/Document/BayFTG-1) | Art. 1 |
+| Berlin | [Gesetz über die Sonn- und Feiertage](https://gesetze.berlin.de/perma?j=FeiertG_BE_!_1) | § 1 Abs. 1 |
+| Brandenburg | [Feiertagsgesetz (FTG)](https://bravors.brandenburg.de/gesetze/ftg_2015) | § 2 Abs. 1 |
+| Bremen | [Gesetz über die Sonn-, Gedenk- und Feiertage](https://www.transparenz.bremen.de/sixcms/detail.php?gsid=bremen2014_tp.c.145882.de) | § 2 Abs. 1 |
+| Hamburg | [Feiertagsgesetz](https://www.landesrecht-hamburg.de/perma?d=jlr-NNLHH00006CB9NN00000000002) | § 1 |
+| Hessen | [Hessisches Feiertagsgesetz (HFeiertagsG)](https://www.rv.hessenrecht.hessen.de/perma?j=FeiertG_HE_!_1) | § 1 Abs. 1 |
+| Mecklenburg-Vorpommern | [Feiertagsgesetz (FTG M-V)](https://www.landesrecht-mv.de/perma?d=jlr-NNLMV00007A2FNN00000000003) | § 2 Abs. 1 |
+| Niedersachsen | [Niedersächsisches Gesetz über die Feiertage (NFeiertagsG)](https://voris.wolterskluwer-online.de/browse/document/f74bc6e7-6ded-3c2c-9afb-b34620456e56) | § 2 Abs. 1 |
+| Nordrhein-Westfalen | [Gesetz über die Sonn- und Feiertage (Feiertagsgesetz NW)](https://recht.nrw.de/lrgv/gesetz/01012000-bekanntmachung-der-neufassung-des-gesetzes-ueber-die-sonn-und-feiertage) | § 2 Abs. 1 |
+| Rheinland-Pfalz | [Feiertagsgesetz (LFtG)](https://landesrecht.rlp.de/perma?d=jlr-NNLRP00006125NN00000000004) | § 2 Abs. 1 |
+| Saarland | [Feiertagsgesetz (SFG)](https://recht.saarland.de/perma?d=jlr-NNLSL0000A2D6NN00000000007) | § 2 Abs. 1 |
+| Sachsen | [Sächsisches Sonn- und Feiertagsgesetz (SächsSFG)](https://www.revosax.sachsen.de/vorschrift/3997-SaechsSFG), [FronleichnamsVO](https://www.revosax.sachsen.de/vorschrift/4142) | § 1 Abs. 1; § 1 and annex |
+| Sachsen-Anhalt | [Gesetz über die Sonn- und Feiertage (FeiertG LSA)](https://www.landesrecht.sachsen-anhalt.de/perma?d=jlr-NNLST0000411CNN00000000003) | § 2 |
+| Schleswig-Holstein | [Gesetz über Sonn- und Feiertage (SFTG)](https://www.gesetze-rechtsprechung.sh.juris.de/perma?j=FeiertG_SH_!_2) | § 2 Abs. 1 |
+| Thüringen | [Thüringer Feier- und Gedenktagsgesetz (ThürFGtG)](https://landesrecht.thueringen.de/perma?j=FeiertG_TH_!_2) | § 2, § 10 Abs. 1 |
+| all | [Bürgerliches Gesetzbuch](https://www.gesetze-im-internet.de/bgb/__193.html) | § 193 (Sonntag, Feiertag, Sonnabend) |
 
 ## 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.
+- 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
@@ -381,7 +512,7 @@ Useful request patterns:
 pnpm test
 ```
 
-Some tests hit live remote services, so they may depend on network access, optional API credentials, or browser automation support.
+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
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '3.6.0',
-  description: 'A comprehensive TypeScript library for accessing business data and real-time financial information. Features include German company data management with MongoDB integration, JSONL bulk processing, automated Handelsregister interactions, and real-time stock market data from multiple providers.'
+  version: '4.1.0',
+  description: 'Open business and financial data for TypeScript: register lookups on the German register portal (handelsregister.de) without storage, the statutory public holidays of the German federal states, and stock and crypto prices and fundamentals from several providers.'
 }