@fin.cx/opendata 4.5.0 → 4.6.0

package/readme.md

@@ -7,7 +7,7 @@ It gives you seven 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 holiday calendar, from `@fin.cx/opendata/holidays`, for the statutory public holidays of each German federal state, the working days of § 193 BGB and the bank working days the social insurance counts its due dates in, 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
 - VAT ID confirmation, from `@fin.cx/opendata/vatid`, over the BZSt's eVatR REST API (the confirmation of § 18e UStG, simple or qualified) and the European Commission's VIES REST API, without any storage
 - the consumer price index, from `@fin.cx/opendata/cpi`, for the Verbraucherpreisindex für Deutschland of the Statistisches Bundesamt as the Deutsche Bundesbank republishes it, with the arithmetic of index clauses (Wertsicherungsklauseln, § 557b BGB), without any storage
@@ -60,6 +60,8 @@ Everything here comes from `@fin.cx/opendata/holidays`. That entry point imports
   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.
+- `isBankWorkingDay()`, `nthLastBankWorkingDay()`
+  Bank working days (Bankarbeitstage), which also leave out 24 and 31 December, when the Deutsche Bundesbank is closed: the days German social insurance due dates are counted in.
 - `easterSunday(year)`, `germanStates`, `findGermanState()`
 
 ### The Base Rate Of § 247 BGB
@@ -468,6 +470,24 @@ workingDayOnOrAfter('2026-05-14', 'DE-BY', { regionalHolidays: 'ignore' }); // '
 
 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.
 
+#### Bank working days
+
+A bank working day (Bankarbeitstag) is neither a Saturday, nor a Sunday, nor a statutory public holiday, nor 24 or 31 December. On those two days the Deutsche Bundesbank is closed although they are no statutory holidays; its list of holidays names them as its additional closing days. German social insurance counts its due dates in these days, with the holidays of the state where the collecting agency (Einzugsstelle) has its seat: contributions are due on the third-last bank working day of the month, and the contribution statement has to be with the collecting agency at the start of the fifth-last.
+
+```ts
+import { isBankWorkingDay, nthLastBankWorkingDay } from '@fin.cx/opendata/holidays';
+
+isBankWorkingDay('2026-12-24', 'DE-HH', { regionalHolidays: 'ignore' }); // false: the Bundesbank is closed
+nthLastBankWorkingDay('2026-12', 3, 'DE-HH', { regionalHolidays: 'ignore' }); // '2026-12-28'
+nthLastBankWorkingDay('2026-12', 5, 'DE-HH', { regionalHolidays: 'ignore' }); // '2026-12-22'
+
+// Reformationstag 2025 was a Friday: a holiday in Niedersachsen, a working day in Bayern
+nthLastBankWorkingDay('2025-10', 3, 'DE-NI', { regionalHolidays: 'ignore' }); // '2025-10-28'
+nthLastBankWorkingDay('2025-10', 3, 'DE-BY', { regionalHolidays: 'ignore' }); // '2025-10-29'
+```
+
+Months are written `YYYY-MM`. The position counts from the end of the month, 1 being the last bank working day; a position the month does not have ends in `invalid_position`. The tests hold the results against the due dates the collecting agencies published for 2025 and 2026.
+
 #### Regional holidays
 
 Four holidays apply only in part of a state:
@@ -563,10 +583,12 @@ Four holidays apply only in part of a state:
 - `isWorkingDay(date, state, { regionalHolidays })`
 - `nextWorkingDay(date, state, { regionalHolidays })`
 - `workingDayOnOrAfter(date, state, { regionalHolidays })`
+- `isBankWorkingDay(date, state, { regionalHolidays })`
+- `nthLastBankWorkingDay(month, position, state, { regionalHolidays })`
 - `easterSunday(year)`
 - `germanStates`, `findGermanState(codeOrName)`
 - `holidayCalendarFirstYear`, `holidayLawsReadOn`
