@fin.cx/opendata 4.7.0 → 4.8.0

package/ts/financialstatements/parse.statement.ts

@@ -0,0 +1,26 @@
+import { FinancialStatementError } from './classes.financialstatementerror.js';
+import { maxStatementBytes } from './constants.js';
+import { decodeHtml } from './html.js';
+import { htmlLayout } from './layout.html.js';
+import { pdfLayout } from './layout.pdf.js';
+import { statementMediaTypeOf } from './mediatypes.js';
+import { readHgbStatement } from './parse.hgb.js';
+import type { IHgbStatement } from './interfaces.js';
+
+/**
+ * Reads a statement under the HGB from the HTML or the PDF a register shows: the balance sheet
+ * (§ 266 HGB) and, where one is published, the income statement (§ 275 HGB). Everything it returns
+ * was printed and adds up; where the current year's balance sheet cannot be read with certainty it
+ * throws `unparseable` rather than guess. A PDF is read from its text layer only.
+ */
+export const parseStatementDocument = async (bytesArg: Uint8Array, mediaTypeArg: string): Promise<IHgbStatement> => {
+  const mediaType = statementMediaTypeOf(mediaTypeArg);
+  if (mediaType !== 'text/html' && mediaType !== 'application/xhtml+xml' && mediaType !== 'application/pdf') {
+    throw new FinancialStatementError('unsupported_media_type', `A statement in "${mediaTypeArg}" is not read here; HTML and PDF are.`);
+  }
+  if (bytesArg.byteLength > maxStatementBytes) {
+    throw new FinancialStatementError('too_large', `The document has ${bytesArg.byteLength} bytes, more than the ${maxStatementBytes} read here.`);
+  }
+  const blocks = mediaType === 'application/pdf' ? await pdfLayout(bytesArg) : htmlLayout(decodeHtml(bytesArg));
+  return readHgbStatement(blocks);
+};

package/ts/financialstatements/plugins.ts

@@ -0,0 +1,29 @@
+// This entry point stands alone: it imports nothing from the rest of the package and needs no storage.
+
+// node native scope
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+
+export {
+  path,
+  createRequire,
+}
+
+// @push.rocks scope
+import * as smartarchiveZip from '@push.rocks/smartarchive/web/zip';
+import * as smartxmlXpath from '@push.rocks/smartxml/xpath';
+
+export {
+  smartarchiveZip,
+  smartxmlXpath,
+}
+
+// third party scope
+import * as parse5 from 'parse5';
+
+export {
+  parse5,
+}
+
+/** PDF.js for Node.js (its legacy build), loaded when the first PDF is read */
+export const loadPdfjs = () => import('pdfjs-dist/legacy/build/pdf.mjs');

package/ts/financialstatements/read.ts

