@fin.cx/opendata 4.3.1 → 4.5.0

package/dist_ts/cpi/indexmath.js

@@ -0,0 +1,198 @@
+import { CpiError } from './classes.cpierror.js';
+import { atScale, divideRounded, formatUnits, parseDecimal, powerOfTen } from './decimal.js';
+// The arithmetic of index clauses as the Statistisches Bundesamt describes it ("Anleitung für die
+// Berechnung von Schwellenwerten und Veränderungsraten für Wertsicherungsklauseln", Stand Januar 2024;
+// "Allgemeine Informationen zum Verbraucherpreisindex"). Every calculation is exact: values are integers
+// of their published digits, and every rounding is half away from zero ("kaufmännisch").
+const MONTH = /^\d{4}-(0[1-9]|1[0-2])$/u;
+const YEAR = /^\d{4}$/u;
+/** The frequency a period is written in, or `undefined` for something that is no period. */
+export const frequencyOf = (periodArg) => {
+    if (typeof periodArg !== 'string') {
+        return undefined;
+    }
+    return MONTH.test(periodArg) ? 'monthly' : YEAR.test(periodArg) ? 'annual' : undefined;
+};
+/** A published value, read as an exact decimal; an estimate or something that is no index value is refused. */
+const publishedValueOf = (valueArg) => {
+    if (!frequencyOf(valueArg.period)) {
+        throw new CpiError('invalid_input', `${JSON.stringify(valueArg.period)} is no period written YYYY-MM or YYYY.`);
+    }
+    const decimal = parseDecimal(valueArg.value);
+    if (!decimal || decimal.units <= 0n) {
+        throw new CpiError('invalid_input', `${JSON.stringify(valueArg.value)} is no index value: a positive decimal written with a point.`, { period: valueArg.period });
+    }
+    if (valueArg.status !== 'final') {
+        throw new CpiError('not_published', `the value for ${valueArg.period} is an estimate, not a published index value.`, { period: valueArg.period, estimate: valueArg });
+    }
+    return decimal;
+};
+/** Values of one index, one base and one frequency; anything else is never compared. */
+const requireComparable = (leftArg, rightArg) => {
+    if (leftArg.index !== rightArg.index || leftArg.base !== rightArg.base || frequencyOf(leftArg.period) !== frequencyOf(rightArg.period)) {
+        throw new CpiError('base_mismatch', `${leftArg.index} ${leftArg.period} (${leftArg.base}) and ${rightArg.index} ${rightArg.period} (${rightArg.base}) are not values of one series and one base; read both on the current base.`);
+    }
+};
+/** The change in percent, in tenths of a percent: ((new / old) × 100) − 100, rounded to one decimal. */
+const changeTenthsOf = (oldArg, newArg) => {
+    const oldDecimal = publishedValueOf(oldArg);
+    const newDecimal = publishedValueOf(newArg);
+    requireComparable(oldArg, newArg);
+    const scale = Math.max(oldDecimal.scale, newDecimal.scale);
+    const oldUnits = atScale(oldDecimal, scale);
+    return divideRounded((atScale(newDecimal, scale) - oldUnits) * 1000n, oldUnits);
+};
+/**
+ * The change from one value to another in percent, as the Statistisches Bundesamt computes it:
+ * ((new / old) × 100) − 100, rounded half away from zero to one decimal (`'13.0'`, `'-2.2'`).
+ * It does not depend on the base, but both values must be read on the same one.
+ */
+export const cpiChangePercent = (oldArg, newArg) => formatUnits(changeTenthsOf(oldArg, newArg), 1);
+/**
+ * The change from one value to another in index points (new − old), with the digits of the more
+ * precise value (`'12.2'`, `'-1.0'`). Points depend on the base, so they are only given within one.
+ */
+export const cpiChangePoints = (oldArg, newArg) => {
+    const oldDecimal = publishedValueOf(oldArg);
+    const newDecimal = publishedValueOf(newArg);
+    requireComparable(oldArg, newArg);
+    const scale = Math.max(oldDecimal.scale, newDecimal.scale);
+    return formatUnits(atScale(newDecimal, scale) - atScale(oldDecimal, scale), scale);
+};
+/** The units of the thresholds at the reference value's digits. */
+const thresholdUnitsOf = (referenceArg, percentArg) => {
+    const reference = publishedValueOf(referenceArg);
+    const percent = parseDecimal(percentArg);
+    const hundred = percent ? 100n * powerOfTen(percent.scale) : 0n;
+    if (!percent || percent.units >= hundred) {
+        throw new CpiError('invalid_input', `${JSON.stringify(percentArg)} is no percentage from 0 to below 100, written with digits and a point.`);
+    }
+    return {
+        upper: divideRounded(reference.units * (hundred + percent.units), hundred),
+        lower: divideRounded(reference.units * (hundred - percent.units), hundred),
+        scale: reference.scale,
+    };
+};
+/**
+ * The thresholds of a percent rule: reference × (1 + percent / 100) and reference × (1 − percent / 100),
+ * rounded half away from zero to the reference value's digits (99.7 and 5 % give 104.7 and 94.7).
+ */
+export const cpiThresholds = (referenceArg, percentArg) => {
+    const { upper, lower, scale } = thresholdUnitsOf(referenceArg, percentArg);
+    return {
+        index: referenceArg.index,
+        base: referenceArg.base,
+        percent: percentArg,
+        upper: formatUnits(upper, scale),
+        lower: formatUnits(lower, scale),
+    };
+};
+/** The reach options as the clause gives them; anything else is refused. */
+const requireReachOptions = (optionsArg) => {
+    if (!['up', 'down', 'either'].includes(optionsArg.direction) || !['reached', 'exceeded'].includes(optionsArg.reach)) {
+        throw new CpiError('invalid_input', 'the direction is up, down or either, and the reach is reached or exceeded.');
+    }
+};
+/**
+ * The first value after the reference period at or beyond the upper threshold or at or below the lower
+ * one, as the options say. The thresholds are units of 10^-scale; the lower one may be zero or less, which
+ * no index value reaches. All values must be published values of the reference value's series and base;
+ * their order does not matter, a period given twice is refused.
+ */
+const firstReachingUnits = (valuesArg, referenceArg, thresholdsArg, optionsArg) => {
+    const periods = new Set();
+    const candidates = [];
+    for (const value of valuesArg) {
+        const decimal = publishedValueOf(value);
+        requireComparable(referenceArg, value);
+        if (periods.has(value.period)) {
+            throw new CpiError('invalid_input', `${value.period} is given twice.`, { period: value.period });
+        }
+        periods.add(value.period);
+        if (value.period > referenceArg.period) {
+            candidates.push({ value, decimal });
+        }
+    }
+    candidates.sort((leftArg, rightArg) => leftArg.value.period.localeCompare(rightArg.value.period));
+    const exceeding = optionsArg.reach === 'exceeded';
+    for (const { value, decimal } of candidates) {
+        const scale = Math.max(decimal.scale, thresholdsArg.scale);
+        const units = atScale(decimal, scale);
+        const upper = thresholdsArg.upper * powerOfTen(scale - thresholdsArg.scale);
+        const lower = thresholdsArg.lower * powerOfTen(scale - thresholdsArg.scale);
+        const up = exceeding ? units > upper : units >= upper;
+        const down = exceeding ? units < lower : units <= lower;
+        if ((optionsArg.direction !== 'down' && up) || (optionsArg.direction !== 'up' && down)) {
+            return value;
+        }
+    }
+    return undefined;
+};
+/**
+ * The first value after the reference period that reaches a threshold of a percent rule
+ * (`cpiThresholds`), or `undefined` while none does. Whether the threshold itself counts (`reached`) or
+ * only a value beyond it (`exceeded`), and which direction, is the clause's to say. All values must be
+ * published values of the reference value's series and base; their order does not matter, a period
+ * given twice is refused.
+ */
+export const cpiFirstReaching = (valuesArg, referenceArg, percentArg, optionsArg) => {
+    requireReachOptions(optionsArg);
+    return firstReachingUnits(valuesArg, referenceArg, thresholdUnitsOf(referenceArg, percentArg), optionsArg);
+};
+/**
+ * The first value after the reference period whose change from the reference in index points
+ * (`cpiChangePoints`) reaches a points rule's threshold, or `undefined` while none does: a value at or
+ * above reference + points (`up`), at or below reference − points (`down`), or whichever comes first
+ * (`either`). The points are a decimal written with digits and a point, from 0 upward, with any number
+ * of digits (`'5'`, `'2.5'`); nothing is rounded, so a threshold with more digits than the values is
+ * compared exactly. Whether the threshold itself counts (`reached`) or only a value beyond it
+ * (`exceeded`) is the clause's to say. Points depend on the base, so all values must be published
+ * values of the reference value's series and base (`base_mismatch` otherwise); their order does not
+ * matter, a period given twice is refused.
+ */
+export const cpiFirstReachingPoints = (valuesArg, referenceArg, pointsArg, optionsArg) => {
+    requireReachOptions(optionsArg);
+    const reference = publishedValueOf(referenceArg);
+    const points = parseDecimal(pointsArg);
+    if (!points) {
+        throw new CpiError('invalid_input', `${JSON.stringify(pointsArg)} is no number of index points from 0 upward, written with digits and a point.`);
+    }
+    const scale = Math.max(reference.scale, points.scale);
+    const referenceUnits = atScale(reference, scale);
+    const pointsUnits = atScale(points, scale);
+    return firstReachingUnits(valuesArg, referenceArg, { upper: referenceUnits + pointsUnits, lower: referenceUnits - pointsUnits, scale }, optionsArg);
+};
+/**
+ * An amount in cents scaled from one index value to another, rounded half away from zero to whole cents:
+ * by the index ratio (amount × new / old, the default, as the Statistisches Bundesamt writes it) or by
+ * the change in percent rounded to one decimal (`basis: 'rounded_percent'`). Which one applies is the
+ * contract's to say. The amount and the result are safe integers; a negative amount (a credit) scales
+ * the same way.
+ */
+export const cpiScaleAmount = (amountCentsArg, oldArg, newArg, optionsArg = {}) => {
+    const basis = optionsArg.basis ?? 'index_ratio';
+    if (!Number.isSafeInteger(amountCentsArg)) {
+        throw new CpiError('invalid_input', `${amountCentsArg} is no amount in whole cents.`);
+    }
+    if (basis !== 'index_ratio' && basis !== 'rounded_percent') {
+        throw new CpiError('invalid_input', `${JSON.stringify(basis)} is no basis; it is index_ratio or rounded_percent.`);
+    }
+    const amount = BigInt(amountCentsArg);
+    let scaled;
+    if (basis === 'rounded_percent') {
+        scaled = divideRounded(amount * (1000n + changeTenthsOf(oldArg, newArg)), 1000n);
+    }
+    else {
+        const oldDecimal = publishedValueOf(oldArg);
+        const newDecimal = publishedValueOf(newArg);
+        requireComparable(oldArg, newArg);
+        const scale = Math.max(oldDecimal.scale, newDecimal.scale);
+        scaled = divideRounded(amount * atScale(newDecimal, scale), atScale(oldDecimal, scale));
+    }
+    const result = Number(scaled);
+    if (!Number.isSafeInteger(result)) {
+        throw new CpiError('invalid_input', `the scaled amount of ${amountCentsArg} cents is beyond the safe integers.`);
+    }
+    return result;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXhtYXRoLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvY3BpL2luZGV4bWF0aC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsUUFBUSxFQUFFLE1BQU0sdUJBQXVCLENBQUM7QUFDakQsT0FBTyxFQUFFLE9BQU8sRUFBRSxhQUFhLEVBQUUsV0FBVyxFQUFFLFlBQVksRUFBRSxVQUFVLEVBQXVCLE1BQU0sY0FBYyxDQUFDO0FBR2xILGtHQUFrRztBQUNsRyx1R0FBdUc7QUFDdkcseUdBQXlHO0FBQ3pHLHlGQUF5RjtBQUV6RixNQUFNLEtBQUssR0FBRywwQkFBMEIsQ0FBQztBQUN6QyxNQUFNLElBQUksR0FBRyxVQUFVLENBQUM7QUFFeEIsNEZBQTRGO0FBQzVGLE1BQU0sQ0FBQyxNQUFNLFdBQVcsR0FBRyxDQUFDLFNBQWtCLEVBQTZCLEVBQUU7SUFDM0UsSUFBSSxPQUFPLFNBQVMsS0FBSyxRQUFRLEVBQUUsQ0FBQztRQUNsQyxPQUFPLFNBQVMsQ0FBQztJQUNuQixDQUFDO0lBQ0QsT0FBTyxLQUFLLENBQUMsSUFBSSxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDLElBQUksQ0FBQyxJQUFJLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQyxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsU0FBUyxDQUFDO0FBQ3pGLENBQUMsQ0FBQztBQUVGLCtHQUErRztBQUMvRyxNQUFNLGdCQUFnQixHQUFHLENBQUMsUUFBbUIsRUFBa0IsRUFBRTtJQUMvRCxJQUFJLENBQUMsV0FBVyxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsRUFBRSxDQUFDO1FBQ2xDLE1BQU0sSUFBSSxRQUFRLENBQUMsZUFBZSxFQUFFLEdBQUcsSUFBSSxDQUFDLFNBQVMsQ0FBQyxRQUFRLENBQUMsTUFBTSxDQUFDLHdDQUF3QyxDQUFDLENBQUM7SUFDbEgsQ0FBQztJQUNELE1BQU0sT0FBTyxHQUFH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

package/dist_ts/cpi/interfaces.d.ts

@@ -0,0 +1,120 @@
+/** A calendar month, `YYYY-MM`. */
+export type TIsoMonth = string;
+/** A calendar year, `YYYY`. */
+export type TIsoYear = string;
+/** The period of an index value: a month (`YYYY-MM`) or a year (`YYYY`, the annual average). */
+export type TCpiPeriod = TIsoMonth | TIsoYear;
+/** Which price index a value belongs to: `de-vpi`, the Verbraucherpreisindex für Deutschland of the Statistisches Bundesamt. */
+export type TCpiIndex = 'de-vpi';
+export type TCpiFrequency = 'monthly' | 'annual';
+/**
+ * - `final`: the value as published, final until the next change of the base year;
+ * - `estimated`: a value the source marks as an estimate (the Bundesbank's `OBS_STATUS` `E`, for the
+ *   latest month at times). It is no published index value and is never used in a calculation.
+ */
+export type TCpiValueStatus = 'final' | 'estimated';
+/** One index value as its source states it. */
+export interface ICpiValue {
+    index: TCpiIndex;
+    period: TCpiPeriod;
+    /**
+     * The value as a decimal with a point and exactly the digits published, trailing zeros included
+     * (`'100.0'`, `'113.5'`). Never a float.
+     */
+    value: string;
+    /** the base the value is stated on, as the source writes it: `'2020=100'` */
+    base: string;
+    status: TCpiValueStatus;
+}
+/** A source's answer as it arrived: its HTTP status and its body as text. */
+export interface ICpiServiceAnswer {
+    httpStatus: number;
+    text: string;
+}
+/**
+ * Where a series comes from and how it must be credited. The figures are those of the Statistisches
+ * Bundesamt (Destatis) under the Datenlizenz Deutschland – Namensnennung – Version 2.0.
+ */
+export interface ICpiSourceNote {
+    source: 'bundesbank';
+    /** who delivered the figures: `'Deutsche Bundesbank'` */
+    provider: string;
+    /** whose figures they are: `'Statistisches Bundesamt (Destatis)'` */
+    dataOrigin: string;
+    /** the series' title as the answer gives it */
+    title: string;
+    /** the series key as the answer gives it, its base included: `'BBDP1.M.DE.N.VPI.C.A00000.I20.A'` */
+    key: string;
+    /** the request the figures were read from */
+    uri: string;
+    licence: string;
+    licenceUri: string;
+    /** the source note to show wherever the figures are shown */
+    attribution: string;
+}
+/** A range of index values of one series and one base, as one answer gave them. */
+export interface ICpiSeries {
+    index: TCpiIndex;
+    frequency: TCpiFrequency;
+    /** `'2020=100'` */
+    base: string;
+    /** `2020` */
+    baseYear: number;
+    /** the published values, oldest first */
+    values: ICpiValue[];
+    /** the values the source marks as estimates, oldest first; kept apart so that no calculation takes one */
+    estimates: ICpiValue[];
+    source: ICpiSourceNote;
+    answer: ICpiServiceAnswer;
+}
+/** One published value with where it comes from and the answer it was read from. */
+export interface ICpiReading extends ICpiValue {
+    source: ICpiSourceNote;
+    answer: ICpiServiceAnswer;
+}
+/** The thresholds of a percent rule: the reference value times (1 ± percent / 100), rounded to its digits. */
+export interface ICpiThresholds {
+    index: TCpiIndex;
+    base: string;
+    /** the percentage asked for, as given */
+    percent: string;
+    upper: string;
+    lower: string;
+}
+export interface ICpiReachOptions {
+    /** `up`: the upper threshold, `down`: the lower one, `either`: whichever comes first */
+    direction: 'up' | 'down' | 'either';
+    /** `reached`: the threshold itself counts; `exceeded`: only a value beyond it counts */
+    reach: 'reached' | 'exceeded';
+}
+export interface ICpiScaleOptions {
+    /**
+     * - `index_ratio` (default): amount × new index / old index, as the Statistisches Bundesamt writes it;
+     * - `rounded_percent`: amount × (100 + the change in percent rounded to one decimal) / 100.
+     */
+    basis?: 'index_ratio' | 'rounded_percent';
+}
+/** A `fetch` as the WHATWG standard defines it; injectable for tests and for a fetch that reaches only public addresses. */
+export type TCpiFetch = (input: string, init: RequestInit) => Promise<Response>;
+export interface ICpiClientOptions {
+    /** default: the runtime's `fetch` */
+    fetch?: TCpiFetch;
+    /** default: the official address (`bundesbankCpiBaseUrl`); a test's own server otherwise */
+    baseUrl?: string;
+    /** how long one request may take, the answer included; default `defaultCpiTimeoutMs` */
+    timeoutMs?: number;
+    /** sent as `User-Agent` where given */
+    userAgent?: string;
+}
+export interface ICpiMonthlyInput {
+    from: TIsoMonth;
+    /** default: whatever the source has published after `from` */
+    to?: TIsoMonth;
+    signal?: AbortSignal;
+}
+export interface ICpiAnnualInput {
+    from: TIsoYear;
+    /** default: whatever the source has published after `from` */
+    to?: TIsoYear;
+    signal?: AbortSignal;
+}

package/dist_ts/cpi/interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW50ZXJmYWNlcy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2NwaS9pbnRlcmZhY2VzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/dist_ts/cpi/request.d.ts

@@ -0,0 +1,9 @@
+import type { ICpiClientOptions, ICpiServiceAnswer } from './interfaces.js';
+/** The time a client gives one request: its option, or the default; anything else than a positive whole number of milliseconds is refused. */
+export declare const timeoutOf: (optionsArg: ICpiClientOptions) => number;
+/**
+ * Sends one `GET` for CSV and reads the answer whole, within the client's time. The caller's signal
+ * ends it as `aborted`, the time as `timeout`, and a request that could not be sent or answered as
+ * `unreachable`; nothing is retried. The timer ends with the request, answered or not.
+ */
+export declare const getText: (optionsArg: ICpiClientOptions, urlArg: string, signalArg: AbortSignal | undefined) => Promise<ICpiServiceAnswer>;

package/dist_ts/cpi/request.js

@@ -0,0 +1,45 @@
+import { CpiError } from './classes.cpierror.js';
+import { defaultCpiTimeoutMs } from './constants.js';
+/** The time a client gives one request: its option, or the default; anything else than a positive whole number of milliseconds is refused. */
+export const timeoutOf = (optionsArg) => {
+    const timeout = optionsArg.timeoutMs ?? defaultCpiTimeoutMs;
+    if (!Number.isSafeInteger(timeout) || timeout <= 0) {
+        throw new CpiError('invalid_input', `the time limit is a positive whole number of milliseconds, got ${String(optionsArg.timeoutMs)}`);
+    }
+    return timeout;
+};
+/**
+ * Sends one `GET` for CSV and reads the answer whole, within the client's time. The caller's signal
+ * ends it as `aborted`, the time as `timeout`, and a request that could not be sent or answered as
+ * `unreachable`; nothing is retried. The timer ends with the request, answered or not.
+ */
+export const getText = async (optionsArg, urlArg, signalArg) => {
+    const fetchFn = optionsArg.fetch ?? ((inputArg, initArg) => fetch(inputArg, initArg));
+    if (signalArg?.aborted) {
+        throw new CpiError('aborted', 'the request was ended by its caller', { service: 'bundesbank' }, { cause: signalArg.reason });
+    }
+    const timeout = new AbortController();
+    const timer = setTimeout(() => timeout.abort(new Error('the client\'s time ran out')), timeoutOf(optionsArg));
+    const signal = signalArg ? AbortSignal.any([signalArg, timeout.signal]) : timeout.signal;
+    try {
+        const response = await fetchFn(urlArg, {
+            method: 'GET',
+            headers: { accept: 'text/csv', ...(optionsArg.userAgent ? { 'user-agent': optionsArg.userAgent } : {}) },
+            signal,
+        });
+        return { httpStatus: response.status, text: await response.text() };
+    }
+    catch (error) {
+        if (signalArg?.aborted) {
+            throw new CpiError('aborted', 'the request was ended by its caller', { service: 'bundesbank' }, { cause: error });
+        }
+        if (timeout.signal.aborted) {
+            throw new CpiError('timeout', 'the source did not answer in time', { service: 'bundesbank' }, { cause: error });
+        }
+        throw new CpiError('unreachable', 'the source could not be reached', { service: 'bundesbank' }, { cause: error });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVxdWVzdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2NwaS9yZXF1ZXN0LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sRUFBRSxRQUFRLEVBQUUsTUFBTSx1QkFBdUIsQ0FBQztBQUNqRCxPQUFPLEVBQUUsbUJBQW1CLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUdyRCw4SUFBOEk7QUFDOUksTUFBTSxDQUFDLE1BQU0sU0FBUyxHQUFHLENBQUMsVUFBNkIsRUFBVSxFQUFFO0lBQ2pFLE1BQU0sT0FBTyxHQUFHLFVBQVUsQ0FBQyxTQUFTLElBQUksbUJBQW1CLENBQUM7SUFDNUQsSUFBSSxDQUFDLE1BQU0sQ0FBQyxhQUFhLENBQUMsT0FBTyxDQUFDLElBQUksT0FBTyxJQUFJLENBQUMsRUFBRSxDQUFDO1FBQ25ELE1BQU0sSUFBSSxRQUFRLENBQUMsZUFBZSxFQUFFLGtFQUFrRSxNQUFNLENBQUMsVUFBVSxDQUFDLFNBQVMsQ0FBQyxFQUFFLENBQUMsQ0FBQztJQUN4SSxDQUFDO0lBQ0QsT0FBTyxPQUFPLENBQUM7QUFDakIsQ0FBQyxDQUFDO0FBRUY7Ozs7R0FJRztBQUNILE1BQU0sQ0FBQyxNQUFNLE9BQU8sR0FBRyxLQUFLLEVBQzFCLFVBQTZCLEVBQzdCLE1BQWMsRUFDZCxTQUFrQyxFQUNOLEVBQUU7SUFDOUIsTUFBTSxPQUFPLEdBQWMsVUFBVSxDQUFDLEtBQUssSUFBSSxDQUFDLENBQUMsUUFBUSxFQUFFLE9BQU8sRUFBRSxFQUFFLENBQUMsS0FBSyxDQUFDLFFBQVEsRUFBRSxPQUFPLENBQUMsQ0FBQyxDQUFDO0lBQ2pHLElBQUksU0FBUyxFQUFFLE9BQU8sRUFBRSxDQUFDO1FBQ3ZCLE1BQU0sSUFBSSxRQUFRLENBQUMsU0FBUyxFQUFFLHFDQUFxQyxFQUFFLEVBQUUsT0FBTyxFQUFFLFlBQVksRUFBRSxFQUFFLEVBQUUsS0FBSyxFQUFFLFNBQVMsQ0FBQyxNQUFNLEVBQUUsQ0FBQyxDQUFDO0lBQy9ILENBQUM7SUFDRCxNQUFNLE9BQU8sR0FBRyxJQUFJLGVBQWUsRUFBRSxDQUFDO0lBQ3RDLE1BQU0sS0FBSyxHQUFHLFVBQVUsQ0FBQyxHQUFHLEVBQUUsQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDLElBQUksS0FBSyxDQUFDLDRCQUE0QixDQUFDLENBQUMsRUFBRSxTQUFTLENBQUMsVUFBVSxDQUFDLENBQUMsQ0FBQztJQUM5RyxNQUFNLE1BQU0sR0FBRyxTQUFTLENBQUMsQ0FBQyxDQUFDLFdBQVcsQ0FBQyxHQUFHLENBQUMsQ0FBQyxTQUFTLEVBQUUsT0FBTyxDQUFDLE1BQU0sQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDLE9BQU8sQ0FBQyxNQUFNLENBQUM7SUFDekYsSUFBSSxDQUFDO1FBQ0gsTUFBTSxRQUFRLEdBQUcsTUFBTSxPQUFPLENBQUMsTUFBTSxFQUFFO1lBQ3JDLE1BQU0sRUFBRSxLQUFLO1lBQ2IsT0FBTyxFQUFFLEVBQUUsTUFBTSxFQUFFLFVBQVUsRUFBRSxHQUFHLENBQUMsVUFBVSxDQUFDLFNBQVMsQ0FBQyxDQUFDLENBQUMsRUFBRSxZQUFZLEVBQUUsVUFBVSxDQUFDLFNBQVMsRUFBRSxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsRUFBRTtZQUN4RyxNQUFNO1NBQ1AsQ0FBQyxDQUFDO1FBQ0gsT0FBTyxFQUFFLFVBQVUsRUFBRSxRQUFRLENBQUMsTUFBTSxFQUFFLElBQUksRUFBRSxNQUFNLFFBQVEsQ0FBQyxJQUFJLEVBQUUsRUFBRSxDQUFDO0lBQ3RFLENBQUM7SUFBQyxPQUFPLEtBQUssRUFBRSxDQUFDO1FBQ2YsSUFBSSxTQUFTLEVBQUUsT0FBTyxFQUFFLENBQUM7WUFDdkIsTUFBTSxJQUFJLFFBQVEsQ0FBQyxTQUFTLEVBQUUscUNBQXFDLEVBQUUsRUFBRSxPQUFPLEVBQUUsWUFBWSxFQUFFLEVBQUUsRUFBRSxLQUFLLEVBQUUsS0FBSyxFQUFFLENBQUMsQ0FBQztRQUNwSCxDQUFDO1FBQ0QsSUFBSSxPQUFPLENBQUMsTUFBTSxDQUFDLE9BQU8sRUFBRSxDQUFDO1lBQzNCLE1BQU0sSUFBSSxRQUFRLENBQUMsU0FBUyxFQUFFLG1DQUFtQyxFQUFFLEVBQUUsT0FBTyxFQUFFLFlBQVksRUFBRSxFQUFFLEVBQUUsS0FBSyxFQUFFLEtBQUssRUFBRSxDQUFDLENBQUM7UUFDbEgsQ0FBQztRQUNELE1BQU0sSUFBSSxRQUFRLENBQUMsYUFBYSxFQUFFLGlDQUFpQyxFQUFFLEVBQUUsT0FBTyxFQUFFLFlBQVksRUFBRSxFQUFFLEVBQUUsS0FBSyxFQUFFLEtBQUssRUFBRSxDQUFDLENBQUM7SUFDcEgsQ0FBQztZQUFTLENBQUM7UUFDVCxZQUFZLENBQUMsS0FBSyxDQUFDLENBQUM7SUFDdEIsQ0FBQztBQUNILENBQUMsQ0FBQyJ9

package/dist_ts/plugins.d.ts

@@ -1,8 +1,7 @@
 import * as path from 'node:path';
 export { path, };
-import * as qenv from '@push.rocks/qenv';
 import * as smartpath from '@push.rocks/smartpath';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrequest from '@push.rocks/smartrequest';
 declare const getErrorMessage: (error: unknown) => string;
-export { getErrorMessage, qenv, smartpath, smartpromise, smartrequest, };
+export { getErrorMessage, smartpath, smartpromise, smartrequest, };

package/dist_ts/plugins.js

@@ -2,7 +2,6 @@
 import * as path from 'node:path';
 export { path, };
 // @push.rocks scope
-import * as qenv from '@push.rocks/qenv';
 import * as smartpath from '@push.rocks/smartpath';
 import * as smartpromise from '@push.rocks/smartpromise';
 import * as smartrequest from '@push.rocks/smartrequest';
@@ -12,5 +11,5 @@ const getErrorMessage = (error) => {
     }
     return String(error);
 };
-export { getErrorMessage, qenv, smartpath, smartpromise, smartrequest, };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxJQUFJLE1BQU0sV0FBVyxDQUFDO0FBRWxDLE9BQU8sRUFDTCxJQUFJLEdBQ0wsQ0FBQTtBQUVELG9CQUFvQjtBQUNwQixPQUFPLEtBQUssSUFBSSxNQUFNLGtCQUFrQixDQUFDO0FBQ3pDLE9BQU8sS0FBSyxTQUFTLE1BQU0sdUJBQXVCLENBQUM7QUFDbkQsT0FBTyxLQUFLLFlBQVksTUFBTSwwQkFBMEIsQ0FBQztBQUN6RCxPQUFPLEtBQUssWUFBWSxNQUFNLDBCQUEwQixDQUFDO0FBRXpELE1BQU0sZUFBZSxHQUFHLENBQUMsS0FBYyxFQUFFLEVBQUU7SUFDekMsSUFBSSxLQUFLLFlBQVksS0FBSyxFQUFFLENBQUM7UUFDM0IsT0FBTyxLQUFLLENBQUMsT0FBTyxDQUFDO0lBQ3ZCLENBQUM7SUFFRCxPQUFPLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQztBQUN2QixDQUFDLENBQUM7QUFFRixPQUFPLEVBQ0wsZUFBZSxFQUNmLElBQUksRUFDSixTQUFTLEVBQ1QsWUFBWSxFQUNaLFlBQVksR0FDYixDQUFBIn0=
+export { getErrorMessage, smartpath, smartpromise, smartrequest, };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxJQUFJLE1BQU0sV0FBVyxDQUFDO0FBRWxDLE9BQU8sRUFDTCxJQUFJLEdBQ0wsQ0FBQTtBQUVELG9CQUFvQjtBQUNwQixPQUFPLEtBQUssU0FBUyxNQUFNLHVCQUF1QixDQUFDO0FBQ25ELE9BQU8sS0FBSyxZQUFZLE1BQU0sMEJBQTBCLENBQUM7QUFDekQsT0FBTyxLQUFLLFlBQVksTUFBTSwwQkFBMEIsQ0FBQztBQUV6RCxNQUFNLGVBQWUsR0FBRyxDQUFDLEtBQWMsRUFBRSxFQUFFO0lBQ3pDLElBQUksS0FBSyxZQUFZLEtBQUssRUFBRSxDQUFDO1FBQzNCLE9BQU8sS0FBSyxDQUFDLE9BQU8sQ0FBQztJQUN2QixDQUFDO0lBRUQsT0FBTyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUM7QUFDdkIsQ0FBQyxDQUFDO0FBRUYsT0FBTyxFQUNMLGVBQWUsRUFDZixTQUFTLEVBQ1QsWUFBWSxFQUNaLFlBQVksR0FDYixDQUFBIn0=

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@fin.cx/opendata",
-  "version": "4.3.1",
+  "version": "4.5.0",
   "private": false,
-  "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.",
+  "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.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "exports": {
@@ -26,19 +26,23 @@
       "types": "./dist_ts/vatid/index.d.ts",
       "import": "./dist_ts/vatid/index.js"
     },
+    "./cpi": {
+      "types": "./dist_ts/cpi/index.d.ts",
+      "import": "./dist_ts/cpi/index.js"
+    },
     "./package.json": "./package.json"
   },
   "type": "module",
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^5.0.0",
+    "@git.zone/tsbuild": "^5.1.2",
     "@git.zone/tsrun": "^3.0.2",
