@fin.cx/opendata 4.1.0 → 4.3.0

package/readme.md

@@ -1,13 +1,15 @@
 # @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, and the statutory public holidays of the German 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 four practical lanes in one package:
+It gives you six 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
+- 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
 
 ## Issue Reporting and Security
 
@@ -59,6 +61,50 @@ Everything here comes from `@fin.cx/opendata/holidays`. That entry point imports
   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`
+
+### VAT ID Confirmation
+
+Everything here comes from `@fin.cx/opendata/vatid`. That entry point imports nothing else of the package and has no dependencies. It keeps nothing: each answer goes to the caller, with the answer as it arrived (`answer`: the HTTP status and the body, byte for byte), so the caller can keep it as evidence where the law asks for it. For an intra-Community supply that is the books' record of the buyer's foreign VAT ID (§ 17d Abs. 1 UStDV); a confirmation also shows the care of a prudent businessman on which the exemption rests in good faith (§ 6a Abs. 4 UStG).
+
+- `EvatrClient#confirm({ requesterVatId, vatId, trader? })`
+  The BZSt's confirmation of a foreign VAT ID (§ 18e Nr. 1 UStG). The requester is a business with a German VAT ID. With `trader` (name and city, optionally street and postal code) it is a qualified confirmation. Where the VAT ID is valid the answer carries the member state's result for each field (`qualified.answered: true`; `A` matches, `B` does not match, `C` not asked, `D` not given), or, for `evatr-2008`, that the comparison has a particularity the BZSt explains on request (`qualified.answered: false`). A valid answer to a qualified request without a documented result for each field sent is refused as `unexpected_answer`, never passed on as a simple confirmation.
+- `ViesClient#check({ vatId, requesterVatId?, trader? })`
+  The European Commission's VIES check, with the registered name and address where the member state gives them, a comparison of the trader data (`VALID`, `INVALID`, `NOT_PROCESSED`), and VIES's request identifier where the requester is named. The name is VIES's `name`, or, where it gives none, its `traderName`: the contract lists `traderName` in the answer but does not say whether it is the registered name or the one asked about; the test service answers a comparison with the registered name there. Everything else VIES answers is in `answer`.
+- `splitVatId(value)`, `vatIdCountryCodes`, `evatrStatusCodes`
+- `VatIdError` with a code for every reason no answer about validity arrived, and the answer as it arrived where one did (`answer`)
+
+Both clients take 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) and a caller's `signal`. Nothing is retried.
+
+```typescript
+import { EvatrClient, ViesClient, VatIdError } from '@fin.cx/opendata/vatid';
+
+const evatr = new EvatrClient();
+const confirmation = await evatr.confirm({
+  requesterVatId: 'DE123456789',
+  vatId: 'ATU12345678',
+  trader: { name: 'Musterhaus GmbH & Co KG', street: 'Musterstrasse 22', postalCode: '12345', city: 'musterort' },
+});
+// { service: 'bzst-evatr', requestId, requestedAt, status: 'evatr-0000', valid: true,
+//   qualified: { answered: true, name: 'A', city: 'A', ... }, answer: { httpStatus: 200, text: '{"id":…}' } }
+
+try {
+  await new ViesClient().check({ vatId: 'ATU12345678', requesterVatId: 'DE123456789' });
+} catch (error) {
+  if (error instanceof VatIdError) {
+    console.log(error.code, error.serviceCode); // for example 'member_state_unavailable', 'MS_UNAVAILABLE'
+  }
+}
+```
+
 ## Before You Start
 
 - No stock or fundamentals providers are pre-registered. You must register them before calling the services.
@@ -450,6 +496,19 @@ Four holidays apply only in part of a state:
 - `holidayCalendarFirstYear`, `holidayLawsReadOn`
 - `HolidayCalendarError` with the codes `invalid_date`, `unsupported_year`, `unknown_state` and `invalid_options`
 
+### VAT ID (`@fin.cx/opendata/vatid`)
+
+- `EvatrClient` with `confirm(input)`; `ViesClient` with `check(input)`
+- `splitVatId(value)`, `vatIdCountryCodes`, `evatrStatusCodes`, `evatrBaseUrl`, `viesBaseUrl`, `defaultVatIdTimeoutMs`
+- `VatIdError` with the codes `invalid_input`, `vat_id_malformed`, `requester_invalid`, `not_permitted`, `qualified_limit_reached`, `unavailable`, `member_state_unavailable`, `busy`, `blocked`, `unreachable`, `timeout`, `aborted` and `unexpected_answer`
+
+### 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.
@@ -497,6 +556,14 @@ 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 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:
+
+- The BZSt's eVatR REST API (`https://api.evatr.vies.bzst.de/app`, OpenAPI at `https://api.evatr.vies.bzst.de/api-docs`, version "v:1.2.3.19.886"): `POST /v1/abfrage` with `anfragendeUstid`, `angefragteUstid` and, for a qualified confirmation, `firmenname` and `ort` (and optionally `strasse`, `plz`). The status codes are those of `/v1/info/statusmeldungen`, and the country codes those of `/v1/info/eu_mitgliedstaaten`. The BZSt's page on foreign VAT IDs names the online form (`https://www.bzst.de/evatr`) and the REST API, and says the former XML-RPC interface is obsolete from 30 November 2025.
+- 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.
+
 ## Behavior And Caveats
 
 - Historical market data is cached aggressively because it is treated as immutable.
