@fin.cx/opendata 3.6.0 → 4.0.0

package/ts/handelsregister/forms.ts

@@ -0,0 +1,99 @@
+import * as html from './html.js';
+
+/** an option of a select element */
+export interface IFormOption {
+  value: string;
+  label: string;
+}
+
+/** a form as a browser would submit it */
+export interface IPortalForm {
+  id: string;
+  /** the action as the page states it, relative to the page */
+  action: string;
+  /** the successful controls with their current values, in document order */
+  fields: Array<[string, string]>;
+  /** the options of each select element, by name */
+  options: Map<string, IFormOption[]>;
+  /** the names of every control, including unchecked boxes and buttons */
+  controlNames: Set<string>;
+}
+
+const skippedInputTypes = new Set(['submit', 'button', 'image', 'reset', 'file']);
+
+/**
+ * Reads a form the way a browser collects it for submission: text and hidden inputs with their
+ * values, checked boxes and radios, textareas, and the selected (or first) option of each select.
+ */
+export const readForm = (documentArg: html.THtmlDocument, formIdArg: string): IPortalForm | undefined => {
+  const form = html.findById(documentArg, formIdArg);
+  if (!form || form.tagName !== 'form') {
+    return undefined;
+  }
+  const action = html.getAttribute(form, 'action');
+  if (!action) {
+    return undefined;
+  }
+  const fields: Array<[string, string]> = [];
+  const options = new Map<string, IFormOption[]>();
+  const controlNames = new Set<string>();
+  for (const element of html.descendants(form)) {
+    const name = html.getAttribute(element, 'name');
+    if (!name) {
+      continue;
+    }
+    if (element.tagName === 'input') {
+      controlNames.add(name);
+      const type = (html.getAttribute(element, 'type') ?? 'text').toLowerCase();
+      if (skippedInputTypes.has(type)) {
+        continue;
+      }
+      if (type === 'checkbox' || type === 'radio') {
+        if (html.getAttribute(element, 'checked') !== undefined) {
+          fields.push([name, html.getAttribute(element, 'value') ?? 'on']);
+        }
+        continue;
+      }
+      fields.push([name, html.getAttribute(element, 'value') ?? '']);
+    } else if (element.tagName === 'textarea') {
+      controlNames.add(name);
+      fields.push([name, element.childNodes.map((childArg) => ('value' in childArg ? childArg.value : '')).join('')]);
+    } else if (element.tagName === 'select') {
+      controlNames.add(name);
+      const selectOptions = html
+        .findAll(element, (optionArg) => optionArg.tagName === 'option')
+        .map((optionArg) => ({
+          value: html.getAttribute(optionArg, 'value') ?? html.textOf(optionArg),
+          label: html.textOf(optionArg),
+          selected: html.getAttribute(optionArg, 'selected') !== undefined,
+        }));
+      options.set(
+        name,
+        selectOptions.map((optionArg) => ({ value: optionArg.value, label: optionArg.label }))
+      );
+      const chosen = selectOptions.find((optionArg) => optionArg.selected) ?? selectOptions[0];
+      if (chosen) {
+        fields.push([name, chosen.value]);
+      }
+    } else if (element.tagName === 'button') {
+      controlNames.add(name);
+    }
+  }
+  return { id: formIdArg, action, fields, options, controlNames };
+};
+
+/** sets a field to one value, replacing every earlier value of that name */
+export const setField = (fieldsArg: Array<[string, string]>, nameArg: string, valueArg: string): void => {
+  const index = fieldsArg.findIndex(([fieldName]) => fieldName === nameArg);
+  const remaining = fieldsArg.filter(([fieldName]) => fieldName !== nameArg);
+  fieldsArg.length = 0;
+  fieldsArg.push(...remaining);
+  fieldsArg.splice(index >= 0 ? index : fieldsArg.length, 0, [nameArg, valueArg]);
+};
+
+/** removes every value of a field */
+export const removeField = (fieldsArg: Array<[string, string]>, nameArg: string): void => {
+  const remaining = fieldsArg.filter(([fieldName]) => fieldName !== nameArg);
+  fieldsArg.length = 0;
+  fieldsArg.push(...remaining);
+};

