@fin.cx/opendata 4.0.0 → 4.2.0

package/readme.md

@@ -1,12 +1,14 @@
 # @fin.cx/opendata
 
-`@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.
+`@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, the statutory public holidays of the German federal states, and the base rate of § 247 BGB. It is built for programmers who want scriptable APIs and real workflows instead of a thin wrapper around one remote endpoint.
 
-It gives you three practical lanes in one package:
+It gives you five 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
+- 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
+- the base rate, from `@fin.cx/opendata/baserate`, for the Basiszinssatz of § 247 BGB per half-year as the Deutsche Bundesbank publishes it, for default interest under § 288 BGB
 
 ## Issue Reporting and Security
 
@@ -48,6 +50,26 @@ Everything here comes from `@fin.cx/opendata/handelsregister`. That entry point
 - `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`).
 
+### 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()`
+
+### The Base Rate Of § 247 BGB
+
+Everything here comes from `@fin.cx/opendata/baserate`. That entry point imports nothing else of the package, has no dependencies, and makes no request.
+
+- `getBaseRate(date)`
+  The base rate in force on a day: its half-year period with the rate in percent a year.
+- `splitByBaseRate(from, to)`
+  A span of days split where the rate changes, as interest under § 288 BGB is computed.
+- `baseRatePeriods`, `baseRateFirstDay`, `baseRatesReadOn`, `baseRateSource`
+
 ## Before You Start
 
 - No stock or fundamentals providers are pre-registered. You must register them before calling the services.
@@ -312,6 +334,57 @@ import { parseStructuredContent } from '@fin.cx/opendata/handelsregister';
 const content = parseStructuredContent(xmlText);
 ```
 
+#### Printed court names
+
+`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.
+
+### Public Holidays
+
+```ts
+import {
+  getPublicHolidays,
+  isWorkingDay,
+  nextWorkingDay,
+  workingDayOnOrAfter,
+} from '@fin.cx/opendata/holidays';
+
+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', … }, …]
+
+isWorkingDay('2026-06-04', 'DE-HE', { regionalHolidays: 'ignore' }); // false: Fronleichnam
+nextWorkingDay('2026-04-02', 'DE-BY', { regionalHolidays: 'ignore' }); // '2026-04-07'
+
+// § 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'
+```
+
+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.
+
+#### Regional holidays
+
+Four holidays apply only in part of a state:
+
+| 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
 
 ### `StockPriceService`
@@ -375,11 +448,31 @@ const content = parseStructuredContent(xmlText);
 - `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`
+
+### Base rate (`@fin.cx/opendata/baserate`)
+
+- `getBaseRate(date)`
+- `splitByBaseRate(from, to)`
+- `baseRatePeriods`, `baseRateFirstDay`, `baseRatesReadOn`, `baseRateSource`
+- `BaseRateError` with the codes `invalid_date`, `invalid_range`, `before_first_period` and `not_published`
+
 ## 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:
+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 |
 | --- | --- | --- |
@@ -399,6 +492,31 @@ Codes and designations are reproduced as published, without changes. The tables
 
 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) |
+
+The base rate of `@fin.cx/opendata/baserate` (`ts/baserate/data.baserate.ts`) is the table "Basiszinssatz nach § 247 BGB" of the Deutsche Bundesbank (https://www.bundesbank.de/de/bundesbank/organisation/agb-und-regelungen/basiszinssatz-607820), which the Bundesbank publishes under § 247 Abs. 2 BGB, read on 2026-09-27 and reproduced unaltered: every half-year from 1 July 2002, the first row it lists, to the half-year from 1 July 2026 (1,52 %). The rate changes on 1 January and 1 July (§ 247 Abs. 1 Satz 2 BGB); a day after 31 December 2026 answers `not_published` until a release carries the next row.
+
 ## Behavior And Caveats
 
 - Historical market data is cached aggressively because it is treated as immutable.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '4.0.0',
-  description: 'Open business and financial data for TypeScript: register lookups on the German register portal (handelsregister.de) without storage, and stock and crypto prices and fundamentals from several providers.'
+  version: '4.2.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, the base rate of § 247 BGB, and stock and crypto prices and fundamentals from several providers.'
 }

package/ts/baserate/baserate.ts

