@fin.cx/opendata 4.8.0 → 4.9.1

package/ts/gleif/index.ts

@@ -0,0 +1,6 @@
+export * from './interfaces.js';
+export { GleifClient, gleifDeltaKinds, gleifGoldenCopyBaseUrl, gleifRestBaseUrl } from './classes.gleifclient.js';
+export { GleifError, type TGleifErrorCode } from './classes.gleiferror.js';
+export { parseGleifRestRecord } from './records.js';
+export { courtFromRegistrationAuthority, registrationAuthorityFromCourt, parseRegistrationAuthorityEntityId, registerReferenceFromRegistrationAuthority } from './crosswalk.js';
+export { germanRegistrationAuthorities, gleifUnmappedCourts, gleifRegistrationAuthoritiesSource } from './data.crosswalk.js';

package/ts/gleif/interfaces.ts

@@ -0,0 +1,107 @@
+import type { TRegisterType } from '../handelsregister/interfaces.js';
+
+export interface IGleifName {
+  name: string;
+  language?: string;
+  /** The published other-name type; absent for the legal name. */
+  type?: string;
+}
+
+export interface IGleifAddress {
+  addressLines: string[];
+  city: string;
+  country: string;
+  language?: string;
+  region?: string;
+  postalCode?: string;
+  addressNumber?: string;
+  addressNumberWithinBuilding?: string;
+  mailRouting?: string;
+}
+
+/** Level 1 reference data, with source strings and ISO 8601 dates preserved. No persistence. */
+export interface IGleifRecord {
+  lei: string;
+  legalName: IGleifName;
+  otherNames: IGleifName[];
+  transliteratedOtherNames: IGleifName[];
+  legalForm?: { elfCode?: string; other?: string };
+  legalAddress: IGleifAddress;
+  headquartersAddress: IGleifAddress;
+  jurisdiction?: string;
+  entityStatus: string;
+  entityCategory?: string;
+  registrationAuthority?: { id?: string; otherId?: string; entityId?: string };
+  registrationStatus: string;
+  initialRegistrationDate: string;
+  lastUpdateDate: string;
+}
+
+export type TGleifDelta = 'IntraDay' | 'LastDay' | 'LastWeek' | 'LastMonth';
+export type TGleifFileKind = 'GoldenCopy' | TGleifDelta;
+
+/** The API's LEI-CDF 3.1 ZIP/CSV descriptor. `size` is compressed bytes. */
+export interface IGleifGoldenCopyFile {
+  url: string;
+  format: 'csv';
+  cdfVersion: 'LEI_3.1';
+  kind: TGleifFileKind;
+  recordCount: number;
+  size: number;
+}
+
+export interface IGleifPublish {
+  /** UTC publication label exactly as returned, `YYYY-MM-DD HH:mm:ss`. */
+  publishDate: string;
+  fullFile: IGleifGoldenCopyFile;
+  deltaFiles: Record<TGleifDelta, IGleifGoldenCopyFile>;
+}
+
+export type TGleifFetch = (input: string, init: RequestInit) => Promise<Response>;
+
+export interface IGleifClientOptions {
+  fetch?: TGleifFetch;
+  /** Default: https://goldencopy.gleif.org/api/v2 */
+  goldenCopyBaseUrl?: string;
+  /** Default: https://api.gleif.org/api/v1 */
+  restBaseUrl?: string;
+  userAgent?: string;
+  /** Per request, including streaming and consumer time; default 30 minutes. */
+  timeoutMs?: number;
+}
+
+export interface IGleifReadOptions {
+  /** ISO 3166-1 alpha-2; compares the legal address's country, not the headquarters. */
+  country?: string;
+  /** Exact legal jurisdiction, e.g. DE or US-DE. Both filters, if given, must match. */
+  jurisdiction?: string;
+  signal?: AbortSignal;
+  /** Maximum CSV row size in Unicode code points, including the header; default 1,048,576. */
+  maxRowChars?: number;
+}
+
+export interface IGleifStreamOptions extends IGleifReadOptions {
+  /** Default GoldenCopy; deltas overlap and are current records, not event histories. */
+  kind?: TGleifFileKind;
+}
+
+export interface IGleifRegisterNumber {
+  type: TRegisterType;
+  number: string;
+}
+
+export interface IGleifRegistrationAuthority {
+  raCode: string;
+  name: string;
+  jurisdiction: string;
+  registerName: string;
+  courtCode?: string;
+  /** Present exactly when this German RA has no court in opendata's list. */
+  unmappedReason?: string;
+}
+
+export interface IGleifUnmappedCourt {
+  courtCode: string;
+  name: string;
+  reason: string;
+}