package/ts/handelsregister/html.ts

@@ -0,0 +1,113 @@
+import * as plugins from './plugins.js';
+
+export type THtmlDocument = plugins.parse5.DefaultTreeAdapterTypes.Document;
+export type THtmlElement = plugins.parse5.DefaultTreeAdapterTypes.Element;
+type THtmlParentNode = plugins.parse5.DefaultTreeAdapterTypes.ParentNode;
+type THtmlChildNode = plugins.parse5.DefaultTreeAdapterTypes.ChildNode;
+
+export const parseHtml = (htmlArg: string): THtmlDocument => plugins.parse5.parse(htmlArg);
+
+const isElement = (nodeArg: THtmlChildNode): nodeArg is THtmlElement => 'tagName' in nodeArg;
+
+/** the element children of a node */
+export const elementChildren = (nodeArg: THtmlParentNode): THtmlElement[] =>
+  nodeArg.childNodes.filter(isElement);
+
+/** every element below a node, in document order */
+export const descendants = (nodeArg: THtmlParentNode): THtmlElement[] => {
+  const result: THtmlElement[] = [];
+  const stack: THtmlElement[] = elementChildren(nodeArg).reverse();
+  while (stack.length > 0) {
+    const element = stack.pop() as THtmlElement;
+    result.push(element);
+    const children = element.tagName === 'template' ? [] : elementChildren(element);
+    for (let index = children.length - 1; index >= 0; index--) {
+      stack.push(children[index]);
+    }
+  }
+  return result;
+};
+
+export const getAttribute = (elementArg: THtmlElement, nameArg: string): string | undefined =>
+  elementArg.attrs.find((attrArg) => attrArg.name === nameArg)?.value;
+
+export const hasClass = (elementArg: THtmlElement, classArg: string): boolean =>
+  (getAttribute(elementArg, 'class') ?? '').split(/\s+/).includes(classArg);
+
+export const findById = (nodeArg: THtmlParentNode, idArg: string): THtmlElement | undefined =>
+  descendants(nodeArg).find((elementArg) => getAttribute(elementArg, 'id') === idArg);
+
+export const findAll = (
+  nodeArg: THtmlParentNode,
+  predicateArg: (elementArg: THtmlElement) => boolean
+): THtmlElement[] => descendants(nodeArg).filter(predicateArg);
+
+export const findFirst = (
+  nodeArg: THtmlParentNode,
+  predicateArg: (elementArg: THtmlElement) => boolean
+): THtmlElement | undefined => descendants(nodeArg).find(predicateArg);
+
+/**
+ * the raw text of a node and everything below it, scripts and styles left out: the text nodes in
+ * document order, separated by spaces. Walks the tree with its own stack, so no nesting depth a page
+ * can have exhausts the call stack.
+ */
+const rawText = (nodeArg: THtmlChildNode | THtmlParentNode): string => {
+  const pieces: string[] = [];
+  const stack: Array<THtmlChildNode | THtmlParentNode> = [nodeArg];
+  for (let node = stack.pop(); node !== undefined; node = stack.pop()) {
+    if ('value' in node && node.nodeName === '#text') {
+      pieces.push(node.value);
+      continue;
+    }
+    if (!('childNodes' in node)) {
+      continue;
+    }
+    if ('tagName' in node && (node.tagName === 'script' || node.tagName === 'style')) {
+      continue;
+    }
+    for (let index = node.childNodes.length - 1; index >= 0; index--) {
+      stack.push(node.childNodes[index]);
+    }
+  }
+  return pieces.join(' ');
+};
+
+/** the text of a node with white space collapsed */
+export const textOf = (nodeArg: THtmlChildNode | THtmlParentNode): string =>
+  rawText(nodeArg).replace(/\s+/g, ' ').trim();
+
+/** the text of the text nodes directly inside an element */
+export const ownTextOf = (elementArg: THtmlElement): string =>
+  elementArg.childNodes
+    .map((childArg) => ('value' in childArg && childArg.nodeName === '#text' ? childArg.value : ''))
+    .join(' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+/** the next element sibling */
+export const nextElementSibling = (elementArg: THtmlElement): THtmlElement | undefined => {
+  const parent = elementArg.parentNode;
+  if (!parent) {
+    return undefined;
+  }
+  const siblings = elementChildren(parent);
+  return siblings[siblings.indexOf(elementArg) + 1];
+};
+
+/** the previous element sibling */
+export const previousElementSibling = (elementArg: THtmlElement): THtmlElement | undefined => {
+  const parent = elementArg.parentNode;
+  if (!parent) {
+    return undefined;
+  }
+  const siblings = elementChildren(parent);
+  const index = siblings.indexOf(elementArg);
+  return index > 0 ? siblings[index - 1] : undefined;
+};
+
+/** the language the document declares on its root element */
+export const documentLanguage = (documentArg: THtmlDocument): string | undefined => {
+  const root = elementChildren(documentArg).find((elementArg) => elementArg.tagName === 'html');
+  return root ? getAttribute(root, 'lang') : undefined;
+};

package/ts/handelsregister/index.ts

@@ -0,0 +1,27 @@
+export * from './interfaces.js';
+export {
+  HandelsregisterError,
+  type IHandelsregisterErrorDetails,
+  type THandelsregisterErrorCode,
+  type THandelsregisterStep,
+} from './classes.handelsregistererror.js';
+export { HandelsregisterClient } from './classes.handelsregisterclient.js';
+export { SlidingWindowGate, type ISlidingWindowGateOptions } from './classes.slidingwindowgate.js';
+export {
+  portalMaximumHits,
+  portalRequestsPerHour,
+  registerDocuments,
+  registerTypes,
+  structuredContentNotice,
+} from './constants.js';
+export { registerCourts } from './data.codelists.js';
+export {
+  findRegisterCourt,
+  formatRegisterReference,
+  parseRegisterNumber,
+  parseRegisterReferenceText,
+  type IParsedRegisterReferenceText,
+  type IRegisterNumberParts,
+} from './references.js';
+export { parseSearchResults, type IParsedSearchResults } from './parse.searchresults.js';
+export { parseStructuredContent } from './parse.structuredcontent.js';

package/ts/handelsregister/interfaces.ts

@@ -0,0 +1,272 @@
+/**
+ * The register types the register portal searches: Handelsregister A and B, Genossenschafts-,
+ * Partnerschafts-, Vereins- and Gesellschaftsregister.
+ */
+export type TRegisterType = 'HRA' | 'HRB' | 'GnR' | 'PR' | 'VR' | 'GsR';
+
+/** a register court of the portal */
+export interface IRegisterCourt {
+  /** XJustiz court code, for example `H1101` */
+  code: string;
+  /** the court's name as the portal writes it after "Amtsgericht", for example `Bremen` */
+  name: string;
+}
+
+/** one register sheet, as the portal identifies it */
+export interface IRegisterReference {
+  court: IRegisterCourt;
+  type: TRegisterType;
+  /**
+   * the register number as the portal shows it, with the location suffix where the court uses
+   * one: `35230 HB`, `999928 NM`, `12345`
+   */
+  number: string;
+}
+
+/** what a caller passes to identify one register sheet */
+export interface IRegisterReferenceInput {
+  /** XJustiz court code, see `registerCourts` and `findRegisterCourt()` */
+  courtCode: string;
+  type: TRegisterType;
+  /** `35230`, `35230 HB` or `35230HB`; a location suffix is compared when it is given */
+  number: string;
+}
+
+/** the documents the portal offers for an entry */
+export type TRegisterDocument = 'AD' | 'CD' | 'HD' | 'DK' | 'UT' | 'VÖ' | 'SI';
+
+/** an earlier name of an entry, from the portal's result list */
+export interface IRegisterFormerName {
+  name: string;
+  /** the seat at the time, when the portal names one */
+  seat?: string;
+}
+
+/**
+ * The state of a register sheet in the portal's result list:
+ * - `current`: the portal's "aktuell";
+ * - `closed`: the portal's "Geschlossenes Registerblatt". The entry was deleted, or its sheet was
+ *   closed because the entity moved to another court, changed its legal form or merged. The list
+ *   does not say which;
+ * - `other`: a word this version does not know; `sheetStatusText` carries it.
+ */
+export type TRegisterSheetStatus = 'current' | 'closed' | 'other';
+
+/** one row of the portal's result list */
+export interface IRegisterMatch {
+  reference: IRegisterReference;
+  /** the court that kept the sheet before ("früher Amtsgericht …"), as the portal names it */
+  formerCourt?: string;
+  /** the federal state of the register court, as the portal names it */
+  federalState: string;
+  /** the current name (Firma) */
+  name: string;
+  /** the seat, as the portal shows it */
+  seat: string;
+  sheetStatus: TRegisterSheetStatus;
+  /** the portal's own word for the sheet status, German */
+  sheetStatusText: string;
+  /** earlier names, as the portal numbers them */
+  formerNames: IRegisterFormerName[];
+  /** the documents the portal offers for this entry; `SI` is the structured register content */
+  documents: TRegisterDocument[];
+}
+
+/**
+ * The portal's note on the structured register content. Every result carries it, because the
+ * structured content is not binding: the current printout (AD) is.
+ */
+export interface IStructuredContentNotice {
+  /** the portal's words, German, verbatim */
+  de: string;
+  /** the same in English */
+  en: string;
+}
+
+export interface IRegisterSearchResult {
+  /** every row the portal returned, in its order; never narrowed down to one */
+  matches: IRegisterMatch[];
+  /** the portal stopped at its maximum number of hits (100) and asked for a narrower search */
+  truncated: boolean;
+  /** the portal's notice above the list, German, when it shows one */
+  portalNotice?: string;
+  /** epoch ms: when the result list arrived */
+  retrievedAt: number;
+  /** requests of this call that count against the portal's limit of 60 per hour (always 1) */
+  countedRequests: number;
+  notice: IStructuredContentNotice;
+}
+
+/**
+ * The state of the legal entity, from the structured register content (XJustiz list
+ * reg.status-rechtstraeger):
+ * - `active` ("aktiv");
+ * - `deleted` ("gelöscht");
+ * - `in_liquidation`: dissolved and being wound up ("in Abwicklung");
+ * - `insolvent` ("insolvent");
+ * - `merged`: merged into an entity that is not registered;
+ * - `unknown`: a code this version does not know.
+ */
+export type TRegisterEntityState =
+  | 'active'
+  | 'deleted'
+  | 'in_liquidation'
+  | 'insolvent'
+  | 'merged'
+  | 'unknown';
+
+export interface IRegisterEntityStatus {
+  state: TRegisterEntityState;
+  /** code of the XJustiz list reg.status-rechtstraeger */
+  code: string;
+  /** its German designation, when the code is known */
+  label?: string;
+}
+
+export interface IRegisterLegalForm {
+  /** code of the XUnternehmen list of legal forms, for example `221110` */
+  code: string;
+  /** short designation, for example `GmbH`, when the code is known */
+  short?: string;
+  /** full designation, for example `Gesellschaft mit beschränkter Haftung`, when the code is known */
+  long?: string;
+}
+
+export interface IRegisterSeat {
+  city: string;
+  /** ISO 3166-1 alpha-2, when the state key is known */
+  country?: string;
+  /** the BfJ state key as the content gives it; `000` is Germany */
+  countryKey?: string;
+}
+
+/** a business address; private addresses are never read */
+export interface IRegisterAddress {
+  street?: string;
+  houseNumber?: string;
+  postalCode?: string;
+  city?: string;
+  /** ISO 3166-1 alpha-2, when the state key is known */
+  country?: string;
+  /** the BfJ state key as the content gives it; `000` is Germany */
+  countryKey?: string;
+}
+
+/**
+ * Someone the structured content names as entitled to represent the entity. Only the name and the
+ * function are read: birth dates, places of residence and addresses of people never leave the parser.
+ */
+export interface IRegisterRepresentative {
+  /** for a person: title, given names, name prefix, family name and suffix; for an organisation its name */
+  name: string;
+  kind: 'person' | 'organisation';
+  /** the function, German, for example `Geschäftsführer(in)`; absent for a code this version does not know */
+  function?: string;
+  /** code of the XJustiz list gds.rollenbezeichnung */
+  functionCode: string;
+}
+
+/** the register sheet as the structured content states it */
+export interface IRegisterContentRegister {
+  courtCode?: string;
+  type?: string;
+  number?: string;
+}
+
+/** the parsed structured register content (SI) of one entry */
+export interface IRegisterStructuredContent {
+  /** whether the content describes the entity as an organisation or as a natural person */
+  entityKind: 'organisation' | 'person';
+  name: string;
+  legalForm?: IRegisterLegalForm;
+  seat?: IRegisterSeat;
+  address?: IRegisterAddress;
+  register: IRegisterContentRegister;
+  /** absent when the content states no status */
+  status?: IRegisterEntityStatus;
+  /** ISO date of the most recent entry on the sheet; the content states no date for the status itself */
+  lastEntryOn?: string;
+  /** whether the content names who may represent the entity */
+  representationStated: boolean;
+  representatives: IRegisterRepresentative[];
+  /** when the portal produced the content, as it states it (ISO 8601) */
+  producedAt?: string;
+  binding: false;
+  notice: IStructuredContentNotice;
+}
+
+export interface IRegisterEntry {
+  /** the entry's row in the portal's result list */
+  match: IRegisterMatch;
+  /** the parsed structured content; null when the portal offers none for this entry */
+  structuredContent: IRegisterStructuredContent | null;
+  /** epoch ms: when the last answer of the portal arrived */
+  retrievedAt: number;
+  /** requests of this call that count against the portal's limit: 2, or 1 without structured content */
+  countedRequests: number;
+  notice: IStructuredContentNotice;
+}
+
+/** a search by the name (Firma) */
+export interface IRegisterNameQuery {
+  /** keywords of the name */
+  name: string;
+  /** `all` keywords (default), `any` keyword, or the `exact` name */
+  match?: 'all' | 'any' | 'exact';
+  /** the seat or the place of a branch */
+  seat?: string;
+  type?: TRegisterType;
+  courtCode?: string;
+  /** also closed register sheets (deleted entries) */
+  includeClosed?: boolean;
+}
+
+/** a search by register number; without a court, every court's entry with that number is returned */
+export interface IRegisterNumberQuery {
+  type: TRegisterType;
+  /** `35230`, `35230 HB` or `35230HB`; with a location suffix only rows with that suffix are returned */
+  number: string;
+  courtCode?: string;
+  /** also closed register sheets (deleted entries) */
+  includeClosed?: boolean;
+}
+
+export type TRegisterSearchQuery = IRegisterNameQuery | IRegisterNumberQuery;
+
+/** the two kinds of request the portal's terms count: at most 60 together per hour */
+export type TRegisterCountedRequestKind = 'search' | 'retrieval';
+
+export interface IRegisterCountedRequest {
+  kind: TRegisterCountedRequestKind;
+}
+
+/**
+ * Decides whether the next counted request may be made. The client calls `acquire()` before
+ * every search and every retrieval, before the step contacts the portal. Resolve to allow the
+ * request; throw to refuse it, and nothing is sent. A `HandelsregisterError` reaches the caller
+ * with the refused step and the requests the call counted before it; any other error reaches the
+ * caller unchanged.
+ */
+export interface IRegisterRequestGate {
+  acquire(request: IRegisterCountedRequest): Promise<void>;
+}
+
+export interface IHandelsregisterClientOptions {
+  /** decides before every counted request whether it may be made; see `SlidingWindowGate` */
+  gate: IRegisterRequestGate;
+  /** default `https://www.handelsregister.de` */
+  portalUrl?: string;
+  /** sent as User-Agent; name your installation and a contact */
+  userAgent?: string;
+  /** limit for each HTTP request, including its body; default 20000 ms */
+  requestTimeoutMs?: number;
+  /** limit for each response body; default 5 MiB */
+  maxResponseBytes?: number;
+  /** clock for `retrievedAt`; default `Date.now` */
+  now?: () => number;
+}
+
+export interface IRegisterCallOptions {
+  /** aborts the call; a request already sent may still have counted */
+  signal?: AbortSignal;
+}