@@ -0,0 +1,57 @@
+import { BaseRateError } from './classes.baserateerror.js';
+import { baseRateFirstDay, baseRatePeriods, baseRatesReadOn } from './data.baserate.js';
+import type { IBaseRatePeriod, IBaseRateSpan, TIsoDate } from './interfaces.js';
+
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+const checkDate = (dateArg: TIsoDate): void => {
+  const match = typeof dateArg === 'string' ? ISO_DATE.exec(dateArg) : null;
+  const utc = match ? new Date(Date.UTC(Number(match[1]), Number(match[2]) - 1, Number(match[3]))) : null;
+  if (!match || !utc || utc.toISOString().slice(0, 10) !== dateArg) {
+    throw new BaseRateError('invalid_date', `${JSON.stringify(dateArg)} is not a calendar date written YYYY-MM-DD.`);
+  }
+};
+
+const addDay = (dateArg: TIsoDate): TIsoDate => {
+  const utc = new Date(`${dateArg}T00:00:00Z`);
+  utc.setUTCDate(utc.getUTCDate() + 1);
+  return utc.toISOString().slice(0, 10);
+};
+
+/** The base rate in force on a day: the published period that contains it. */
+export const getBaseRate = (dateArg: TIsoDate): IBaseRatePeriod => {
+  checkDate(dateArg);
+  if (dateArg < baseRateFirstDay) {
+    throw new BaseRateError('before_first_period', `${dateArg} lies before ${baseRateFirstDay}, the first day of the Bundesbank's table.`);
+  }
+  const period = baseRatePeriods.find((periodArg) => periodArg.validFrom <= dateArg && dateArg <= periodArg.validTo);
+  if (!period) {
+    throw new BaseRateError(
+      'not_published',
+      `${dateArg} lies after ${baseRatePeriods[baseRatePeriods.length - 1].validTo}; the base rate of its half-year was not published when the table was read on ${baseRatesReadOn}.`,
+    );
+  }
+  return period;
+};
+
+/**
+ * A span of days, both inclusive, split where the base rate changes: one piece per published
+ * period it touches, oldest first. Interest under § 288 BGB is computed per piece, since the rate
+ * of each half-year applies to the days in it.
+ */
+export const splitByBaseRate = (fromArg: TIsoDate, toArg: TIsoDate): IBaseRateSpan[] => {
+  checkDate(fromArg);
+  checkDate(toArg);
+  if (toArg < fromArg) {
+    throw new BaseRateError('invalid_range', `${toArg} lies before ${fromArg}.`);
+  }
+  const spans: IBaseRateSpan[] = [];
+  let day = fromArg;
+  while (day <= toArg) {
+    const period = getBaseRate(day);
+    const to = period.validTo < toArg ? period.validTo : toArg;
+    spans.push({ from: day, to, ratePercent: period.ratePercent });
+    day = addDay(to);
+  }
+  return spans;
+};

package/ts/baserate/classes.baserateerror.ts

@@ -0,0 +1,20 @@
+/**
+ * Why a question to the base-rate table was refused:
+ * - `invalid_date`: the value is not a calendar date written `YYYY-MM-DD`;
+ * - `invalid_range`: a span ends before it begins;
+ * - `before_first_period`: the day lies before the first period the table holds (1 July 2002);
+ * - `not_published`: the day lies after the half-year of the last period the table holds, whose
+ *   rate the Bundesbank had not published when the table was read (`baseRatesReadOn`).
+ */
+export type TBaseRateErrorCode = 'invalid_date' | 'invalid_range' | 'before_first_period' | 'not_published';
+
+/** The typed error of the base-rate table. */
+export class BaseRateError extends Error {
+  public readonly code: TBaseRateErrorCode;
+
+  constructor(code: TBaseRateErrorCode, message: string) {
+    super(message);
+    this.name = 'BaseRateError';
+    this.code = code;
+  }
+}

package/ts/baserate/data.baserate.ts