@@ -0,0 +1,135 @@
+import { FinancialStatementError } from './classes.financialstatementerror.js';
+import { maxStatementBytes, unternehmensregisterNotice } from './constants.js';
+import { statementMediaTypeOf } from './mediatypes.js';
+import { parseEsefPackage, parseEsefReport } from './parse.esef.js';
+import { parseStatementDocument } from './parse.statement.js';
+import type {
+  IFiling,
+  IFinancialStatement,
+  IReadFinancialStatementOptions,
+  IStatementParseFailure,
+  TFilingKind,
+  TFilingSource,
+  TParsedStatement,
+  TSizeClass,
+} from './interfaces.js';
+
+const filingSources: TFilingSource[] = ['unternehmensregister', 'bundesanzeiger', 'issuer', 'unknown'];
+const filingKinds: TFilingKind[] = ['annual_accounts', 'consolidated_accounts', 'deposited_balance_sheet', 'annual_financial_report'];
+const sizeClasses: TSizeClass[] = ['micro', 'small', 'medium', 'large'];
+const parseFailureCodes = new Set<string>(['invalid_package', 'unreadable', 'no_text', 'unparseable', 'too_large']);
+
+/** the inline XBRL namespace, which marks an HTML document as an ESEF report */
+const inlineXbrlNamespace = 'http://www.xbrl.org/2013/inlineXBRL';
+
+const invalid = (messageArg: string): never => {
+  throw new FinancialStatementError('invalid_input', messageArg);
+};
+
+const isIsoDate = (valueArg: string): boolean => {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(valueArg)) {
+    return false;
+  }
+  const date = new Date(`${valueArg}T00:00:00Z`);
+  return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === valueArg;
+};
+
+const filingOf = (inputArg: IReadFinancialStatementOptions['filing']): IFiling => {
+  if (!filingSources.includes(inputArg?.source)) {
+    invalid(`The filing's source "${inputArg?.source}" is not one of ${filingSources.join(', ')}.`);
+  }
+  if (!filingKinds.includes(inputArg.kind)) {
+    invalid(`The filing's kind "${inputArg.kind}" is not one of ${filingKinds.join(', ')}.`);
+  }
+  if (inputArg.sizeClass != null && !sizeClasses.includes(inputArg.sizeClass)) {
+    invalid(`The filing's size class "${inputArg.sizeClass}" is not one of ${sizeClasses.join(', ')}.`);
+  }
+  for (const field of ['fiscalYearStart', 'fiscalYearEnd', 'publishedOn'] as const) {
+    const value = inputArg[field];
+    if (value != null && (typeof value !== 'string' || !isIsoDate(value))) {
+      invalid(`The filing's ${field} "${value}" is not an ISO date (YYYY-MM-DD).`);
+    }
+  }
+  if (inputArg.source === 'unternehmensregister' && inputArg.publishedOn == null) {
+    invalid('A filing from the Unternehmensregister needs publishedOn, the day it was posted or deposited, for its origin note.');
+  }
+  return {
+    source: inputArg.source,
+    kind: inputArg.kind,
+    companyName: inputArg.companyName ?? null,
+    registerReference: inputArg.registerReference ?? null,
+    lei: inputArg.lei ?? null,
+    fiscalYearStart: inputArg.fiscalYearStart ?? null,
+    fiscalYearEnd: inputArg.fiscalYearEnd ?? null,
+    publishedOn: inputArg.publishedOn ?? null,
+    title: inputArg.title ?? null,
+    sizeClass: inputArg.sizeClass ?? null,
+    documentId: inputArg.documentId ?? null,
+    sourceUrl: inputArg.sourceUrl ?? null,
+  };
+};
+
+const sha256Of = async (bytesArg: Uint8Array<ArrayBuffer>): Promise<string> => {
+  const digest = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', bytesArg));
+  return [...digest].map((byteArg) => byteArg.toString(16).padStart(2, '0')).join('');
+};
+
+/**
+ * Keeps a published statement as a caller stores it: the filing as the caller states it, the
+ * document byte for byte with its SHA-256, and what could be read from it: an ESEF report by
+ * `parseEsefPackage` or `parseEsefReport`, any other HTML or PDF by `parseStatementDocument`. A
+ * document that cannot be read with certainty is kept with `parsed` null and `parseFailure` saying
+ * why. Throws `invalid_input`, `unsupported_media_type` and, for a document larger than
+ * `maxStatementBytes`, `too_large`, as nothing would be kept.
+ */
+export const readFinancialStatement = async (optionsArg: IReadFinancialStatementOptions): Promise<IFinancialStatement> => {
+  if (!(optionsArg?.bytes instanceof Uint8Array)) {
+    invalid('bytes must be a Uint8Array.');
+  }
+  const filing = filingOf(optionsArg.filing);
+  if (optionsArg.bytes.byteLength > maxStatementBytes) {
+    throw new FinancialStatementError(
+      'too_large',
+      `The document has ${optionsArg.bytes.byteLength} bytes, more than the ${maxStatementBytes} read here.`
+    );
+  }
+  const mediaType = statementMediaTypeOf(String(optionsArg.mediaType));
+  if (!mediaType) {
+    throw new FinancialStatementError(
+      'unsupported_media_type',
+      `A statement in "${optionsArg.mediaType}" is not read here; HTML, PDF, XHTML and ZIP packages are.`
+    );
+  }
+  const bytes = new Uint8Array(optionsArg.bytes);
+  const sha256 = await sha256Of(bytes);
+  let parsed: TParsedStatement | null = null;
+  let parseFailure: IStatementParseFailure | null = null;
+  try {
+    if (mediaType === 'application/zip') {
+      parsed = await parseEsefPackage(bytes);
+    } else if (
+      mediaType === 'application/xhtml+xml' ||
+      (mediaType === 'text/html' && new TextDecoder('windows-1252').decode(bytes.subarray(0, 65536)).includes(inlineXbrlNamespace))
+    ) {
+      parsed = parseEsefReport(bytes);
+    } else {
+      parsed = await parseStatementDocument(bytes, mediaType);
+    }
+  } catch (error) {
+    if (!(error instanceof FinancialStatementError) || !parseFailureCodes.has(error.code)) {
+      throw error;
+    }
+    parseFailure = { code: error.code as IStatementParseFailure['code'], message: error.message };
+  }
+  return {
+    filing,
+    raw: { bytes, mediaType, sha256 },
+    parsed,
+    parseFailure,
+    obtainedAt: (optionsArg.now ?? Date.now)(),
+    notice:
+      filing.source === 'unternehmensregister'
+        ? unternehmensregisterNotice(filing.publishedOn as string, filing.kind === 'deposited_balance_sheet')
+        : null,
+  };
+};