-    "@git.zone/tstest": "^6.3.2",
-    "@types/node": "^26.6.2"
+    "@git.zone/tstest": "^7.1.0",
+    "@push.rocks/qenv": "^6.1.3",
+    "@types/node": "^26.6.3"
   },
   "dependencies": {
-    "@push.rocks/qenv": "^6.1.3",
     "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartpromise": "^4.3.0",
     "@push.rocks/smartrequest": "^5.0.1",
@@ -86,7 +90,10 @@
     "Feiertage",
     "working days",
     "Basiszinssatz",
-    "base rate"
+    "base rate",
+    "consumer price index",
+    "Verbraucherpreisindex",
+    "index clause"
   ],
   "scripts": {
     "test": "(tstest test/ --verbose)",

package/readme.md

@@ -1,8 +1,8 @@
 # @fin.cx/opendata
 
-`@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.
+`@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, the base rate of § 247 BGB, and the German consumer price index for index clauses. It is built for programmers who want scriptable APIs and real workflows instead of a thin wrapper around one remote endpoint.
 
-It gives you six practical lanes in one package:
+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
@@ -10,6 +10,7 @@ It gives you six practical lanes in one package:
 - 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
 - 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
 
 ## Issue Reporting and Security
 
@@ -105,6 +106,77 @@ try {
 }
 ```
 
+### The Consumer Price Index
+
+Everything here comes from `@fin.cx/opendata/cpi`. That entry point imports nothing else of the package and has no dependencies. It keeps nothing: each answer goes to the caller with its source note and the answer as it arrived (`answer`: the HTTP status and the body), which the caller keeps as the evidence of an index adjustment.
+
+- `BundesbankCpiClient#getMonthly({ from, to? })`, `#getAnnual({ from, to? })`, `#getMonth(month)`
+  The Verbraucherpreisindex für Deutschland (VPI) of the Statistisches Bundesamt, overall index, unadjusted, monthly and as annual averages, as the Deutsche Bundesbank republishes it in its time series API. No registration is needed. Values are decimal strings with the digits published (`'113.5'`), never floats. Each series names the base it is stated on (`base: '2020=100'`), read from the answer.
+- `cpiChangePercent(old, new)`, `cpiChangePoints(old, new)`
+  The change in percent as the Statistisches Bundesamt computes it, ((new / old) × 100) − 100, rounded to one decimal; and the change in index points.
+- `cpiThresholds(reference, percent)`, `cpiFirstReaching(values, reference, percent, { direction, reach })`
+  The thresholds of a percent rule (reference × (1 ± percent / 100), rounded to the reference's digits), and the first month after the reference month that reaches one. Whether the threshold itself counts (`reached`) or only a value beyond it (`exceeded`) is the clause's to say.
+- `cpiFirstReachingPoints(values, reference, points, { direction, reach })`
+  The same for a points rule: the first month after the reference month whose change in index points reaches the threshold, at or above reference + points (`up`), at or below reference − points (`down`), or whichever comes first (`either`). The points are a decimal from 0 upward (`'5'`, `'2.5'`); the comparison is exact and nothing is rounded.
+- `cpiScaleAmount(amountCents, old, new, { basis? })`
+  An amount in cents scaled from one index value to another: by the index ratio (amount × new / old, the default) or, with `basis: 'rounded_percent'`, by the change in percent rounded to one decimal.
+- `CpiError` with the codes `invalid_input`, `before_first_period`, `not_published`, `base_mismatch`, `series_withdrawn`, `busy`, `unavailable`, `unreachable`, `timeout`, `aborted` and `unexpected_answer`
+
+The client takes a `fetch` (for example `createPublicOnlyFetch` of `@push.rocks/smartrequest`), a `baseUrl` for a test server, a `timeoutMs` (30 seconds by default; its timer ends with the request), a `userAgent` and a caller's `signal`. Nothing is retried.
+
+```typescript
+import { BundesbankCpiClient, CpiError, cpiChangePercent, cpiFirstReaching, cpiFirstReachingPoints, cpiScaleAmount } from '@fin.cx/opendata/cpi';
+
+const client = new BundesbankCpiClient();
+const series = await client.getMonthly({ from: '2020-01' });
+// { index: 'de-vpi', frequency: 'monthly', base: '2020=100', baseYear: 2020,
+//   values: [{ period: '2020-01', value: '99.8', status: 'final', ... }, ...],
+//   estimates: [{ period: '2026-09', value: '126.6', status: 'estimated', ... }],
+//   source: { attribution: 'Quelle: Deutsche Bundesbank, ...', ... }, answer: { httpStatus: 200, text: '...' } }
+
+const may2020 = series.values.find((value) => value.period === '2020-05')!; // 100.4
+const october2022 = series.values.find((value) => value.period === '2022-10')!; // 113.5
+cpiChangePercent(may2020, october2022); // '13.0'
+cpiScaleAmount(100_000, may2020, october2022); // 113048 cents
+cpiFirstReaching(series.values, series.values.find((value) => value.period === '2020-08')!, '5', {
+  direction: 'up',
+  reach: 'reached',
+}); // the value of 2021-12 (104.7)
+cpiFirstReachingPoints(series.values, october2022, '5', { direction: 'up', reach: 'reached' }); // the value of 2024-03 (118.6); 5 % first in 2024-04
+
+try {
+  await client.getMonth('2026-09');
+} catch (error) {
+  if (error instanceof CpiError && error.code === 'not_published') {
+    console.log(error.estimate?.value); // '126.6', the Bundesbank's estimate, not a published value
+  }
+}
+```
+
+#### Published values and estimates
+
+The Statistisches Bundesamt publishes a flash estimate of a month one or two working days before the month ends, and the final value about two weeks after it. For the latest month the Bundesbank's series at times carries its own estimate, marked `E`. The client keeps such values apart (`estimates`, `status: 'estimated'`): `values` holds only published ones, `getMonth()` of a month with only an estimate ends in `not_published` with the estimate in the error, and every calculation refuses an estimate with `not_published`. A range or a month with no value yet ends in `not_published` too.
+
+#### Base years
+
+The Statistisches Bundesamt moves the index to a new base year about every five years (2020=100 since the results for January 2023). It recomputes the values from January of the new base year and converts the earlier ones to the new base, so that a value read on one base differs from the same month read on another. It publishes no factors to convert between bases, and has not done so since 2003. So:
+
+- every value carries its base, and the calculations refuse values of different bases, indices or frequencies with `base_mismatch`; nothing is converted;
+- for a percent rule the Statistisches Bundesamt calculates with the values of the current base for both months, even where the contract names an earlier base, so read both again on the current base;
+- points depend on the base. `cpiChangePoints()` and `cpiFirstReachingPoints()` give them within one base only; a points rule on an earlier base is the contract's matter;
+- the client leaves the base open in its request, and the Bundesbank answers with the series of the current base. The key of the former base 2015=100 answers 404 today; an answer of 404 ends in `series_withdrawn`, and an answer that holds two bases in `unexpected_answer`.
+
+#### Attribution
+
+The figures are the Statistisches Bundesamt's, under the Datenlizenz Deutschland – Namensnennung – Version 2.0 (`https://www.govdata.de/dl-de/by-2-0`), delivered by the Deutsche Bundesbank. Wherever you show an index value, show its source note (`source.attribution`), which names:
+
+- "Quelle: Deutsche Bundesbank" with the series key;
+- the Statistisches Bundesamt (Destatis) as the provider of the data, with the index and its base;
+- the licence "Datenlizenz Deutschland – Namensnennung – Version 2.0" with its link;
+- the request the values were read from.
+
+A change in percent, a threshold or a scaled amount is not a published figure. Mark it as such, for example "eigene Berechnung", next to the source note.
+
 ## Before You Start
 
 - No stock or fundamentals providers are pre-registered. You must register them before calling the services.
@@ -509,6 +581,13 @@ Four holidays apply only in part of a state:
 - `baseRatePeriods`, `baseRateFirstDay`, `baseRatesReadOn`, `baseRateSource`
 - `BaseRateError` with the codes `invalid_date`, `invalid_range`, `before_first_period` and `not_published`
 
+### Consumer price index (`@fin.cx/opendata/cpi`)
+
+- `BundesbankCpiClient` with `getMonthly({ from, to? })`, `getAnnual({ from, to? })` and `getMonth(month)`
+- `cpiChangePercent(old, new)`, `cpiChangePoints(old, new)`, `cpiThresholds(reference, percent)`, `cpiFirstReaching(values, reference, percent, options)`, `cpiFirstReachingPoints(values, reference, points, options)`, `cpiScaleAmount(amountCents, old, new, options?)`
+- `bundesbankCpiBaseUrl`, `bundesbankVpiMonthlyKey`, `bundesbankVpiAnnualKey`, `bundesbankVpiFirstMonth`, `bundesbankVpiFirstYear`, `destatisLicence`, `defaultCpiTimeoutMs`
+- `CpiError` with the codes `invalid_input`, `before_first_period`, `not_published`, `base_mismatch`, `series_withdrawn`, `busy`, `unavailable`, `unreachable`, `timeout`, `aborted` and `unexpected_answer`
+
 ## 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.
@@ -564,6 +643,10 @@ The VAT ID clients of `@fin.cx/opendata/vatid` ask two official services at run
 - The European Commission's VIES REST API (`https://ec.europa.eu/taxation_customs/vies/rest-api`, contract `swagger_publicVAT.yaml`): `POST /check-vat-number`. Its errors arrive with HTTP 200 and `actionSucceed: false`, as its test service (`/check-vat-test-service`) shows.
 - Not verified: the terms of use of either service, whether eVatR needs a registration (its documentation names none), how many qualified confirmations the BZSt allows per session (`evatr-0008`), and the form of `gueltigAb`/`gueltigBis`, which are passed on as the BZSt writes them. The OpenAPI document lists `evatr-0008` under HTTP 400 and the status list under 403, so the client decides by the code.
 
+The consumer price index of `@fin.cx/opendata/cpi` is read at run time, one request at a time, from the Deutsche Bundesbank's time series API (`https://api.statistiken.bundesbank.de/rest/data/BBDP1/`), read on 2026-10-05: the series `M.DE.N.VPI.C.A00000..A` (monthly) and `A.DE.N.VPI.C.A00000..A` (annual averages), whose base dimension is left open so that the answer names the current base (`BBDP1.M.DE.N.VPI.C.A00000.I20.A`, 2020=100). The series begins in January 1991. The Bundesbank names the Statistisches Bundesamt as the source of the figures. The arithmetic follows the Statistisches Bundesamt's "Anleitung für die Berechnung von Schwellenwerten und Veränderungsraten für Wertsicherungsklauseln" (Stand Januar 2024) and its notes on points and percent rules. Every rounding is half away from zero; the Statistisches Bundesamt asks for one decimal without naming a rounding mode, and its examples are consistent with it.
+
+- Not verified: limits on the number of requests to the Bundesbank's API (none is documented) and terms of use specific to it. The Bundesbank's terms for reusing statistics exclude data of third parties, so the figures are used under the Statistisches Bundesamt's licence. Whether the Bundesbank keeps the series of an old base for a while after a change of base year is not known; today the key of 2015=100 answers 404.
+
 ## Behavior And Caveats
 
 - Historical market data is cached aggressively because it is treated as immutable.
@@ -579,7 +662,7 @@ The VAT ID clients of `@fin.cx/opendata/vatid` ask two official services at run
 pnpm test
 ```
 
-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. The VAT ID clients are tested against the answers the two services gave on 2026-09-27 to their documented test values (`test/fixtures/vatid/`); the tests never contact them.
+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. The VAT ID clients are tested against the answers the two services gave on 2026-09-27 to their documented test values (`test/fixtures/vatid/`); the tests never contact them. The consumer price index client is tested against the answers the Bundesbank's API gave on 2026-10-05 and two answers written by hand from them (`test/fixtures/cpi/`); the tests never contact it.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '4.3.1',
-  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.'
+  version: '4.5.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.'
 }