@@ -0,0 +1,81 @@
+/**
+ * The base rate (Basiszinssatz) of § 247 BGB, as the Deutsche Bundesbank publishes it: "Gemäß
+ * § 247 Abs. 2 BGB ist die Deutsche Bundesbank verpflichtet, den aktuellen Stand des
+ * Basiszinssatzes im Bundesanzeiger zu veröffentlichen." It changes on 1 January and 1 July
+ * (§ 247 Abs. 1 Satz 2 BGB). The table below is the Bundesbank's table "Basiszinssatz nach § 247
+ * BGB" (https://www.bundesbank.de/de/bundesbank/organisation/agb-und-regelungen/basiszinssatz-607820),
+ * read on 2026-09-27, unaltered: every row from 1 July 2002, the first one it lists, to the
+ * current one. A later half-year needs a new release.
+ */
+import type { IBaseRatePeriod } from './interfaces.js';
+
+/** the first day the table answers for */
+export const baseRateFirstDay = '2002-07-01';
+
+/** the day the Bundesbank's table was read; later half-years need a new release */
+export const baseRatesReadOn = '2026-09-27';
+
+/** the page the table was read from */
+export const baseRateSource = 'https://www.bundesbank.de/de/bundesbank/organisation/agb-und-regelungen/basiszinssatz-607820';
+
+const rows: ReadonlyArray<readonly [string, number]> = [
+  // gültig ab, Basiszinssatz in Prozent, as the table of the Deutsche Bundesbank states them
+  ['2002-07-01', 2.47],
+  ['2003-01-01', 1.97],
+  ['2003-07-01', 1.22],
+  ['2004-01-01', 1.14],
+  ['2004-07-01', 1.13],
+  ['2005-01-01', 1.21],
+  ['2005-07-01', 1.17],
+  ['2006-01-01', 1.37],
+  ['2006-07-01', 1.95],
+  ['2007-01-01', 2.70],
+  ['2007-07-01', 3.19],
+  ['2008-01-01', 3.32],
+  ['2008-07-01', 3.19],
+  ['2009-01-01', 1.62],
+  ['2009-07-01', 0.12],
+  ['2010-01-01', 0.12],
+  ['2010-07-01', 0.12],
+  ['2011-01-01', 0.12],
+  ['2011-07-01', 0.37],
+  ['2012-01-01', 0.12],
+  ['2012-07-01', 0.12],
+  ['2013-01-01', -0.13],
+  ['2013-07-01', -0.38],
+  ['2014-01-01', -0.63],
+  ['2014-07-01', -0.73],
+  ['2015-01-01', -0.83],
+  ['2015-07-01', -0.83],
+  ['2016-01-01', -0.83],
+  ['2016-07-01', -0.88],
+  ['2017-01-01', -0.88],
+  ['2017-07-01', -0.88],
+  ['2018-01-01', -0.88],
+  ['2018-07-01', -0.88],
+  ['2019-01-01', -0.88],
+  ['2019-07-01', -0.88],
+  ['2020-01-01', -0.88],
+  ['2020-07-01', -0.88],
+  ['2021-01-01', -0.88],
+  ['2021-07-01', -0.88],
+  ['2022-01-01', -0.88],
+  ['2022-07-01', -0.88],
+  ['2023-01-01', 1.62],
+  ['2023-07-01', 3.12],
+  ['2024-01-01', 3.62],
+  ['2024-07-01', 3.37],
+  ['2025-01-01', 2.27],
+  ['2025-07-01', 1.27],
+  ['2026-01-01', 1.27],
+  ['2026-07-01', 1.52],
+];
+
+/** the last day of the half-year a period begins in */
+const halfYearEndOf = (validFromArg: string): string =>
+  `${validFromArg.slice(0, 4)}-${validFromArg.slice(5, 7) === '01' ? '06-30' : '12-31'}`;
+
+/** every published period, oldest first */
+export const baseRatePeriods: readonly IBaseRatePeriod[] = Object.freeze(
+  rows.map(([validFrom, ratePercent]) => Object.freeze({ validFrom, validTo: halfYearEndOf(validFrom), ratePercent })),
+);

package/ts/baserate/index.ts

@@ -0,0 +1,6 @@
+// This entry point stands alone: it imports nothing from the rest of the package, has no
+// dependencies and needs no storage or network.
+export * from './interfaces.js';
+export { BaseRateError, type TBaseRateErrorCode } from './classes.baserateerror.js';
+export { baseRateFirstDay, baseRatePeriods, baseRateSource, baseRatesReadOn } from './data.baserate.js';
+export { getBaseRate, splitByBaseRate } from './baserate.js';

