@fin.cx/opendata 4.5.0 → 4.7.0

package/ts/handelsregister/interfaces.ts

@@ -92,7 +92,10 @@ export interface IRegisterSearchResult {
   portalNotice?: string;
   /** epoch ms: when the result list arrived */
   retrievedAt: number;
-  /** requests of this call that count against the portal's limit of 60 per hour (always 1) */
+  /**
+   * requests of this call that count against the portal's limit of 60 per hour: 1, or 2 when the
+   * portal dropped the search without an answer and it was sent once more
+   */
   countedRequests: number;
   notice: IStructuredContentNotice;
 }
@@ -202,7 +205,11 @@ export interface IRegisterEntry {
   structuredContent: IRegisterStructuredContent | null;
   /** epoch ms: when the last answer of the portal arrived */
   retrievedAt: number;
-  /** requests of this call that count against the portal's limit: 2, or 1 without structured content */
+  /**
+   * requests of this call that count against the portal's limit: 2, or 1 without structured content;
+   * one more for the search or the retrieval when the portal dropped it without an answer and it was
+   * sent once more
+   */
   countedRequests: number;
   notice: IStructuredContentNotice;
 }

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'