package/ts/gleif/plugins.ts

@@ -0,0 +1,2 @@
+// External dependencies for this subpath only; no portal client or storage imports.
+export { fflate } from '../plugins.js';

package/ts/gleif/records.ts

@@ -0,0 +1,104 @@
+import { GleifError } from './classes.gleiferror.js';
+import type { IGleifAddress, IGleifName, IGleifRecord } from './interfaces.js';
+
+const bad = (labelArg: string): never => { throw new GleifError('unexpected_answer', `Missing or invalid GLEIF ${labelArg}.`); };
+const object = (valueArg: unknown, labelArg: string): Record<string, unknown> =>
+  valueArg && typeof valueArg === 'object' && !Array.isArray(valueArg) ? valueArg as Record<string, unknown> : bad(labelArg);
+const optional = (valueArg: unknown): string | undefined => {
+  if (valueArg === undefined || valueArg === null || valueArg === '') return undefined;
+  return typeof valueArg === 'string' ? valueArg : bad('string');
+};
+const required = (valueArg: unknown, labelArg: string): string => optional(valueArg) ?? bad(labelArg);
+const date = (valueArg: unknown, labelArg: string): string => {
+  const value = required(valueArg, labelArg);
+  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) || !Number.isFinite(Date.parse(value))) bad(labelArg);
+  return value;
+};
+const compact = <TArg extends object>(valueArg: TArg): TArg => Object.fromEntries(Object.entries(valueArg).filter(([, valueArg]) => valueArg !== undefined)) as TArg;
+const name = (valueArg: unknown): IGleifName => {
+  const value = object(valueArg, 'name');
+  return compact({ name: required(value.name, 'name'), language: optional(value.language), type: optional(value.type) });
+};
+const names = (valueArg: unknown): IGleifName[] => {
+  if (valueArg === undefined || valueArg === null) return [];
+  if (!Array.isArray(valueArg)) bad('names');
+  return (valueArg as unknown[]).map(name);
+};
+const address = (valueArg: unknown): IGleifAddress => {
+  const value = object(valueArg, 'address');
+  if (!Array.isArray(value.addressLines) || value.addressLines.length < 1) bad('address lines');
+  return compact({
+    addressLines: (value.addressLines as unknown[]).map((lineArg) => required(lineArg, 'address line')),
+    city: required(value.city, 'city'), country: required(value.country, 'country'),
+    language: optional(value.language), region: optional(value.region), postalCode: optional(value.postalCode),
+    addressNumber: optional(value.addressNumber), addressNumberWithinBuilding: optional(value.addressNumberWithinBuilding), mailRouting: optional(value.mailRouting),
+  });
+};
+
+/** Maps the documented JSON:API attributes, not the differently shaped Golden Copy JSON. */
+export const parseGleifRestRecord = (valueArg: unknown): IGleifRecord => {
+  const data = object(object(valueArg, 'response').data, 'data');
+  if (data.type !== 'lei-records') bad('resource type');
+  const attributes = object(data.attributes, 'attributes');
+  const entity = object(attributes.entity, 'entity');
+  const registration = object(attributes.registration, 'registration');
+  const lei = required(attributes.lei, 'LEI');
+  if (!/^[A-Z0-9]{18}\d{2}$/.test(lei) || data.id !== lei) bad('LEI');
+  const legalForm = entity.legalForm === undefined || entity.legalForm === null ? undefined : object(entity.legalForm, 'legal form');
+  const registeredAt = entity.registeredAt === undefined || entity.registeredAt === null ? undefined : object(entity.registeredAt, 'registration authority');
+  const form = legalForm ? compact({ elfCode: optional(legalForm.id), other: optional(legalForm.other) }) : undefined;
+  const authority = compact({ id: optional(registeredAt?.id), otherId: optional(registeredAt?.other), entityId: optional(entity.registeredAs) });
+  return compact({
+    lei, legalName: name(entity.legalName), otherNames: names(entity.otherNames), transliteratedOtherNames: names(entity.transliteratedOtherNames),
+    legalForm: form && Object.keys(form).length ? form : undefined,
+    legalAddress: address(entity.legalAddress), headquartersAddress: address(entity.headquartersAddress),
+    jurisdiction: optional(entity.jurisdiction), entityStatus: required(entity.status, 'entity status'), entityCategory: optional(entity.category),
+    registrationAuthority: Object.keys(authority).length ? authority : undefined,
+    registrationStatus: required(registration.status, 'registration status'),
+    initialRegistrationDate: date(registration.initialRegistrationDate, 'initial registration date'), lastUpdateDate: date(registration.lastUpdateDate, 'last update date'),
+  });
+};
+
+/** Column names verified against the published LEI-CDF 3.1 CSV (the optional values may be empty). */
+export const gleifCsvColumns = [
+  'LEI', 'Entity.LegalName', 'Entity.LegalName.xmllang', 'Entity.LegalJurisdiction', 'Entity.EntityStatus', 'Entity.EntityCategory',
+  'Entity.LegalForm.EntityLegalFormCode', 'Entity.LegalForm.OtherLegalForm',
+  'Entity.RegistrationAuthority.RegistrationAuthorityID', 'Entity.RegistrationAuthority.OtherRegistrationAuthorityID', 'Entity.RegistrationAuthority.RegistrationAuthorityEntityID',
+  'Registration.RegistrationStatus', 'Registration.InitialRegistrationDate', 'Registration.LastUpdateDate',
+  ...['Entity.LegalAddress', 'Entity.HeadquartersAddress'].flatMap((prefixArg) => ['FirstAddressLine', 'City', 'Country'].map((fieldArg) => `${prefixArg}.${fieldArg}`)),
+] as const;
+
+export const csvRecordMapper = (headerArg: string[]): ((rowArg: string[]) => IGleifRecord) => {
+  if (new Set(headerArg).size !== headerArg.length || gleifCsvColumns.some((columnArg) => !headerArg.includes(columnArg))) {
+    throw new GleifError('invalid_csv', 'Missing or duplicate LEI-CDF 3.1 columns.');
+  }
+  const indices = new Map(headerArg.map((columnArg, indexArg) => [columnArg, indexArg]));
+  const nameColumns = (prefixArg: string): string[] => headerArg.filter((columnArg) => new RegExp(`^${prefixArg.replaceAll('.', '\\.') }\\.\\d+$`).test(columnArg));
+  const otherColumns = nameColumns('Entity.OtherEntityNames.OtherEntityName');
+  const transliteratedColumns = nameColumns('Entity.TransliteratedOtherEntityNames.TransliteratedOtherEntityName');
+  return (rowArg) => {
+    if (rowArg.length !== headerArg.length) throw new GleifError('invalid_csv', 'LEI-CDF CSV row has a different column count from its header.');
+    const get = (columnArg: string): string | undefined => {
+      const index = indices.get(columnArg);
+      return index === undefined ? undefined : rowArg[index];
+    };
+    const nameOf = (prefixArg: string) => ({ name: get(prefixArg), language: get(`${prefixArg}.xmllang`), type: get(`${prefixArg}.type`) });
+    const addressOf = (prefixArg: string) => ({
+      addressLines: [get(`${prefixArg}.FirstAddressLine`), ...[1, 2, 3].map((indexArg) => get(`${prefixArg}.AdditionalAddressLine.${indexArg}`))].filter(Boolean),
+      city: get(`${prefixArg}.City`), country: get(`${prefixArg}.Country`), language: get(`${prefixArg}.xmllang`), region: get(`${prefixArg}.Region`), postalCode: get(`${prefixArg}.PostalCode`),
+      addressNumber: get(`${prefixArg}.AddressNumber`), addressNumberWithinBuilding: get(`${prefixArg}.AddressNumberWithinBuilding`), mailRouting: get(`${prefixArg}.MailRouting`),
+    });
+    const lei = get('LEI');
+    return parseGleifRestRecord({ data: { type: 'lei-records', id: lei, attributes: { lei, entity: {
+      legalName: nameOf('Entity.LegalName'), otherNames: otherColumns.filter((columnArg) => get(columnArg)).map(nameOf),
+      transliteratedOtherNames: transliteratedColumns.filter((columnArg) => get(columnArg)).map(nameOf),
+      legalForm: { id: get('Entity.LegalForm.EntityLegalFormCode'), other: get('Entity.LegalForm.OtherLegalForm') },
+      legalAddress: addressOf('Entity.LegalAddress'), headquartersAddress: addressOf('Entity.HeadquartersAddress'),
+      jurisdiction: get('Entity.LegalJurisdiction'), status: get('Entity.EntityStatus'), category: get('Entity.EntityCategory'),
+      registeredAt: { id: get('Entity.RegistrationAuthority.RegistrationAuthorityID'), other: get('Entity.RegistrationAuthority.OtherRegistrationAuthorityID') },
+      registeredAs: get('Entity.RegistrationAuthority.RegistrationAuthorityEntityID'),
+    }, registration: {
+      status: get('Registration.RegistrationStatus'), initialRegistrationDate: get('Registration.InitialRegistrationDate'), lastUpdateDate: get('Registration.LastUpdateDate'),
+    } } } });
+  };
+};

