@fin.cx/opendata 4.3.1 → 4.5.0

package/ts/cpi/classes.bundesbankcpiclient.ts

@@ -0,0 +1,292 @@
+import { CpiError } from './classes.cpierror.js';
+import {
+  bundesbankCpiBaseUrl,
+  bundesbankVpiAnnualKey,
+  bundesbankVpiFirstMonth,
+  bundesbankVpiFirstYear,
+  bundesbankVpiMonthlyKey,
+  destatisLicence,
+} from './constants.js';
+import { parseDecimal } from './decimal.js';
+import { frequencyOf } from './indexmath.js';
+import type {
+  ICpiAnnualInput,
+  ICpiClientOptions,
+  ICpiMonthlyInput,
+  ICpiReading,
+  ICpiSeries,
+  ICpiSourceNote,
+  ICpiValue,
+  TCpiFrequency,
+  TCpiPeriod,
+} from './interfaces.js';
+import { getText, timeoutOf } from './request.js';
+
+/**
+ * The columns of the API's SDMX-CSV answer this client reads. The API leaves out a column that is empty
+ * in every row: `OBS_STATUS` appears only where a value carries a status.
+ */
+const COLUMNS = ['BBK_STD_FREQ', 'TIME_PERIOD', 'OBS_VALUE', 'BBK_DECIMALS', 'BBK_ID', 'BBK_UNIT', 'BBK_TITLE'] as const;
+const STATUS_COLUMN = 'OBS_STATUS';
+
+/** The key of the overall index for Germany on one base, as the answer names it. */
+const SERIES_KEY = /^BBDP1\.([MA])\.DE\.N\.VPI\.C\.A00000\.I(\d{2})\.A$/u;
+
+const UNIT = /^(\d{4})=100$/u;
+
+const FREQUENCY_CODES: Readonly<Record<TCpiFrequency, string>> = { monthly: 'M', annual: 'A' };
+
+/** What the API's `OBS_STATUS` says about a value; any other flag is not read. */
+const STATUSES: Readonly<Record<string, ICpiValue['status']>> = { '': 'final', E: 'estimated' };
+
+interface IRange {
+  frequency: TCpiFrequency;
+  from: TCpiPeriod;
+  to?: TCpiPeriod;
+}
+
+interface IReadSeries {
+  values: ICpiValue[];
+  estimates: ICpiValue[];
+  base: string;
+  baseYear: number;
+  key: string;
+  title: string;
+}
+
+/** One line of semicolon-separated values; a field in double quotes may hold separators and doubled quotes. */
+const splitLine = (lineArg: string): string[] | undefined => {
+  const fields: string[] = [];
+  let field = '';
+  let quoted = false;
+  for (let position = 0; position < lineArg.length; position++) {
+    const character = lineArg[position];
+    if (quoted) {
+      if (character === '"' && lineArg[position + 1] === '"') {
+        field += '"';
+        position++;
+      } else if (character === '"') {
+        quoted = false;
+      } else {
+        field += character;
+      }
+    } else if (character === '"' && field === '') {
+      quoted = true;
+    } else if (character === ';') {
+      fields.push(field);
+      field = '';
+    } else {
+      field += character;
+    }
+  }
+  if (quoted) {
+    return undefined;
+  }
+  fields.push(field);
+  return fields;
+};
+
+/**
+ * The Verbraucherpreisindex für Deutschland (overall index, unadjusted) of the Statistisches Bundesamt as
+ * the Deutsche Bundesbank republishes it in its time series API (`bundesbankCpiBaseUrl`), monthly and as
+ * annual averages. Each answer names its base, and the values the Bundesbank marks as its own estimate
+ * (the latest month at times) are kept apart from the published ones. Nothing is kept: each answer goes
+ * to the caller with the source note to show and the answer as it arrived.
+ */
+export class BundesbankCpiClient {
+  private readonly baseUrl: string;
+
+  constructor(private readonly options: ICpiClientOptions = {}) {
+    timeoutOf(options);
+    this.baseUrl = (options.baseUrl ?? bundesbankCpiBaseUrl).replace(/\/?$/u, '/');
+  }
+
+  /** The months from `from` to `to`, both included, or to the latest one when `to` is left out. */
+  public async getMonthly(inputArg: ICpiMonthlyInput): Promise<ICpiSeries> {
+    return this.getSeries({ frequency: 'monthly', from: inputArg.from, ...(inputArg.to !== undefined ? { to: inputArg.to } : {}) }, inputArg.signal);
+  }
+
+  /** The annual averages from `from` to `to`, both included, or to the latest one when `to` is left out. */
+  public async getAnnual(inputArg: ICpiAnnualInput): Promise<ICpiSeries> {
+    return this.getSeries({ frequency: 'annual', from: inputArg.from, ...(inputArg.to !== undefined ? { to: inputArg.to } : {}) }, inputArg.signal);
+  }
+
+  /**
+   * The published value of one month. A month with only the Bundesbank's estimate, or with nothing yet,
+   * ends in `not_published`, the estimate in the error where there is one.
+   */
+  public async getMonth(monthArg: string, optionsArg: { signal?: AbortSignal } = {}): Promise<ICpiReading> {
+    const series = await this.getSeries({ frequency: 'monthly', from: monthArg, to: monthArg }, optionsArg.signal);
+    const value = series.values[0];
+    if (!value) {
+      const estimate = series.estimates[0];
+      const message = estimate
+        ? `the index for ${monthArg} is not published yet; the Bundesbank gives only its own estimate (${estimate.value}).`
+        : `the index for ${monthArg} is not published yet.`;
+      throw new CpiError('not_published', message, {
+        service: 'bundesbank',
+        httpStatus: series.answer.httpStatus,
+        answer: series.answer,
+        period: monthArg,
+        ...(estimate ? { estimate } : {}),
+      });
+    }
+    return { ...value, source: series.source, answer: series.answer };
+  }
+
+  private async getSeries(rangeArg: IRange, signalArg: AbortSignal | undefined): Promise<ICpiSeries> {
+    checkRange(rangeArg);
+    const key = rangeArg.frequency === 'monthly' ? bundesbankVpiMonthlyKey : bundesbankVpiAnnualKey;
+    const uri = `${this.baseUrl}${key}?startPeriod=${rangeArg.from}${rangeArg.to !== undefined ? `&endPeriod=${rangeArg.to}` : ''}`;
+    const answer = await getText(this.options, uri, signalArg);
+    const refused = (codeArg: 'series_withdrawn' | 'busy' | 'unavailable' | 'unexpected_answer', messageArg: string): CpiError =>
+      new CpiError(codeArg, messageArg, { service: 'bundesbank', httpStatus: answer.httpStatus, answer });
+    if (answer.httpStatus === 404) {
+      throw refused('series_withdrawn', `the Bundesbank has no series ${key}: it answered 404.`);
+    }
+    if (answer.httpStatus === 429) {
+      throw refused('busy', 'the Bundesbank refused the request as one too many (429).');
+    }
+    if (answer.httpStatus >= 500 && answer.httpStatus <= 599) {
+      throw refused('unavailable', `the Bundesbank cannot answer now (${answer.httpStatus}).`);
+    }
+    if (answer.httpStatus !== 200) {
+      throw refused('unexpected_answer', `the Bundesbank answered ${answer.httpStatus}.`);
+    }
+    const read = readAnswer(answer.text, rangeArg, (messageArg) => refused('unexpected_answer', messageArg));
+    if (!read) {
+      throw new CpiError('not_published', `the Bundesbank has no value from ${rangeArg.from}${rangeArg.to !== undefined ? ` to ${rangeArg.to}` : ' on'} yet.`, {
+        service: 'bundesbank',
+        httpStatus: answer.httpStatus,
+        answer,
+        period: rangeArg.from,
+      });
+    }
+    return {
+      index: 'de-vpi',
+      frequency: rangeArg.frequency,
+      base: read.base,
+      baseYear: read.baseYear,
+      values: read.values,
+      estimates: read.estimates,
+      source: sourceNoteOf(read, uri),
+      answer,
+    };
+  }
+}
+
+/** A range of the series' periods, or the reason it is none. */
+const checkRange = (rangeArg: IRange): void => {
+  const written = rangeArg.frequency === 'monthly' ? 'YYYY-MM' : 'YYYY';
+  for (const period of [rangeArg.from, rangeArg.to]) {
+    if (period !== undefined && frequencyOf(period) !== rangeArg.frequency) {
+      throw new CpiError('invalid_input', `${JSON.stringify(period)} is no period written ${written}.`);
+    }
+  }
+  if (rangeArg.to !== undefined && rangeArg.to < rangeArg.from) {
+    throw new CpiError('invalid_input', `the range ends (${rangeArg.to}) before it begins (${rangeArg.from}).`);
+  }
+  const first = rangeArg.frequency === 'monthly' ? bundesbankVpiFirstMonth : bundesbankVpiFirstYear;
+  if (rangeArg.from < first) {
+    throw new CpiError('before_first_period', `${rangeArg.from} lies before ${first}, the first period of the series.`, { period: rangeArg.from });
+  }
+};
+
+/**
+ * The values of an SDMX-CSV answer, or `undefined` where it holds none. An answer is read only where every
+ * row is of the series and the frequency asked for, of one key and one base, inside the range asked for,
+ * once per period, with a value of the digits the answer states and a status this client knows.
+ */
+const readAnswer = (textArg: string, rangeArg: IRange, unreadableArg: (messageArg: string) => CpiError): IReadSeries | undefined => {
+  const lines = textArg.replace(/^/u, '').split(/\r?\n/u).filter((lineArg) => lineArg !== '');
+  const header = lines[0] === undefined ? undefined : splitLine(lines[0]);
+  if (!header || header[0] !== 'DATAFLOW') {
+    throw unreadableArg('the answer is no SDMX-CSV of the Bundesbank.');
+  }
+  const rows = lines.slice(1);
+  if (rows.length === 0) {
+    return undefined;
+  }
+  const missing = COLUMNS.filter((columnArg) => !header.includes(columnArg));
+  if (missing.length > 0) {
+    throw unreadableArg(`the answer has no column ${missing.join(', ')}.`);
+  }
+  const at = (fieldsArg: string[], columnArg: (typeof COLUMNS)[number] | typeof STATUS_COLUMN): string => {
+    const position = header.indexOf(columnArg);
+    return position < 0 ? '' : fieldsArg[position] ?? '';
+  };
+  const values: ICpiValue[] = [];
+  const estimates: ICpiValue[] = [];
+  const periods = new Set<string>();
+  let key: string | undefined;
+  let title = '';
+  let base = '';
+  let baseYear = 0;
+  for (const row of rows) {
+    const fields = splitLine(row);
+    if (!fields || fields.length !== header.length) {
+      throw unreadableArg(`a row is not of the answer's columns: ${row}`);
+    }
+    const rowKey = at(fields, 'BBK_ID');
+    const keyMatch = SERIES_KEY.exec(rowKey);
+    const unitMatch = UNIT.exec(at(fields, 'BBK_UNIT'));
+    const frequencyCode = FREQUENCY_CODES[rangeArg.frequency];
+    if (!keyMatch || keyMatch[1] !== frequencyCode || at(fields, 'BBK_STD_FREQ') !== frequencyCode) {
+      throw unreadableArg(`${JSON.stringify(rowKey)} is not the ${rangeArg.frequency} series of the overall index for Germany.`);
+    }
+    if (!unitMatch || unitMatch[1].slice(2) !== keyMatch[2]) {
+      throw unreadableArg(`${JSON.stringify(at(fields, 'BBK_UNIT'))} is no base of the series ${rowKey}.`);
+    }
+    if (key !== undefined && key !== rowKey) {
+      throw unreadableArg(`the answer holds more than one series or base: ${key} and ${rowKey}.`);
+    }
+    key = rowKey;
+    title = at(fields, 'BBK_TITLE');
+    base = unitMatch[0];
+    baseYear = Number(unitMatch[1]);
+    const period = at(fields, 'TIME_PERIOD');
+    if (frequencyOf(period) !== rangeArg.frequency || period < rangeArg.from || (rangeArg.to !== undefined && period > rangeArg.to)) {
+      throw unreadableArg(`${JSON.stringify(period)} is not a period asked for.`);
+    }
+    if (periods.has(period)) {
+      throw unreadableArg(`${period} is answered twice.`);
+    }
+    periods.add(period);
+    const flag = at(fields, STATUS_COLUMN);
+    if (!Object.hasOwn(STATUSES, flag)) {
+      throw unreadableArg(`${JSON.stringify(flag)} is no status this client knows, for ${period}.`);
+    }
+    const status = STATUSES[flag];
+    const written = at(fields, 'OBS_VALUE');
+    if (written === '' || written === 'NaN') {
+      // a period without a value has no observation
+      continue;
+    }
+    const decimals = Number(at(fields, 'BBK_DECIMALS'));
+    const decimal = parseDecimal(written);
+    if (!Number.isSafeInteger(decimals) || decimals < 0 || decimals > 6 || !decimal || decimal.units <= 0n || decimal.scale > decimals) {
+      throw unreadableArg(`${JSON.stringify(written)} is no index value of ${at(fields, 'BBK_DECIMALS')} decimals, for ${period}.`);
+    }
+    const value = decimal.scale === decimals ? written : `${written}${decimal.scale === 0 ? '.' : ''}${'0'.repeat(decimals - decimal.scale)}`;
+    (status === 'final' ? values : estimates).push({ index: 'de-vpi', period, value, base, status });
+  }
+  if (key === undefined || values.length + estimates.length === 0) {
+    return undefined;
+  }
+  const byPeriod = (leftArg: ICpiValue, rightArg: ICpiValue): number => leftArg.period.localeCompare(rightArg.period);
+  return { values: values.sort(byPeriod), estimates: estimates.sort(byPeriod), base, baseYear, key, title };
+};
+
+const sourceNoteOf = (readArg: IReadSeries, uriArg: string): ICpiSourceNote => ({
+  source: 'bundesbank',
+  provider: 'Deutsche Bundesbank',
+  dataOrigin: 'Statistisches Bundesamt (Destatis)',
+  title: readArg.title,
+  key: readArg.key,
+  uri: uriArg,
+  licence: destatisLicence.name,
+  licenceUri: destatisLicence.uri,
+  attribution:
+    `Quelle: Deutsche Bundesbank, Zeitreihe ${readArg.key}; Daten: Statistisches Bundesamt (Destatis), ` +
+    `Verbraucherpreisindex für Deutschland, ${readArg.base}; ${destatisLicence.name} (${destatisLicence.uri}); ${uriArg}`,
+});