@@ -512,7 +579,7 @@ The holiday calendar is derived from the holiday laws of the federal states, rea
 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.
+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.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '4.1.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, and stock and crypto prices and fundamentals from several providers.'
+  version: '4.3.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/vatid/classes.evatrclient.ts

@@ -0,0 +1,182 @@
+import { VatIdError, type TVatIdErrorCode } from './classes.vatiderror.js';
+import { evatrBaseUrl, evatrConfirmationPath, evatrStatusCodes } from './constants.js';
+import type {
+  IEvatrConfirmation,
+  IEvatrConfirmationInput,
+  IVatIdClientOptions,
+  IVatIdTraderData,
+  TEvatrFieldResult,
+  TEvatrQualifiedResult,
+  TEvatrStatusCode,
+} from './interfaces.js';
+import { postJson, textField } from './request.js';
+import { splitVatId } from './vatid.js';
+
+/** The status codes that are an answer about the VAT ID asked about, and whether they say it is valid. */
+const ANSWERS: Readonly<Partial<Record<TEvatrStatusCode, boolean>>> = {
+  'evatr-0000': true,
+  'evatr-2008': true,
+  'evatr-2001': false,
+  'evatr-2002': false,
+  'evatr-2006': false,
+};
+
+/** What every other status code means for the caller (`VatIdError`). */
+const REFUSALS: Readonly<Partial<Record<TEvatrStatusCode, TVatIdErrorCode>>> = {
+  'evatr-0001': 'invalid_input',
+  'evatr-0002': 'invalid_input',
+  'evatr-0003': 'invalid_input',
+  'evatr-0004': 'requester_invalid',
+  'evatr-0005': 'vat_id_malformed',
+  'evatr-0006': 'not_permitted',
+  'evatr-0007': 'invalid_input',
+  'evatr-0008': 'qualified_limit_reached',
+  'evatr-0011': 'unavailable',
+  'evatr-0012': 'vat_id_malformed',
+  'evatr-0013': 'unavailable',
+  'evatr-1001': 'unavailable',
+  'evatr-1002': 'unavailable',
+  'evatr-1003': 'unavailable',
+  'evatr-1004': 'unavailable',
+  'evatr-2003': 'vat_id_malformed',
+  'evatr-2004': 'unavailable',
+  'evatr-2005': 'requester_invalid',
+  'evatr-2007': 'member_state_unavailable',
+  'evatr-2011': 'unavailable',
+  'evatr-3011': 'unavailable',
+};
+
+const FIELD_RESULTS: readonly TEvatrFieldResult[] = ['A', 'B', 'C', 'D'];
+
+const fieldResult = (bodyArg: unknown, keyArg: string): TEvatrFieldResult | undefined => {
+  const value = textField(bodyArg, keyArg);
+  return value !== undefined && (FIELD_RESULTS as readonly string[]).includes(value) ? (value as TEvatrFieldResult) : undefined;
+};
+
+/**
+ * The BZSt's confirmation of foreign VAT IDs (§ 18e Nr. 1 UStG) over its eVatR REST API
+ * (`https://api.evatr.vies.bzst.de/api-docs`). A simple confirmation says whether a VAT ID is valid
+ * when asked; a qualified one also compares the business's name, city, and where given street and
+ * postal code with what its member state registered. The BZSt confirms to a business with a German
+ * VAT ID of its own, which every request names. Nothing is kept: each answer goes to the caller.
+ */
+export class EvatrClient {
+  constructor(private readonly options: IVatIdClientOptions = {}) {}
+
+  public async confirm(inputArg: IEvatrConfirmationInput): Promise<IEvatrConfirmation> {
+    const requester = splitVatId(inputArg.requesterVatId);
+    if (!requester || requester.countryCode !== 'DE') {
+      throw new VatIdError('invalid_input', 'the requester is named by its German VAT ID', { service: 'bzst-evatr', field: 'requesterVatId' });
+    }
+    const asked = splitVatId(inputArg.vatId);
+    if (!asked) {
+      throw new VatIdError('invalid_input', 'the VAT ID asked about starts with no member state\'s code', { service: 'bzst-evatr', field: 'vatId' });
+    }
+    const trader = inputArg.trader ? traderOf(inputArg.trader) : undefined;
+    if (inputArg.trader && !trader) {
+      throw new VatIdError('invalid_input', 'a qualified confirmation needs the name and the city', { service: 'bzst-evatr', field: 'trader' });
+    }
+    const answer = await postJson(this.options, 'bzst-evatr', `${this.options.baseUrl ?? evatrBaseUrl}${evatrConfirmationPath}`, {
+      anfragendeUstid: requester.vatId,
+      angefragteUstid: asked.vatId,
+      ...(trader
+        ? {
+          firmenname: trader.name,
+          ort: trader.city,
+          ...(trader.street ? { strasse: trader.street } : {}),
+          ...(trader.postalCode ? { plz: trader.postalCode } : {}),
+        }
+        : {}),
+    }, inputArg.signal);
+    const status = textField(answer.body, 'status');
+    if (!status || !(evatrStatusCodes as readonly string[]).includes(status)) {
+      throw new VatIdError('unexpected_answer', `the BZSt answered HTTP ${answer.httpStatus} without a status it documents`, {
+        service: 'bzst-evatr',
+        httpStatus: answer.httpStatus,
+        ...(status ? { serviceCode: status } : {}),
+        answer: answer.answer,
+      });
+    }
+    const code = status as TEvatrStatusCode;
+    const valid = ANSWERS[code];
+    if (valid === undefined) {
+      throw new VatIdError(REFUSALS[code] ?? 'unexpected_answer', `the BZSt answered ${code}`, {
+        service: 'bzst-evatr',
+        serviceCode: code,
+        httpStatus: answer.httpStatus,
+        answer: answer.answer,
+      });
+    }
+    const requestedAt = textField(answer.body, 'anfrageZeitpunkt');
+    const requestedAtMs = requestedAt ? Date.parse(requestedAt) : Number.NaN;
+    if (!requestedAt || Number.isNaN(requestedAtMs)) {
+      throw new VatIdError('unexpected_answer', 'the BZSt answered without the moment of the request', {
+        service: 'bzst-evatr',
+        serviceCode: code,
+        httpStatus: answer.httpStatus,
+        answer: answer.answer,
+      });
+    }
+    const requestId = textField(answer.body, 'id');
+    const validFrom = textField(answer.body, 'gueltigAb');
+    const validTo = textField(answer.body, 'gueltigBis');
+    const qualified = trader && valid ? qualifiedResultOf(trader, code, answer.body) : undefined;
+    if (qualified === null) {
+      // a qualified request answered valid without a result for each field sent would read as a simple
+      // confirmation; it is refused instead of being passed on as one
+      throw new VatIdError('unexpected_answer', `the BZSt answered ${code} to a qualified request without a documented result for each field sent`, {
+        service: 'bzst-evatr',
+        serviceCode: code,
+        httpStatus: answer.httpStatus,
+        answer: answer.answer,
+      });
+    }
+    return {
+      service: 'bzst-evatr',
+      ...(requestId ? { requestId } : {}),
+      requestedAt,
+      requestedAtMs,
+      status: code as IEvatrConfirmation['status'],
+      valid,
+      ...(validFrom ? { validFrom } : {}),
+      ...(validTo ? { validTo } : {}),
+      requesterVatId: requester.vatId,
+      vatId: asked.vatId,
+      ...(qualified ? { qualified } : {}),
+      answer: answer.answer,
+    };
+  }
+}
+
+/**
+ * The comparison of a qualified request whose VAT ID is valid: `evatr-2008` says it has a
+ * particularity and gives no result (`answered: false`); otherwise every field sent has a documented
+ * result (`A`…`D`), or the answer is not one this client reads (`null`). A result the BZSt gives for a
+ * field not sent is kept as it is.
+ */
+const qualifiedResultOf = (traderArg: IVatIdTraderData, codeArg: TEvatrStatusCode, bodyArg: unknown): TEvatrQualifiedResult | null => {
+  if (codeArg === 'evatr-2008') {
+    return { asked: traderArg, answered: false };
+  }
+  const name = fieldResult(bodyArg, 'ergFirmenname');
+  const city = fieldResult(bodyArg, 'ergOrt');
+  // a field not sent may still carry its result (`C`, not asked); one sent must
+  const street = fieldResult(bodyArg, 'ergStrasse');
+  const postalCode = fieldResult(bodyArg, 'ergPlz');
+  if (!name || !city || (traderArg.street && !street) || (traderArg.postalCode && !postalCode)) {
+    return null;
+  }
+  return { asked: traderArg, answered: true, name, city, ...(street ? { street } : {}), ...(postalCode ? { postalCode } : {}) };
+};
+
+/** The business data as a qualified confirmation sends it: trimmed, with the name and the city required. */
+export const traderOf = (traderArg: IVatIdTraderData): IVatIdTraderData | undefined => {
+  const name = traderArg.name.trim();
+  const city = traderArg.city.trim();
+  if (!name || !city) {
+    return undefined;
+  }
+  const street = traderArg.street?.trim();
+  const postalCode = traderArg.postalCode?.trim();
+  return { name, city, ...(street ? { street } : {}), ...(postalCode ? { postalCode } : {}) };
+};