package/ts/gleif/stream.zip.ts

@@ -0,0 +1,43 @@
+import * as plugins from './plugins.js';
+import { GleifError } from './classes.gleiferror.js';
+
+/** One CSV member, incrementally inflated. Input slices bound each synchronous output batch. */
+export async function* unzipCsv(sourceArg: AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array> {
+  let member: plugins.fflate.UnzipFile | undefined;
+  let complete = false;
+  let failure: Error | undefined;
+  let output: Uint8Array[] = [];
+  const unzipper = new plugins.fflate.Unzip((fileArg) => {
+    if (member || !fileArg.name.toLowerCase().endsWith('.csv')) {
+      throw new GleifError('invalid_archive', 'Expected exactly one CSV member in the Golden Copy ZIP.');
+    }
+    member = fileArg;
+    fileArg.ondata = (errorArg, dataArg, finalArg) => {
+      if (errorArg) failure = errorArg;
+      else if (dataArg.length) output.push(dataArg);
+      if (finalArg) complete = true;
+    };
+    fileArg.start();
+  });
+  unzipper.register(plugins.fflate.UnzipInflate);
+  try {
+    for await (const chunk of sourceArg) {
+      for (let offset = 0; offset < chunk.length; offset += 1024) {
+        unzipper.push(chunk.subarray(offset, offset + 1024));
+        if (failure) throw failure;
+        const ready = output;
+        output = [];
+        for (const data of ready) yield data;
+      }
+    }
+    unzipper.push(new Uint8Array(), true);
+    if (failure) throw failure;
+    for (const data of output) yield data;
+    if (!member || !complete) throw new GleifError('invalid_archive', 'Missing or truncated CSV member in Golden Copy ZIP.');
+  } catch (error) {
+    if (error instanceof GleifError) throw error;
+    throw new GleifError('invalid_archive', 'Could not stream the Golden Copy ZIP.', undefined, { cause: error });
+  } finally {
+    member?.terminate();
+  }
+}

package/ts/handelsregister/data.codelists.ts

@@ -17,6 +17,8 @@ export interface ILegalFormLabel {
   short?: string;
   /** full designation, for example `Gesellschaft mit beschränkter Haftung` */
   long: string;
+  /** economic activity of a natural person, in XUnternehmen category 400000; not a public result field */
+  naturalPerson?: true;
 }
 
 /** XUnternehmen legal form code → designation */
@@ -106,15 +108,15 @@ export const legalFormLabels: Readonly<Record<string, ILegalFormLabel>> = {
   '294000': { short: 'ausl. juristische Person (EU-Recht)', long: 'ausländische juristische Person (EU-Recht)' },
   '295000': { short: 'ausl. juristische Person (Nicht-EU-Recht)', long: 'ausländische juristische Person (Nicht-EU-Recht)' },
   '298100': { short: 'sonst. ausl. juristische Person des privaten Rechts (Auffangtatb. Steuer)', long: 'sonstige ausländische juristische Person des privaten Rechts (Auffangtatbestand Steuer)' },
-  '410000': { long: 'gewerbliches Einzelunternehmen (ohne Hausgewerbe)' },
-  '411000': { short: 'e.K.; e.Kfm.; e.Kfr.', long: 'eingetragenes gewerbliches Einzelunternehmen (e.K.; e.Kfm.; e.Kfr.)' },
-  '411100': { short: 'e.K.; e.Kfm.; e.Kfr. (Sitz in DE)', long: 'eingetragenes gewerbliches Einzelunternehmen (e.K.; e.Kfm.; e.Kfr.) (Sitz in Deutschland)' },
-  '411200': { short: 'e.K.; e.Kfm.; e.Kfr. (Sitz im Ausland)', long: 'eingetragenes gewerbliches Einzelunternehmen (e.K.; e.Kfm.; e.Kfr.) (Sitz im Ausland)' },
-  '422000': { short: 'Land-/Forstwirt', long: 'Land-/Forstwirt' },
-  '428100': { short: 'sonst. wirtsch. Tätigkeit einer nat. Person', long: 'sonstige wirtschaftliche Tätigkeit einer natürlichen Person (Auffangtatbestand)' },
-  '490000': { short: 'ausl. wirtsch. Tätigkeit einer nat. Person', long: 'ausländische wirtschaftliche Tätigkeit einer natürlichen Person' },
-  '491000': { short: 'ausl. gew. Einzelunternehmen (EU-Recht)', long: 'ausländische gewerbliches Einzelunternehmen (EU-Recht)' },
-  '492000': { short: 'ausl. gew. Einzelunternehmen (Nicht-EU-Recht)', long: 'ausländisches gewerbliches Einzelunternehmen (Nicht-EU-Recht)' },
+  '410000': { long: 'gewerbliches Einzelunternehmen (ohne Hausgewerbe)', naturalPerson: true },
+  '411000': { short: 'e.K.; e.Kfm.; e.Kfr.', long: 'eingetragenes gewerbliches Einzelunternehmen (e.K.; e.Kfm.; e.Kfr.)', naturalPerson: true },
+  '411100': { short: 'e.K.; e.Kfm.; e.Kfr. (Sitz in DE)', long: 'eingetragenes gewerbliches Einzelunternehmen (e.K.; e.Kfm.; e.Kfr.) (Sitz in Deutschland)', naturalPerson: true },
+  '411200': { short: 'e.K.; e.Kfm.; e.Kfr. (Sitz im Ausland)', long: 'eingetragenes gewerbliches Einzelunternehmen (e.K.; e.Kfm.; e.Kfr.) (Sitz im Ausland)', naturalPerson: true },
+  '422000': { short: 'Land-/Forstwirt', long: 'Land-/Forstwirt', naturalPerson: true },
+  '428100': { short: 'sonst. wirtsch. Tätigkeit einer nat. Person', long: 'sonstige wirtschaftliche Tätigkeit einer natürlichen Person (Auffangtatbestand)', naturalPerson: true },
+  '490000': { short: 'ausl. wirtsch. Tätigkeit einer nat. Person', long: 'ausländische wirtschaftliche Tätigkeit einer natürlichen Person', naturalPerson: true },
+  '491000': { short: 'ausl. gew. Einzelunternehmen (EU-Recht)', long: 'ausländische gewerbliches Einzelunternehmen (EU-Recht)', naturalPerson: true },
+  '492000': { short: 'ausl. gew. Einzelunternehmen (Nicht-EU-Recht)', long: 'ausländisches gewerbliches Einzelunternehmen (Nicht-EU-Recht)', naturalPerson: true },
   '540000': { short: 'Gewerbebetrieb einer KöR', long: 'Gewerbebetrieb einer Körperschaft des öffentlichen Rechts' },
   '581000': { long: 'sonstige wirtschaftliche Tätigkeit einer nicht-natürlichen Person (Auffangtatbestand)' },
   '681000': { short: 'Freitext', long: 'Freitext (Auffangtatbestand)' },

package/ts/handelsregister/interfaces.ts

@@ -178,7 +178,11 @@ export interface IRegisterContentRegister {
 
 /** 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 */
+  /**
+   * The registered entity: natural-person business legal forms mean person, even in an XJustiz
+   * organisation element. Otherwise an organisation holder means organisation, its absence person.
+   * Unknown/missing legal forms retain that structural rule; representatives do not decide it.
+   */
   entityKind: 'organisation' | 'person';
   name: string;
   legalForm?: IRegisterLegalForm;

package/ts/handelsregister/parse.structuredcontent.ts

@@ -120,7 +120,7 @@ const readLegalForm = (organisationsArg: TXmlElement[]): IRegisterLegalForm | un
     const code = codeAt(organisation, 'angabenZurRechtsform', 'rechtsform');
     if (code) {
       const label = legalFormLabels[code];
-      return label ? { code, ...label } : { code };
+      return label ? { code, ...(label.short ? { short: label.short } : {}), long: label.long } : { code };
     }
   }
   return undefined;
@@ -313,8 +313,11 @@ export const parseStructuredContent = (xmlArg: string): IRegisterStructuredConte
   }
 
   const holders = entityRole.participant.kind === 'person' ? [...organisations, entityRole.participant.element] : organisations;
+  const legalForm = readLegalForm(organisations);
   const content: IRegisterStructuredContent = {
-    entityKind: organisations.length > 0 ? 'organisation' : 'person',
+    // XJustiz also represents natural-person businesses as organisations. Unknown/missing forms
+    // retain the structural rule: an organisation holder means organisation, otherwise person.
+    entityKind: legalForm && legalFormLabels[legalForm.code]?.naturalPerson ? 'person' : organisations.length > 0 ? 'organisation' : 'person',
     name,
     register: readRegister(root, organisations),
     representationStated: entitled.length > 0,
@@ -322,7 +325,6 @@ export const parseStructuredContent = (xmlArg: string): IRegisterStructuredConte
     binding: false,
     notice: structuredContentNotice,
   };
-  const legalForm = readLegalForm(organisations);
   const seat = readSeat(organisations);
   const address = readAddress(holders);
   const status = readStatus(baseData);

package/ts/plugins.ts

@@ -24,3 +24,7 @@ export {
   smartpromise,
   smartrequest,
 }
+
+// third-party scope
+import * as fflate from 'fflate';
+export { fflate };