package/ts/cpi/classes.cpierror.ts

@@ -0,0 +1,76 @@
+import type { ICpiServiceAnswer, ICpiValue, TCpiPeriod } from './interfaces.js';
+
+/**
+ * Why no index value or no result was given:
+ * - `invalid_input`: a period, a value, a percentage or an amount that is not one, or a range that ends
+ *   before it begins;
+ * - `before_first_period`: a period before the first one the series holds;
+ * - `not_published`: no published value for the period yet: nothing at all, or only an estimate
+ *   (`estimate`); a calculation given an estimate refuses it the same way;
+ * - `base_mismatch`: values of different bases, indices or frequencies, which are never compared;
+ * - `series_withdrawn`: the source no longer has the series asked for (HTTP 404), as happens to a
+ *   series key of an old base after the base year changed;
+ * - `busy`: the source refuses for too many requests (HTTP 429);
+ * - `unavailable`: the source cannot answer now (HTTP 5xx);
+ * - `unreachable`: no answer arrived: the name, the connection or TLS failed;
+ * - `timeout`: the answer did not arrive within the client's time;
+ * - `aborted`: the caller's signal ended the request;
+ * - `unexpected_answer`: an answer this client cannot read: another status, a missing column, a value or
+ *   a flag it does not know, a period it did not ask for, or more than one series or base.
+ */
+export type TCpiErrorCode =
+  | 'invalid_input'
+  | 'before_first_period'
+  | 'not_published'
+  | 'base_mismatch'
+  | 'series_withdrawn'
+  | 'busy'
+  | 'unavailable'
+  | 'unreachable'
+  | 'timeout'
+  | 'aborted'
+  | 'unexpected_answer';
+
+export interface ICpiErrorDetails {
+  /** the source asked, where a request was sent */
+  service?: 'bundesbank';
+  /** the HTTP status of the answer, where one arrived */
+  httpStatus?: number;
+  /** the answer as it arrived, where one did */
+  answer?: ICpiServiceAnswer;
+  /** the period the refusal is about */
+  period?: TCpiPeriod;
+  /** the estimate the source gave for that period, where it gave one (`not_published`) */
+  estimate?: ICpiValue;
+}
+
+/** The typed error of `@fin.cx/opendata/cpi`. */
+export class CpiError extends Error {
+  public readonly code: TCpiErrorCode;
+  public readonly service?: ICpiErrorDetails['service'];
+  public readonly httpStatus?: number;
+  public readonly answer?: ICpiServiceAnswer;
+  public readonly period?: TCpiPeriod;
+  public readonly estimate?: ICpiValue;
+
+  constructor(code: TCpiErrorCode, message: string, detailsArg: ICpiErrorDetails = {}, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'CpiError';
+    this.code = code;
+    if (detailsArg.service !== undefined) {
+      this.service = detailsArg.service;
+    }
+    if (detailsArg.httpStatus !== undefined) {
+      this.httpStatus = detailsArg.httpStatus;
+    }
+    if (detailsArg.answer !== undefined) {
+      this.answer = detailsArg.answer;
+    }
+    if (detailsArg.period !== undefined) {
+      this.period = detailsArg.period;
+    }
+    if (detailsArg.estimate !== undefined) {
+      this.estimate = detailsArg.estimate;
+    }
+  }
+}

