@fin.cx/opendata 3.5.1 → 4.0.0

package/ts/handelsregister/parse.searchresults.ts

@@ -0,0 +1,241 @@
+import { HandelsregisterError } from './classes.handelsregistererror.js';
+import { registerDocuments, registerTypes, structuredContentNotice } from './constants.js';
+import { registerCourts } from './data.codelists.js';
+import * as forms from './forms.js';
+import * as html from './html.js';
+import type {
+  IRegisterCourt,
+  IRegisterFormerName,
+  IRegisterMatch,
+  IStructuredContentNotice,
+  TRegisterDocument,
+  TRegisterSheetStatus,
+  TRegisterType,
+} from './interfaces.js';
+
+export const resultFormId = 'ergebnissForm';
+const resultTableId = 'ergebnissForm:selectedSuchErgebnisFormTable';
+const resultRowsId = `${resultTableId}_data`;
+const hitLimitLabelId = 'ergebnissForm:ergebnisseAnzahl_label';
+
+/** one row of the result list with what is needed to retrieve its documents */
+export interface IResultRow {
+  match: IRegisterMatch;
+  /** the extra fields a click on each document link submits with the result form */
+  documentSubmissions: Map<TRegisterDocument, Array<[string, string]>>;
+}
+
+export interface IParsedResultList {
+  rows: IResultRow[];
+  truncated: boolean;
+  portalNotice?: string;
+  /** the number of hits the portal reports */
+  hitCount?: number;
+  /** the result form, for retrieving documents */
+  form?: forms.IPortalForm;
+}
+
+/** the public shape of a parsed result list */
+export interface IParsedSearchResults {
+  matches: IRegisterMatch[];
+  truncated: boolean;
+  portalNotice?: string;
+  notice: IStructuredContentNotice;
+}
+
+const unexpected = (messageArg: string): HandelsregisterError =>
+  new HandelsregisterError('unexpected_response', messageArg, { step: 'result_list' });
+
+const sheetStatusOf = (textArg: string): TRegisterSheetStatus => {
+  switch (textArg) {
+    case 'aktuell':
+      return 'current';
+    case 'Geschlossenes Registerblatt':
+      return 'closed';
+    default:
+      return 'other';
+  }
+};
+
+const courtLinePattern = new RegExp(
+  `^Amtsgericht (.+?) (${registerTypes.join('|')}) (\\d+)(?: ([A-Za-zÄÖÜäöü]{1,5}))?(?: früher Amtsgericht (.+))?$`
+);
+
+interface ICourtLine {
+  court: IRegisterCourt;
+  type: TRegisterType;
+  number: string;
+  formerCourt?: string;
+}
+
+const readCourtLine = (textArg: string, courtsArg: readonly IRegisterCourt[]): ICourtLine => {
+  const match = courtLinePattern.exec(textArg);
+  if (!match) {
+    throw unexpected('A row of the result list names its register in an unknown form.');
+  }
+  const court = courtsArg.find((courtArg) => courtArg.name === match[1]);
+  if (!court) {
+    throw unexpected('A row of the result list names a register court this version does not know.');
+  }
+  const type = registerTypes.find((typeArg) => typeArg === match[2]);
+  if (!type) {
+    throw unexpected('A row of the result list names an unknown register type.');
+  }
+  const line: ICourtLine = { court, type, number: match[4] ? `${match[3]} ${match[4]}` : match[3] };
+  if (match[5]) {
+    line.formerCourt = match[5];
+  }
+  return line;
+};
+
+/** `1.) Beispiel GmbH` → `Beispiel GmbH` */
+const withoutListNumber = (textArg: string): string => textArg.replace(/^\d+\.\)\s*/, '').trim();
+
+/** the parameters `PrimeFaces.addSubmitParam('<form>', {...})` adds to a submission */
+const readSubmitParameters = (onclickArg: string, formIdArg: string): Array<[string, string]> | undefined => {
+  const call = /PrimeFaces\.addSubmitParam\('([^']+)',\{([^}]*)\}\)/.exec(onclickArg);
+  if (!call || call[1] !== formIdArg) {
+    return undefined;
+  }
+  const parameters: Array<[string, string]> = [];
+  const pairPattern = /'([^']*)':'([^']*)'/g;
+  let pair: RegExpExecArray | null;
+  while ((pair = pairPattern.exec(call[2])) !== null) {
+    parameters.push([pair[1], pair[2]]);
+  }
+  return parameters.length > 0 ? parameters : undefined;
+};
+
+const readRow = (rowArg: html.THtmlElement, courtsArg: readonly IRegisterCourt[]): IResultRow => {
+  const headCell = html.findFirst(rowArg, (elementArg) => elementArg.tagName === 'td' && html.hasClass(elementArg, 'fontTableNameSize'));
+  const courtSpan = headCell && html.findFirst(headCell, (elementArg) => html.hasClass(elementArg, 'fontWeightBold'));
+  const seatCell = html.findFirst(rowArg, (elementArg) => elementArg.tagName === 'td' && html.hasClass(elementArg, 'sitzSuchErgebnisse'));
+  const nameCell = seatCell && html.previousElementSibling(seatCell);
+  const statusCell = seatCell && html.nextElementSibling(seatCell);
+  const documentsCell = statusCell && html.nextElementSibling(statusCell);
+  if (!headCell || !courtSpan || !seatCell || !nameCell || !statusCell || !documentsCell) {
+    throw unexpected('A row of the result list lacks a cell this version reads.');
+  }
+  const courtLine = readCourtLine(html.textOf(courtSpan), courtsArg);
+  const name = html.textOf(nameCell);
+  const sheetStatusText = html.textOf(statusCell);
+  if (!name || !sheetStatusText) {
+    throw unexpected('A row of the result list has no name or no status.');
+  }
+
+  const documents: TRegisterDocument[] = [];
+  const documentSubmissions = new Map<TRegisterDocument, Array<[string, string]>>();
+  for (const link of html.findAll(documentsCell, (elementArg) => elementArg.tagName === 'a')) {
+    const document = registerDocuments.find((documentArg) => documentArg === html.textOf(link));
+    if (!document) {
+      continue;
+    }
+    documents.push(document);
+    const parameters = readSubmitParameters(html.getAttribute(link, 'onclick') ?? '', resultFormId);
+    if (parameters) {
+      documentSubmissions.set(document, parameters);
+    }
+  }
+
+  const formerNames: IRegisterFormerName[] = [];
+  for (const nameHistoryCell of html.findAll(
+    rowArg,
+    (elementArg) => elementArg.tagName === 'td' && html.hasClass(elementArg, 'RegPortErg_HistorieZn')
+  )) {
+    const formerName = withoutListNumber(html.textOf(nameHistoryCell));
+    if (!formerName) {
+      continue;
+    }
+    const seatHistoryCell = html.nextElementSibling(nameHistoryCell);
+    const formerSeat =
+      seatHistoryCell && html.hasClass(seatHistoryCell, 'RegPortErg_SitzStatus')
+        ? withoutListNumber(html.textOf(seatHistoryCell))
+        : '';
+    formerNames.push(formerSeat ? { name: formerName, seat: formerSeat } : { name: formerName });
+  }
+
+  const match: IRegisterMatch = {
+    reference: { court: courtLine.court, type: courtLine.type, number: courtLine.number },
+    federalState: html.ownTextOf(headCell),
+    name,
+    seat: html.textOf(seatCell),
+    sheetStatus: sheetStatusOf(sheetStatusText),
+    sheetStatusText,
+    formerNames,
+    documents,
+  };
+  if (courtLine.formerCourt) {
+    match.formerCourt = courtLine.formerCourt;
+  }
+  return { match, documentSubmissions };
+};
+
+/**
+ * Reads the portal's result list. `courtsArg` are the register courts the rows are resolved
+ * against; by default the courts this version knows.
+ */
+export const readResultList = (
+  htmlArg: string,
+  courtsArg: readonly IRegisterCourt[] = registerCourts
+): IParsedResultList => {
+  const document = html.parseHtml(htmlArg);
+  if (html.documentLanguage(document) !== 'de') {
+    throw unexpected('The result list is not in German.');
+  }
+  const rowsBody = html.findById(document, resultRowsId);
+  if (!rowsBody) {
+    throw unexpected('The answer contains no result list.');
+  }
+  const rows = html
+    .elementChildren(rowsBody)
+    .filter((elementArg) => elementArg.tagName === 'tr' && html.getAttribute(elementArg, 'data-ri') !== undefined)
+    .map((rowArg) => readRow(rowArg, courtsArg));
+  if (rows.length === 0) {
+    const emptyMessage = html.findFirst(rowsBody, (elementArg) => html.hasClass(elementArg, 'ui-datatable-empty-message'));
+    if (!emptyMessage) {
+      throw unexpected('The result list has neither rows nor the message that there are none.');
+    }
+  }
+
+  const table = html.findById(document, resultTableId);
+  const hitCounter = table && html.findFirst(table, (elementArg) => html.hasClass(elementArg, 'ui-paginator-current'));
+  const hitMatch = hitCounter ? /von (\d+) Treffer/.exec(html.textOf(hitCounter)) : null;
+  const hitCount = hitMatch ? Number(hitMatch[1]) : undefined;
+
+  const hitLimitLabel = html.findById(document, hitLimitLabelId);
+  const portalNotice = hitLimitLabel ? html.textOf(hitLimitLabel) : '';
+  const hitLimitReached = /Trefferanzahl/.test(portalNotice);
+
+  const result: IParsedResultList = {
+    rows,
+    truncated: hitLimitReached || (hitCount !== undefined && hitCount > rows.length),
+  };
+  if (portalNotice) {
+    result.portalNotice = portalNotice;
+  }
+  if (hitCount !== undefined) {
+    result.hitCount = hitCount;
+  }
+  const form = forms.readForm(document, resultFormId);
+  if (form) {
+    result.form = form;
+  }
+  return result;
+};
+
+/**
+ * Parses a result list page of the register portal, as saved from a browser, into matches.
+ * Makes no request.
+ */
+export const parseSearchResults = (htmlArg: string): IParsedSearchResults => {
+  const list = readResultList(htmlArg);
+  const result: IParsedSearchResults = {
+    matches: list.rows.map((rowArg) => rowArg.match),
+    truncated: list.truncated,
+    notice: structuredContentNotice,
+  };
+  if (list.portalNotice) {
+    result.portalNotice = list.portalNotice;
+  }
+  return result;
+};

package/ts/handelsregister/parse.structuredcontent.ts

@@ -0,0 +1,338 @@
+import * as plugins from './plugins.js';
+import { HandelsregisterError } from './classes.handelsregistererror.js';
+import { structuredContentNotice } from './constants.js';
+import { entityStatusLabels, legalFormLabels, roleLabels, stateKeyToIso } from './data.codelists.js';
+import type {
+  IRegisterAddress,
+  IRegisterContentRegister,
+  IRegisterEntityStatus,
+  IRegisterLegalForm,
+  IRegisterRepresentative,
+  IRegisterSeat,
+  IRegisterStructuredContent,
+  TRegisterEntityState,
+} from './interfaces.js';
+import { formatRegisterNumber, parseRegisterNumber, parseRegisterReferenceText } from './references.js';
+
+type TXmlElement = plugins.smartxmlXpath.dom.Element;
+
+const xjustizNamespace = 'http://www.xjustiz.de';
+const registerMessage = 'nachricht.reg.0400003';
+/** business address types: "Dienst-/Geschäftsanschrift", then "Lage der Geschäftsräume" */
+const businessAddressTypes = ['003', '021'];
+
+const invalid = (messageArg: string, causeArg?: unknown): HandelsregisterError =>
+  new HandelsregisterError('invalid_structured_content', messageArg, {
+    step: 'structured_content',
+    ...(causeArg === undefined ? {} : { cause: causeArg }),
+  });
+
+const childrenNamed = (elementArg: TXmlElement, nameArg: string): TXmlElement[] =>
+  elementArg.children.filter((childArg) => childArg.localName === nameArg);
+
+/** the first element along a path of local names */
+const at = (elementArg: TXmlElement | undefined, ...namesArg: string[]): TXmlElement | undefined => {
+  let current = elementArg;
+  for (const name of namesArg) {
+    if (!current) {
+      return undefined;
+    }
+    current = current.children.find((childArg) => childArg.localName === name);
+  }
+  return current;
+};
+
+/**
+ * the trimmed text of the value element along a path, or undefined when absent or empty. The
+ * XJustiz values read here (codes, names, dates, numbers) are text only, so a value element that
+ * holds elements is refused.
+ */
+const textAt = (elementArg: TXmlElement | undefined, ...namesArg: string[]): string | undefined => {
+  const element = at(elementArg, ...namesArg);
+  if (!element) {
+    return undefined;
+  }
+  if (element.children.length > 0) {
+    throw invalid('A value in the structured content holds elements instead of text.');
+  }
+  const text = element.textContent?.replace(/\s+/g, ' ').trim();
+  return text ? text : undefined;
+};
+
+/** the code of a code list value along a path */
+const codeAt = (elementArg: TXmlElement | undefined, ...namesArg: string[]): string | undefined =>
+  textAt(elementArg, ...namesArg, 'code');
+
+interface IParticipant {
+  kind: 'organisation' | 'person';
+  element: TXmlElement;
+}
+
+interface IRole {
+  code?: string;
+  participant: IParticipant;
+}
+
+const readParticipant = (participationArg: TXmlElement): IParticipant | undefined => {
+  const choice = at(participationArg, 'beteiligter', 'auswahl_beteiligter');
+  const organisation = at(choice, 'organisation');
+  if (organisation) {
+    return { kind: 'organisation', element: organisation };
+  }
+  const person = at(choice, 'natuerlichePerson');
+  return person ? { kind: 'person', element: person } : undefined;
+};
+
+/** title, given names, name prefix, family name and suffix; nothing else of a person is read */
+const personName = (personArg: TXmlElement): string => {
+  const fullName = at(personArg, 'vollerName');
+  const familyName = textAt(fullName, 'nachname');
+  if (!familyName) {
+    throw invalid('A person in the structured content has no family name.');
+  }
+  return [
+    textAt(fullName, 'titel'),
+    textAt(fullName, 'vorname'),
+    textAt(fullName, 'namensvorsatz'),
+    familyName,
+    textAt(fullName, 'namenszusatz'),
+  ]
+    .filter((partArg): partArg is string => partArg !== undefined)
+    .join(' ');
+};
+
+const organisationName = (organisationArg: TXmlElement): string | undefined =>
+  textAt(organisationArg, 'bezeichnung', 'bezeichnung.aktuell');
+
+const participantName = (participantArg: IParticipant): string => {
+  if (participantArg.kind === 'person') {
+    return personName(participantArg.element);
+  }
+  const name = organisationName(participantArg.element);
+  if (!name) {
+    throw invalid('An organisation in the structured content has no name.');
+  }
+  return name;
+};
+
+const readLegalForm = (organisationsArg: TXmlElement[]): IRegisterLegalForm | undefined => {
+  for (const organisation of organisationsArg) {
+    const code = codeAt(organisation, 'angabenZurRechtsform', 'rechtsform');
+    if (code) {
+      const label = legalFormLabels[code];
+      return label ? { code, ...label } : { code };
+    }
+  }
+  return undefined;
+};
+
+const withCountry = <T extends { country?: string; countryKey?: string }>(targetArg: T, keyArg: string | undefined): T => {
+  if (keyArg) {
+    targetArg.countryKey = keyArg;
+    const iso = stateKeyToIso[keyArg];
+    if (iso) {
+      targetArg.country = iso;
+    }
+  }
+  return targetArg;
+};
+
+const readSeat = (organisationsArg: TXmlElement[]): IRegisterSeat | undefined => {
+  for (const organisation of organisationsArg) {
+    const city = textAt(organisation, 'sitz', 'ort');
+    if (city) {
+      return withCountry<IRegisterSeat>({ city }, codeAt(organisation, 'sitz', 'staat'));
+    }
+  }
+  return undefined;
+};
+
+const readAddress = (holdersArg: TXmlElement[]): IRegisterAddress | undefined => {
+  for (const addressType of businessAddressTypes) {
+    for (const holder of holdersArg) {
+      const address = childrenNamed(holder, 'anschrift').find(
+        (addressArg) => codeAt(addressArg, 'anschriftstyp') === addressType
+      );
+      if (!address) {
+        continue;
+      }
+      const result: IRegisterAddress = {};
+      const street = textAt(address, 'strasse');
+      const houseNumber = textAt(address, 'hausnummer');
+      const postalCode = textAt(address, 'postleitzahl');
+      const city = textAt(address, 'ort');
+      if (street) result.street = street;
+      if (houseNumber) result.houseNumber = houseNumber;
+      if (postalCode) result.postalCode = postalCode;
+      if (city) result.city = city;
+      return withCountry(result, codeAt(address, 'staat'));
+    }
+  }
+  return undefined;
+};
+
+const readRegister = (rootArg: TXmlElement, organisationsArg: TXmlElement[]): IRegisterContentRegister => {
+  const register: IRegisterContentRegister = {};
+  const instance = at(rootArg, 'grunddaten', 'verfahrensdaten', 'instanzdaten');
+  for (const organisation of organisationsArg) {
+    const entry = at(organisation, 'registereintragung');
+    const court = at(entry, 'auswahl_registerbehoerde', 'inlaendischesRegistergericht');
+    const courtCode = codeAt(court, 'gericht');
+    const type = codeAt(court, 'registerart');
+    const numberText = textAt(entry, 'registernummer');
+    if (courtCode && !register.courtCode) register.courtCode = courtCode;
+    if (type && !register.type) register.type = type;
+    if (numberText && !register.number) {
+      const parsed = parseRegisterReferenceText(numberText);
+      if (parsed) {
+        register.number = parsed.number;
+        if (!register.type) register.type = parsed.type;
+      } else {
+        const parts = parseRegisterNumber(numberText);
+        if (parts) register.number = formatRegisterNumber(parts);
+      }
+    }
+  }
+  const instanceCourt = codeAt(instance, 'auswahl_instanzbehoerde', 'gericht');
+  if (instanceCourt && !register.courtCode) register.courtCode = instanceCourt;
+  const fileNumber = at(instance, 'aktenzeichen', 'auswahl_aktenzeichen');
+  const structured = at(fileNumber, 'aktenzeichen.strukturiert');
+  if (structured) {
+    const type = codeAt(structured, 'register');
+    const running = textAt(structured, 'laufendeNummer');
+    if (type && !register.type) register.type = type;
+    if (running && !register.number) register.number = running;
+  }
+  const freeText = textAt(fileNumber, 'aktenzeichen.freitext');
+  if (freeText) {
+    const parsed = parseRegisterReferenceText(freeText);
+    if (parsed) {
+      if (!register.type) register.type = parsed.type;
+      if (!register.number) register.number = parsed.number;
+    }
+  }
+  return register;
+};
+
+const statusStates: Readonly<Record<string, TRegisterEntityState>> = {
+  '001': 'active',
+  '002': 'deleted',
+  '003': 'in_liquidation',
+  '004': 'insolvent',
+  '005': 'merged',
+};
+
+const readStatus = (baseDataArg: TXmlElement | undefined): IRegisterEntityStatus | undefined => {
+  const code = codeAt(baseDataArg, 'statusRechtstraeger');
+  if (!code) {
+    return undefined;
+  }
+  const status: IRegisterEntityStatus = { state: statusStates[code] ?? 'unknown', code };
+  const label = entityStatusLabels[code];
+  if (label) {
+    status.label = label;
+  }
+  return status;
+};
+
+/**
+ * Parses the structured register content (SI) the register portal delivers as XJustiz XML
+ * (`nachricht.reg.0400003`). Makes no request. Of people it reads the name and the function only.
+ */
+export const parseStructuredContent = (xmlArg: string): IRegisterStructuredContent => {
+  if (/<!DOCTYPE/i.test(xmlArg)) {
+    throw invalid('The structured content declares a document type, which XJustiz never does.');
+  }
+  let document: plugins.smartxmlXpath.dom.Document;
+  try {
+    document = plugins.smartxmlXpath.parseXmlDocument(xmlArg);
+  } catch (error) {
+    throw invalid('The structured content is not well-formed XML.', error);
+  }
+  const root = document.documentElement;
+  if (!root || root.localName !== registerMessage || root.namespaceURI !== xjustizNamespace) {
+    throw invalid('The document is not an XJustiz register message.');
+  }
+
+  const roles = new Map<string, IRole>();
+  const proceedings = at(root, 'grunddaten', 'verfahrensdaten');
+  const participations = proceedings ? childrenNamed(proceedings, 'beteiligung') : [];
+  for (const participation of participations) {
+    const participant = readParticipant(participation);
+    if (!participant) {
+      continue;
+    }
+    for (const role of childrenNamed(participation, 'rolle')) {
+      const roleNumber = textAt(role, 'rollennummer');
+      if (!roleNumber) {
+        continue;
+      }
+      const code = codeAt(role, 'rollenbezeichnung');
+      roles.set(roleNumber, code ? { code, participant } : { participant });
+    }
+  }
+
+  const registerData = childrenNamed(root, 'fachdatenRegister');
+  if (registerData.length !== 1) {
+    throw invalid('The structured content does not describe exactly one entity.');
+  }
+  const entityRole = roles.get(textAt(registerData[0], 'betroffenerRechtstraeger', 'ref.rollennummer') ?? '');
+  if (!entityRole) {
+    throw invalid('The structured content does not say which participant the entity is.');
+  }
+  const baseData = at(registerData[0], 'basisdatenRegister');
+  const organisations = [at(baseData, 'rechtstraeger'), entityRole.participant.kind === 'organisation' ? entityRole.participant.element : undefined].filter(
+    (elementArg): elementArg is TXmlElement => elementArg !== undefined
+  );
+
+  const name =
+    organisations.map((organisationArg) => organisationName(organisationArg)).find((nameArg) => nameArg !== undefined) ??
+    (entityRole.participant.kind === 'person' ? personName(entityRole.participant.element) : undefined);
+  if (!name) {
+    throw invalid('The structured content names no entity.');
+  }
+
+  const representatives: IRegisterRepresentative[] = [];
+  const representation = at(baseData, 'vertretung');
+  const entitled = representation ? childrenNamed(representation, 'vertretungsberechtigte') : [];
+  for (const entry of entitled) {
+    const role = roles.get(textAt(entry, 'ref.rollennummer') ?? '');
+    if (!role || !role.code) {
+      throw invalid('The structured content refers to a representative it does not list.');
+    }
+    const representative: IRegisterRepresentative = {
+      name: participantName(role.participant),
+      kind: role.participant.kind,
+      functionCode: role.code,
+    };
+    const label = roleLabels[role.code];
+    if (label) {
+      representative.function = label;
+    }
+    representatives.push(representative);
+  }
+
+  const holders = entityRole.participant.kind === 'person' ? [...organisations, entityRole.participant.element] : organisations;
+  const content: IRegisterStructuredContent = {
+    entityKind: organisations.length > 0 ? 'organisation' : 'person',
+    name,
+    register: readRegister(root, organisations),
+    representationStated: entitled.length > 0,
+    representatives,
+    binding: false,
+    notice: structuredContentNotice,
+  };
+  const legalForm = readLegalForm(organisations);
+  const seat = readSeat(organisations);
+  const address = readAddress(holders);
+  const status = readStatus(baseData);
+  const lastEntryOn = textAt(registerData[0], 'auszug', 'letzteEintragung');
+  const producedAt = textAt(root, 'nachrichtenkopf', 'erstellungszeitpunkt');
+  if (legalForm) content.legalForm = legalForm;
+  if (seat) content.seat = seat;
+  if (address) content.address = address;
+  if (status) content.status = status;
+  if (lastEntryOn) content.lastEntryOn = lastEntryOn;
+  if (producedAt) content.producedAt = producedAt;
+  return content;
+};

package/ts/handelsregister/plugins.ts

@@ -0,0 +1,15 @@
+// This entry point stands alone: it imports nothing from the rest of the package and needs no storage.
+
+// @push.rocks scope
+import * as smartxmlXpath from '@push.rocks/smartxml/xpath';
+
+export {
+  smartxmlXpath,
+}
+
+// third party scope
+import * as parse5 from 'parse5';
+
+export {
+  parse5,
+}