-- `HolidayCalendarError` with the codes `invalid_date`, `unsupported_year`, `unknown_state` and `invalid_options`
+- `HolidayCalendarError` with the codes `invalid_date`, `invalid_month`, `invalid_position`, `unsupported_year`, `unknown_state` and `invalid_options`
 
 ### VAT ID (`@fin.cx/opendata/vatid`)
 
@@ -635,6 +657,8 @@ The holiday calendar is derived from the holiday laws of the federal states, rea
 | 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 bank working days follow the Deutsche Bundesbank's list "Feiertage in Deutschland im Jahr 2026", read on 2026-10-08, which names 24 December (Heiligabend) and 31 December (Silvester) as its additional closing days ("Zusätzliche geschäftsfreie Tage der Deutschen Bundesbank"), and the collecting agencies' statement that these two days are no bank working days for the due dates of contributions, that a holiday counts by the seat of the collecting agency, and their published due dates of 2025 (AOK, with separate October dates for the states with and without Reformationstag) and 2026 (TK, AOK and KKH). The calendar takes the two closing days as fixed; a change of the Bundesbank's closing days needs a new version.
+
 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.
 
 The VAT ID clients of `@fin.cx/opendata/vatid` ask two official services at run time, one request at a time, read on 2026-09-27:

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '4.5.0',
+  version: '4.6.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, the German consumer price index with the arithmetic of index clauses, and stock and crypto prices and fundamentals from several providers.'
 }

package/ts/holidays/calendar.ts

@@ -7,6 +7,7 @@ import type {
   IWorkingDayOptions,
   TGermanStateCode,
   TIsoDate,
+  TIsoMonth,
 } from './interfaces.js';
 
 const dayMs = 86_400_000;
@@ -57,6 +58,17 @@ const parseIsoDate = (dateArg: TIsoDate): ICalendarDay => {
   return { year, utc };
 };
 