package/ts/cpi/constants.ts

@@ -0,0 +1,28 @@
+/**
+ * The Deutsche Bundesbank's time series API (SDMX REST), dataflow `BBDP1`, where the Bundesbank
+ * republishes the Verbraucherpreisindex für Deutschland of the Statistisches Bundesamt ("Quelle:
+ * Statistisches Bundesamt, Wiesbaden."). Read on 2026-10-05; it answers without registration.
+ */
+export const bundesbankCpiBaseUrl = 'https://api.statistiken.bundesbank.de/rest/data/BBDP1/';
+
+/**
+ * The series keys of the overall index for Germany, monthly and annual average, unadjusted. The base
+ * dimension is left open (`..A`): the answer names the current base (`BBDP1.M.DE.N.VPI.C.A00000.I20.A`,
+ * 2020=100), and when the Statistisches Bundesamt changes the base year the Bundesbank withdraws the
+ * key of the old one (the `I15` key of 2015=100 answers 404).
+ */
+export const bundesbankVpiMonthlyKey = 'M.DE.N.VPI.C.A00000..A';
+export const bundesbankVpiAnnualKey = 'A.DE.N.VPI.C.A00000..A';
+
+/** The first month and year of the series (January 1991, the first one the API answers). */
+export const bundesbankVpiFirstMonth = '1991-01';
+export const bundesbankVpiFirstYear = '1991';
+
+/** The licence under which the Statistisches Bundesamt publishes its figures. */
+export const destatisLicence = {
+  name: 'Datenlizenz Deutschland – Namensnennung – Version 2.0',
+  uri: 'https://www.govdata.de/dl-de/by-2-0',
+} as const;
+
+/** How long one request may take by default, the answer included. */
+export const defaultCpiTimeoutMs = 30_000;