package/ts/vatid/classes.vatiderror.ts

@@ -0,0 +1,83 @@
+import type { IVatIdServiceAnswer } from './interfaces.js';
+
+/**
+ * Why a VAT ID could not be confirmed. Every code means that the service gave no answer about the
+ * validity of the VAT ID asked about:
+ * - `invalid_input`: what was asked is incomplete or not a VAT ID of a member state (checked before
+ *   sending, or refused by the service: eVatR `evatr-0002`, `evatr-0003`, `evatr-0007`, VIES
+ *   `INVALID_INPUT`);
+ * - `vat_id_malformed`: the service says the VAT ID asked about does not have the form its member
+ *   state gives (eVatR `evatr-0005`, `evatr-0012`, `evatr-2003`);
+ * - `requester_invalid`: the requester's own VAT ID is malformed or not valid (eVatR `evatr-0004`,
+ *   `evatr-2005`, VIES `INVALID_REQUESTER_INFO`);
+ * - `not_permitted`: a German VAT ID asked about by a German one (eVatR `evatr-0006`);
+ * - `qualified_limit_reached`: the qualified confirmations of this session are used up (eVatR
+ *   `evatr-0008`); a simple one is still possible;
+ * - `unavailable`: the service cannot answer now (eVatR `evatr-0011`, `-0013`, `-1001`…`-1004`,
+ *   `-2004`, `-2011`, `-3011`; VIES `SERVICE_UNAVAILABLE`);
+ * - `member_state_unavailable`: the member state's system did not answer or failed (eVatR
+ *   `evatr-2007`; VIES `MS_UNAVAILABLE`, `TIMEOUT`);
+ * - `busy`: too many requests at once (VIES `GLOBAL_MAX_CONCURRENT_REQ`, `MS_MAX_CONCURRENT_REQ`
+ *   and their `_TIME` forms);
+ * - `blocked`: the service blocks this address or this VAT ID (VIES `IP_BLOCKED`, `VAT_BLOCKED`);
+ * - `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, or a status it does not know.
+ */
+export type TVatIdErrorCode =
+  | 'invalid_input'
+  | 'vat_id_malformed'
+  | 'requester_invalid'
+  | 'not_permitted'
+  | 'qualified_limit_reached'
+  | 'unavailable'
+  | 'member_state_unavailable'
+  | 'busy'
+  | 'blocked'
+  | 'unreachable'
+  | 'timeout'
+  | 'aborted'
+  | 'unexpected_answer';
+
+export interface IVatIdErrorDetails {
+  service: 'bzst-evatr' | 'vies';
+  /** the service's own code: `evatr-0008`, `MS_UNAVAILABLE` */
+  serviceCode?: string;
+  /** the HTTP status of the answer, where one arrived */
+  httpStatus?: number;
+  /** which input a local check refused */
+  field?: 'requesterVatId' | 'vatId' | 'trader';
+  /** the answer as it arrived, where one did */
+  answer?: IVatIdServiceAnswer;
+}
+
+/** The typed error of the VAT ID clients. */
+export class VatIdError extends Error {
+  public readonly code: TVatIdErrorCode;
+  public readonly service: IVatIdErrorDetails['service'];
+  public readonly serviceCode?: string;
+  public readonly httpStatus?: number;
+  public readonly field?: IVatIdErrorDetails['field'];
+  /** the answer as it arrived, where one did: a refusal, or an answer this client cannot read */
+  public readonly answer?: IVatIdServiceAnswer;
+
+  constructor(code: TVatIdErrorCode, message: string, detailsArg: IVatIdErrorDetails, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'VatIdError';
+    this.code = code;
+    this.service = detailsArg.service;
+    if (detailsArg.serviceCode !== undefined) {
+      this.serviceCode = detailsArg.serviceCode;
+    }
+    if (detailsArg.httpStatus !== undefined) {
+      this.httpStatus = detailsArg.httpStatus;
+    }
+    if (detailsArg.field !== undefined) {
+      this.field = detailsArg.field;
+    }
+    if (detailsArg.answer !== undefined) {
+      this.answer = detailsArg.answer;
+    }
+  }
+}