+const parseIsoMonth = (monthArg: TIsoMonth): { year: number; month: number } => {
+  const match = typeof monthArg === 'string' ? /^(\d{4})-(\d{2})$/.exec(monthArg) : null;
+  const month = match ? Number(match[2]) : 0;
+  if (!match || month < 1 || month > 12) {
+    throw new HolidayCalendarError('invalid_month', `A month is written YYYY-MM; ${JSON.stringify(monthArg)} is not.`);
+  }
+  const year = Number(match[1]);
+  checkYear(year);
+  return { year, month };
+};
+
 const checkState = (stateArg: TGermanStateCode): void => {
   if (!germanStates.some((stateEntry) => stateEntry.code === stateArg)) {
     throw new HolidayCalendarError(
@@ -189,6 +201,15 @@ const isWorkingDayUtc = (utcArg: number, stateArg: TGermanStateCode, optionsArg:
   return weekday !== 0 && weekday !== 6 && !isHolidayUtc(utcArg, stateArg, optionsArg);
 };
 
+/** 24 and 31 December, the days the Deutsche Bundesbank closes besides the statutory holidays */
+const isBundesbankClosingDayUtc = (utcArg: number): boolean => {
+  const date = new Date(utcArg);
+  return date.getUTCMonth() === 11 && (date.getUTCDate() === 24 || date.getUTCDate() === 31);
+};
+
+const isBankWorkingDayUtc = (utcArg: number, stateArg: TGermanStateCode, optionsArg: IWorkingDayOptions): boolean =>
+  isWorkingDayUtc(utcArg, stateArg, optionsArg) && !isBundesbankClosingDayUtc(utcArg);
+
 /** Whether a date is a statutory public holiday in a state. */
 export const isPublicHoliday = (
   dateArg: TIsoDate,
@@ -212,6 +233,58 @@ export const isWorkingDay = (dateArg: TIsoDate, stateArg: TGermanStateCode, opti
   return isWorkingDayUtc(day.utc, stateArg, optionsArg);
 };
 
+/**
+ * Whether a date is a bank working day (Bankarbeitstag) in a state: neither a Saturday, nor a
+ * Sunday, nor a statutory public holiday, nor 24 or 31 December, on which the Deutsche Bundesbank
+ * is closed. These are the days the German social insurance counts the due dates of contributions
+ * in, with the holidays of the state where the collecting agency has its seat.
+ */
+export const isBankWorkingDay = (
+  dateArg: TIsoDate,
+  stateArg: TGermanStateCode,
+  optionsArg: IWorkingDayOptions,
+): boolean => {
+  const day = parseIsoDate(dateArg);
+  checkState(stateArg);
+  checkOptions(optionsArg);
+  return isBankWorkingDayUtc(day.utc, stateArg, optionsArg);
+};
+
+/**
+ * The bank working day of a month at a position counted from the month's end: 1 is the last bank
+ * working day of the month, 3 the third-last.
+ */
+export const nthLastBankWorkingDay = (
+  monthArg: TIsoMonth,
+  positionArg: number,
+  stateArg: TGermanStateCode,
+  optionsArg: IWorkingDayOptions,
+): TIsoDate => {
+  const { year, month } = parseIsoMonth(monthArg);
+  checkState(stateArg);
+  checkOptions(optionsArg);
+  if (!Number.isInteger(positionArg) || positionArg < 1) {
+    throw new HolidayCalendarError(
+      'invalid_position',
+      `A position counted from the end of a month is a whole number from 1 on, not ${String(positionArg)}.`,
+    );
+  }
+  const first = utcOf(year, month, 1);
+  let found = 0;
+  for (let utc = utcOf(year, month + 1, 0); utc >= first; utc -= dayMs) {
+    if (isBankWorkingDayUtc(utc, stateArg, optionsArg)) {
+      found += 1;
+      if (found === positionArg) {
+        return toIsoDate(utc);
+      }
+    }
+  }
+  throw new HolidayCalendarError(
+    'invalid_position',
+    `${monthArg} has ${found} bank working days in ${stateArg}, fewer than ${positionArg}.`,
+  );
+};
+
 /** The first working day after a date (§ 193 BGB: not a Saturday, Sunday or public holiday). */
 export const nextWorkingDay = (dateArg: TIsoDate, stateArg: TGermanStateCode, optionsArg: IWorkingDayOptions): TIsoDate => {
   const day = parseIsoDate(dateArg);

package/ts/holidays/classes.holidaycalendarerror.ts

@@ -1,12 +1,21 @@
 /**
  * Why a question to the holiday calendar was refused:
  * - `invalid_date`: the value is not a calendar date written `YYYY-MM-DD`;
+ * - `invalid_month`: the value is not a calendar month written `YYYY-MM`;
+ * - `invalid_position`: the position of a bank working day counted from the end of a month is not
+ *   a whole number from 1 up to the number of bank working days the month has;
  * - `unsupported_year`: the year lies before the first year the calendar answers for (2018) or
  *   after 9999;
  * - `unknown_state`: the value is not the code of a German federal state;
  * - `invalid_options`: the options do not say how to treat regional holidays.
  */
-export type THolidayCalendarErrorCode = 'invalid_date' | 'unsupported_year' | 'unknown_state' | 'invalid_options';
+export type THolidayCalendarErrorCode =
+  | 'invalid_date'
+  | 'invalid_month'
+  | 'invalid_position'
+  | 'unsupported_year'
+  | 'unknown_state'
+  | 'invalid_options';
 
 /** The typed error of the holiday calendar. */
 export class HolidayCalendarError extends Error {

package/ts/holidays/index.ts

@@ -11,8 +11,10 @@ export {
   findGermanState,
   getPublicHolidays,
   getPublicHolidaysOn,
+  isBankWorkingDay,
   isPublicHoliday,
   isWorkingDay,
   nextWorkingDay,
+  nthLastBankWorkingDay,
   workingDayOnOrAfter,
 } from './calendar.js';

package/ts/holidays/interfaces.ts

@@ -27,6 +27,9 @@ export interface IGermanState {
 /** A plain calendar date, `YYYY-MM-DD`. */
 export type TIsoDate = string;
 
+/** A calendar month, `YYYY-MM`. */
+export type TIsoMonth = string;
+
 /** The statutory public holidays the calendar knows. */
 export type TPublicHolidayId =
   | 'neujahr'