package/ts/cpi/decimal.ts

@@ -0,0 +1,45 @@
+/** A non-negative decimal as integer units of 10^-scale: `'113.5'` is 1135 at scale 1. */
+export interface IScaledDecimal {
+  units: bigint;
+  scale: number;
+}
+
+/** A decimal written with digits and at most one point between them; no sign, no exponent, no comma, no leading zero. */
+const DECIMAL = /^(0|[1-9]\d*)(?:\.(\d+))?$/u;
+
+const TEN = 10n;
+
+export const powerOfTen = (exponentArg: number): bigint => TEN ** BigInt(exponentArg);
+
+export const parseDecimal = (textArg: unknown): IScaledDecimal | undefined => {
+  const match = typeof textArg === 'string' ? DECIMAL.exec(textArg) : null;
+  if (!match) {
+    return undefined;
+  }
+  const fraction = match[2] ?? '';
+  return { units: BigInt(`${match[1]}${fraction}`), scale: fraction.length };
+};
+
+/** The units of a decimal at a scale at least its own. */
+export const atScale = (decimalArg: IScaledDecimal, scaleArg: number): bigint =>
+  decimalArg.units * powerOfTen(scaleArg - decimalArg.scale);
+
+/** numerator / denominator, rounded half away from zero ("kaufmännisch"); the denominator is positive. */
+export const divideRounded = (numeratorArg: bigint, denominatorArg: bigint): bigint => {
+  const negative = numeratorArg < 0n;
+  const magnitude = negative ? -numeratorArg : numeratorArg;
+  let quotient = magnitude / denominatorArg;
+  if ((magnitude % denominatorArg) * 2n >= denominatorArg) {
+    quotient += 1n;
+  }
+  return negative ? -quotient : quotient;
+};
+
+/** Units of 10^-scale written as a decimal with exactly `scaleArg` digits after the point: `-22` at 1 is `'-2.2'`. */
+export const formatUnits = (unitsArg: bigint, scaleArg: number): string => {
+  const negative = unitsArg < 0n;
+  const digits = (negative ? -unitsArg : unitsArg).toString().padStart(scaleArg + 1, '0');
+  const whole = digits.slice(0, digits.length - scaleArg);
+  const fraction = digits.slice(digits.length - scaleArg);
+  return `${negative ? '-' : ''}${whole}${scaleArg > 0 ? `.${fraction}` : ''}`;
+};

package/ts/cpi/index.ts

@@ -0,0 +1,16 @@
+// This entry point stands alone: it imports nothing from the rest of the package and has no
+// dependencies. It keeps nothing: every answer goes to the caller, with the source's answer as it
+// arrived, which the caller keeps as the evidence of an index adjustment.
+export * from './interfaces.js';
+export { CpiError, type ICpiErrorDetails, type TCpiErrorCode } from './classes.cpierror.js';
+export {
+  bundesbankCpiBaseUrl,
+  bundesbankVpiAnnualKey,
+  bundesbankVpiFirstMonth,
+  bundesbankVpiFirstYear,
+  bundesbankVpiMonthlyKey,
+  defaultCpiTimeoutMs,
+  destatisLicence,
+} from './constants.js';
+export { cpiChangePercent, cpiChangePoints, cpiFirstReaching, cpiFirstReachingPoints, cpiScaleAmount, cpiThresholds } from './indexmath.js';
+export { BundesbankCpiClient } from './classes.bundesbankcpiclient.js';