package/ts/baserate/interfaces.ts

@@ -0,0 +1,21 @@
+/** A plain calendar date, `YYYY-MM-DD`. */
+export type TIsoDate = string;
+
+/**
+ * One half-year's base rate (Basiszinssatz, § 247 BGB) as the Deutsche
+ * Bundesbank publishes it: valid from 1 January or 1 July to the last day of
+ * that half-year, both inclusive.
+ */
+export interface IBaseRatePeriod {
+  validFrom: TIsoDate;
+  validTo: TIsoDate;
+  /** percent a year; it can be negative (2013 to 2022) */
+  ratePercent: number;
+}
+
+/** A span of days within one base-rate period, both days inclusive. */
+export interface IBaseRateSpan {
+  from: TIsoDate;
+  to: TIsoDate;
+  ratePercent: number;
+}

package/ts/handelsregister/references.ts

@@ -21,25 +21,103 @@ export interface IParsedRegisterReferenceText {
 
 const collapse = (textArg: string): string => textArg.replace(/\s+/g, ' ').trim();
 
-const courtKey = (textArg: string): string =>
-  collapse(textArg)
-    .replace(/^(?:amtsgericht|registergericht|ag)\s+/i, '')
-    .toLocaleLowerCase('de-DE');
+/** German letters as a text without them spells them: `Muenchen` is `München` */
+const spelledOut: Readonly<Record<string, string>> = { 'ä': 'ae', 'ö': 'oe', 'ü': 'ue', 'ß': 'ss' };
 
-/** the alternative name the portal puts in brackets: `Berlin (Charlottenburg)` → `charlottenburg` */
-const courtAliasKey = (nameArg: string): string | undefined => {
-  const bracket = /\(([^()]+)\)\s*$/.exec(nameArg);
-  return bracket ? courtKey(bracket[1]) : undefined;
+/** words that name a court or a register rather than its place */
+const courtWords: ReadonlySet<string> = new Set([
+  'amtsgericht',
+  'amtsgerichts',
+  'ag',
+  'registergericht',
+  'registergerichts',
+  'handelsregister',
+  'genossenschaftsregister',
+  'partnerschaftsregister',
+  'vereinsregister',
+  'gesellschaftsregister',
+  'abteilung',
+  'beim',
+  'bei',
+  'des',
+]);
+
+/**
+ * The place a printed court name names, as courts are compared: lower case, German letters spelled
+ * out, punctuation as spaces, and without the words that name a court or a register or the
+ * division of the commercial register. `Handelsregister B des Amtsgerichts Frankfurt a. M.` is
+ * `frankfurt a m`.
+ */
+const placeKey = (textArg: string): string => {
+  const words = textArg
+    .normalize('NFC')
+    .toLocaleLowerCase('de-DE')
+    .replace(/[äöüß]/g, (letterArg) => spelledOut[letterArg] ?? letterArg)
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter((wordArg) => wordArg !== '');
+  return words
+    .filter((wordArg, indexArg) => {
+      const previous = words[indexArg - 1];
+      const division = (previous === 'handelsregister' || previous === 'abteilung') && (wordArg === 'a' || wordArg === 'b');
+      return !courtWords.has(wordArg) && !division;
+    })
+    .join(' ');
 };
 
 /**
- * Finds a register court by its code or its name: `H1101`, `Bremen`, `Amtsgericht Bremen`,
- * `Berlin (Charlottenburg)` or `Charlottenburg`. Returns undefined unless exactly one court fits.
+ * Other names under which the register courts are printed, for courts whose name in the official
+ * list carries a qualifier that prints leave out, abbreviate or spell out. Each name here is a name
+ * of that court alone. `Frankfurt` without `am Main` or `(Oder)` is a name of neither of the two.
+ */
+const printedCourtNames: Readonly<Record<string, readonly string[]>> = {
+  'Bad Homburg v.d.H.': ['Bad Homburg', 'Bad Homburg vor der Höhe', 'Bad Homburg v. d. Höhe'],
+  'Berlin (Charlottenburg)': ['Berlin', 'Charlottenburg', 'Charlottenburg (Berlin)'],
+  'Frankfurt am Main': ['Frankfurt a. M.', 'Frankfurt a. Main', 'Frankfurt/M.', 'Frankfurt/Main', 'Frankfurt (Main)'],
+  'Frankfurt (Oder)': ['Frankfurt/O.', 'Frankfurt a. d. O.', 'Frankfurt an der Oder', 'Frankfurt a. d. Oder'],
+  'Freiburg': ['Freiburg im Breisgau', 'Freiburg i. Br.', 'Freiburg/Breisgau', 'Freiburg (Breisgau)'],
+  'Kempten (Allgäu)': ['Kempten'],
+  'Königstein': ['Königstein im Taunus', 'Königstein i. Ts.'],
+  'Landau': ['Landau in der Pfalz', 'Landau i. d. Pfalz', 'Landau/Pfalz'],
+  'Limburg': ['Limburg an der Lahn', 'Limburg a. d. Lahn'],
+  'Ludwigshafen a.Rhein (Ludwigshafen)': ['Ludwigshafen', 'Ludwigshafen am Rhein'],
+  'Offenbach am Main': ['Offenbach', 'Offenbach a. M.'],
+  'Oldenburg (Oldenburg)': ['Oldenburg', 'Oldenburg (Oldb.)', 'Oldenburg i. O.'],
+  'St. Ingbert (St Ingbert)': ['St. Ingbert', 'Sankt Ingbert'],
+  'St. Wendel (St Wendel)': ['St. Wendel', 'Sankt Wendel'],
+  'Weiden i. d. OPf.': ['Weiden', 'Weiden in der Oberpfalz'],
+};
+
+/** every place key of a list of courts with the courts it names */
+const courtsByPlaceKey = (courtsArg: readonly IRegisterCourt[]): ReadonlyMap<string, readonly IRegisterCourt[]> => {
+  const byKey = new Map<string, IRegisterCourt[]>();
+  for (const court of courtsArg) {
+    const keys = new Set([court.name, ...(printedCourtNames[court.name] ?? [])].map(placeKey));
+    for (const key of keys) {
+      if (key !== '') {
+        byKey.set(key, [...(byKey.get(key) ?? []), court]);
+      }
+    }
+  }
+  return byKey;
+};
+
+let officialCourtKeys: ReadonlyMap<string, readonly IRegisterCourt[]> | undefined;
+
+/**
+ * Finds a register court by its code or by its name as the portal or a business prints it: `H1101`,
+ * `Bremen`, `AG Bremen`, `Amtsgericht Bremen – Registergericht`, `Registergericht Bremen`,
+ * `Handelsregister B des Amtsgerichts Bremen`, `Amtsgericht Frankfurt a. M.`, `Frankfurt (Oder)`,
+ * `Kempten (Allgäu)` or `Kempten`, `Freiburg i. Br.`, `AG Berlin` or `Charlottenburg`. Umlauts may
+ * be spelled out (`Muenchen`). Returns undefined unless exactly one court fits: a place the list
+ * does not know, and `Frankfurt` alone, name no court.
  */
 export const findRegisterCourt = (
   codeOrNameArg: string,
   courtsArg: readonly IRegisterCourt[] = registerCourts
 ): IRegisterCourt | undefined => {
+  if (typeof codeOrNameArg !== 'string') {
+    return undefined;
+  }
   const text = collapse(codeOrNameArg);
   if (!text) {
     return undefined;
@@ -48,16 +126,12 @@ export const findRegisterCourt = (
   if (byCode) {
     return byCode;
   }
-  const key = courtKey(text);
-  const byName = courtsArg.filter((courtArg) => courtKey(courtArg.name) === key);
-  if (byName.length === 1) {
-    return byName[0];
-  }
-  if (byName.length > 1) {
-    return undefined;
-  }
-  const byAlias = courtsArg.filter((courtArg) => courtAliasKey(courtArg.name) === key);
-  return byAlias.length === 1 ? byAlias[0] : undefined;
+  const keys =
+    courtsArg === registerCourts
+      ? (officialCourtKeys ??= courtsByPlaceKey(registerCourts))
+      : courtsByPlaceKey(courtsArg);
+  const courts = keys.get(placeKey(text)) ?? [];
+  return courts.length === 1 ? courts[0] : undefined;
 };
 
 /** returns the canonical register type for `hrb`, `HRB`, `gnr` …, or undefined */