@fin.cx/opendata 4.7.0 → 4.8.0

package/dist_ts/financialstatements/parse.statement.d.ts

@@ -0,0 +1,8 @@
+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 declare const parseStatementDocument: (bytesArg: Uint8Array, mediaTypeArg: string) => Promise<IHgbStatement>;

package/dist_ts/financialstatements/parse.statement.js

@@ -0,0 +1,25 @@
+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';
+/**
+ * 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, mediaTypeArg) => {
+    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);
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGFyc2Uuc3RhdGVtZW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvZmluYW5jaWFsc3RhdGVtZW50cy9wYXJzZS5zdGF0ZW1lbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxFQUFFLHVCQUF1QixFQUFFLE1BQU0sc0NBQXNDLENBQUM7QUFDL0UsT0FBTyxFQUFFLGlCQUFpQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFDbkQsT0FBTyxFQUFFLFVBQVUsRUFBRSxNQUFNLFdBQVcsQ0FBQztBQUN2QyxPQUFPLEVBQUUsVUFBVSxFQUFFLE1BQU0sa0JBQWtCLENBQUM7QUFDOUMsT0FBTyxFQUFFLFNBQVMsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQzVDLE9BQU8sRUFBRSxvQkFBb0IsRUFBRSxNQUFNLGlCQUFpQixDQUFDO0FBQ3ZELE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLGdCQUFnQixDQUFDO0FBR2xEOzs7OztHQUtHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sc0JBQXNCLEdBQUcsS0FBSyxFQUFFLFFBQW9CLEVBQUUsWUFBb0IsRUFBMEIsRUFBRTtJQUNqSCxNQUFNLFNBQVMsR0FBRyxvQkFBb0IsQ0FBQyxZQUFZLENBQUMsQ0FBQztJQUNyRCxJQUFJLFNBQVMsS0FBSyxXQUFXLElBQUksU0FBUyxLQUFLLHVCQUF1QixJQUFJLFNBQVMsS0FBSyxpQkFBaUIsRUFBRSxDQUFDO1FBQzFHLE1BQU0sSUFBSSx1QkFBdUIsQ0FBQyx3QkFBd0IsRUFBRSxtQkFBbUIsWUFBWSx1Q0FBdUMsQ0FBQyxDQUFDO0lBQ3RJLENBQUM7SUFDRCxJQUFJLFFBQVEsQ0FBQyxVQUFVLEdBQUcsaUJBQWlCLEVBQUUsQ0FBQztRQUM1QyxNQUFNLElBQUksdUJBQXVCLENBQUMsV0FBVyxFQUFFLG9CQUFvQixRQUFRLENBQUMsVUFBVSx5QkFBeUIsaUJBQWlCLGFBQWEsQ0FBQyxDQUFDO0lBQ2pKLENBQUM7SUFDRCxNQUFNLE1BQU0sR0FBRyxTQUFTLEtBQUssaUJBQWlCLENBQUMsQ0FBQyxDQUFDLE1BQU0sU0FBUyxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsQ0FBQyxVQUFVLENBQUMsVUFBVSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUM7SUFDOUcsT0FBTyxnQkFBZ0IsQ0FBQyxNQUFNLENBQUMsQ0FBQztBQUNsQyxDQUFDLENBQUMifQ==

package/dist_ts/financialstatements/plugins.d.ts

@@ -0,0 +1,10 @@
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+export { path, createRequire, };
+import * as smartarchiveZip from '@push.rocks/smartarchive/web/zip';
+import * as smartxmlXpath from '@push.rocks/smartxml/xpath';
+export { smartarchiveZip, smartxmlXpath, };
+import * as parse5 from 'parse5';
+export { parse5, };
+/** PDF.js for Node.js (its legacy build), loaded when the first PDF is read */
+export declare const loadPdfjs: () => Promise<typeof import("pdfjs-dist/legacy/build/pdf.mjs")>;

package/dist_ts/financialstatements/plugins.js

@@ -0,0 +1,15 @@
+// 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');
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2ZpbmFuY2lhbHN0YXRlbWVudHMvcGx1Z2lucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSx1R0FBdUc7QUFFdkcsb0JBQW9CO0FBQ3BCLE9BQU8sS0FBSyxJQUFJLE1BQU0sV0FBVyxDQUFDO0FBQ2xDLE9BQU8sRUFBRSxhQUFhLEVBQUUsTUFBTSxhQUFhLENBQUM7QUFFNUMsT0FBTyxFQUNMLElBQUksRUFDSixhQUFhLEdBQ2QsQ0FBQTtBQUVELG9CQUFvQjtBQUNwQixPQUFPLEtBQUssZUFBZSxNQUFNLGtDQUFrQyxDQUFDO0FBQ3BFLE9BQU8sS0FBSyxhQUFhLE1BQU0sNEJBQTRCLENBQUM7QUFFNUQsT0FBTyxFQUNMLGVBQWUsRUFDZixhQUFhLEdBQ2QsQ0FBQTtBQUVELG9CQUFvQjtBQUNwQixPQUFPLEtBQUssTUFBTSxNQUFNLFFBQVEsQ0FBQztBQUVqQyxPQUFPLEVBQ0wsTUFBTSxHQUNQLENBQUE7QUFFRCwrRUFBK0U7QUFDL0UsTUFBTSxDQUFDLE1BQU0sU0FBUyxHQUFHLEdBQUcsRUFBRSxDQUFDLE1BQU0sQ0FBQyxpQ0FBaUMsQ0FBQyxDQUFDIn0=

package/dist_ts/financialstatements/read.d.ts

@@ -0,0 +1,10 @@
+import type { IFinancialStatement, IReadFinancialStatementOptions } from './interfaces.js';
+/**
+ * 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 declare const readFinancialStatement: (optionsArg: IReadFinancialStatementOptions) => Promise<IFinancialStatement>;

package/dist_ts/financialstatements/read.js

@@ -0,0 +1,113 @@
+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';
+const filingSources = ['unternehmensregister', 'bundesanzeiger', 'issuer', 'unknown'];
+const filingKinds = ['annual_accounts', 'consolidated_accounts', 'deposited_balance_sheet', 'annual_financial_report'];
+const sizeClasses = ['micro', 'small', 'medium', 'large'];
+const parseFailureCodes = new Set(['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) => {
+    throw new FinancialStatementError('invalid_input', messageArg);
+};
+const isIsoDate = (valueArg) => {
+    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) => {
+    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']) {
+        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) => {
+    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) => {
+    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 = null;
+    let parseFailure = 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, message: error.message };
+    }
+    return {
+        filing,
+        raw: { bytes, mediaType, sha256 },
+        parsed,
+        parseFailure,
+        obtainedAt: (optionsArg.now ?? Date.now)(),
+        notice: filing.source === 'unternehmensregister'
+            ? unternehmensregisterNotice(filing.publishedOn, filing.kind === 'deposited_balance_sheet')
+            : null,
+    };
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicmVhZC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2ZpbmFuY2lhbHN0YXRlbWVudHMvcmVhZC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQUUsdUJBQXVCLEVBQUUsTUFBTSxzQ0FBc0MsQ0FBQztBQUMvRSxPQUFPLEVBQUUsaUJBQWlCLEVBQUUsMEJBQTBCLEVBQUUsTUFBTSxnQkFBZ0IsQ0FBQztBQUMvRSxPQUFPLEVBQUUsb0JBQW9CLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUN2RCxPQUFPLEVBQUUsZ0JBQWdCLEVBQUUsZUFBZSxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFDcEUsT0FBTyxFQUFFLHNCQUFzQixFQUFFLE1BQU0sc0JBQXNCLENBQUM7QUFZOUQsTUFBTSxhQUFhLEdBQW9CLENBQUMsc0JBQXNCLEVBQUUsZ0JBQWdCLEVBQUUsUUFBUSxFQUFFLFNBQVMsQ0FBQyxDQUFDO0FBQ3ZHLE1BQU0sV0FBVyxHQUFrQixDQUFDLGlCQUFpQixFQUFFLHVCQUF1QixFQUFFLHlCQUF5QixFQUFFLHlCQUF5QixDQUFDLENBQUM7QUFDdEksTUFBTSxXQUFXLEdBQWlCLENBQUMsT0FBTyxFQUFFLE9BQU8sRUFBRSxRQUFRLEVBQUUsT0FBTyxDQUFDLENBQUM7QUFDeEUsTUFBTSxpQkFBaUIsR0FBRyxJQUFJLEdBQUcsQ0FBUyxDQUFDLGlCQUFpQixFQUFFLFlBQVksRUFBRSxTQUFTLEVBQUUsYUFBYSxFQUFFLFdBQVcsQ0FBQyxDQUFDLENBQUM7QUFFcEgsZ0ZBQWdGO0FBQ2hGLE1BQU0sbUJBQW1CLEdBQUcscUNBQXFDLENBQUM7QUFFbEUsTUFBTSxPQUFPLEdBQUcsQ0FBQyxVQUFrQixFQUFTLEVBQUU7SUFDNUMsTUFBTSxJQUFJLHVCQUF1QixDQUFDLGVBQWUsRUFBRSxVQUFVLENBQUMsQ0FBQztBQUNqRSxDQUFDLENBQUM7QUFFRixNQUFNLFNBQVMsR0FBRyxDQUFDLFFBQWdCLEVBQVcsRUFBRTtJ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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@fin.cx/opendata",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "private": false,
-  "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, the German consumer price index with the arithmetic of index clauses, and stock and crypto prices and fundamentals from several providers.",
+  "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, the German consumer price index with the arithmetic of index clauses, published financial statements read from their HTML, PDF or ESEF documents, and stock and crypto prices and fundamentals from several providers.",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "exports": {
@@ -30,6 +30,10 @@
       "types": "./dist_ts/cpi/index.d.ts",
       "import": "./dist_ts/cpi/index.js"
     },
+    "./financialstatements": {
+      "types": "./dist_ts/financialstatements/index.d.ts",
+      "import": "./dist_ts/financialstatements/index.js"
+    },
     "./package.json": "./package.json"
   },
   "type": "module",
@@ -43,11 +47,13 @@
     "@types/node": "26.6.4"
   },
   "dependencies": {
+    "@push.rocks/smartarchive": "^5.5.2",
     "@push.rocks/smartpath": "^6.0.0",
     "@push.rocks/smartpromise": "^4.3.0",
     "@push.rocks/smartrequest": "^5.0.1",
     "@push.rocks/smartxml": "^2.1.0",
-    "parse5": "^8.0.1"
+    "parse5": "^8.0.1",
+    "pdfjs-dist": "^6.3.289"
   },
   "repository": {
     "type": "git",
@@ -93,7 +99,11 @@
     "base rate",
     "consumer price index",
     "Verbraucherpreisindex",
-    "index clause"
+    "index clause",
+    "Jahresabschluss",
+    "financial statements",
+    "HGB",
+    "ESEF"
   ],
   "scripts": {
     "test": "(tstest test/ --verbose)",

package/readme.md

@@ -1,8 +1,8 @@
 # @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, the statutory public holidays of the German federal states, the base rate of § 247 BGB, and the German consumer price index for index clauses. 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, the base rate of § 247 BGB, the German consumer price index for index clauses, and the figures of published financial statements. It is built for programmers who want scriptable APIs and real workflows instead of a thin wrapper around one remote endpoint.
 
-It gives you seven practical lanes in one package:
+It gives you eight 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
@@ -11,6 +11,7 @@ It gives you seven practical lanes in one package:
 - 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
 - the consumer price index, from `@fin.cx/opendata/cpi`, for the Verbraucherpreisindex für Deutschland of the Statistisches Bundesamt as the Deutsche Bundesbank republishes it, with the arithmetic of index clauses (Wertsicherungsklauseln, § 557b BGB), without any storage
+- published financial statements, from `@fin.cx/opendata/financialstatements`, for the balance sheet and the income statement under the HGB from the HTML or the PDF the Unternehmensregister shows, and the facts of an ESEF report, read from a document the caller obtained, without any request or storage
 
 ## Issue Reporting and Security
 
@@ -179,6 +180,69 @@ The figures are the Statistisches Bundesamt's, under the Datenlizenz Deutschland
 
 A change in percent, a threshold or a scaled amount is not a published figure. Mark it as such, for example "eigene Berechnung", next to the source note.
 
+### Published Financial Statements
+
+Everything here comes from `@fin.cx/opendata/financialstatements`. That entry point imports nothing else of the package, makes no request and keeps nothing. It reads a statement from the bytes the caller obtained, such as a statement saved from the Unternehmensregister, and returns what the caller stores: the filing, the document byte for byte, and what could be read from it. Its types hold no storage of their own, so any store can keep them.
+
+- `readFinancialStatement({ filing, bytes, mediaType, now? })`
+  A statement as a caller keeps it (`IFinancialStatement`): the filing as the caller states it (`filing`, an `IFiling`), the document with its media type and SHA-256 (`raw`), the statement read from it (`parsed`), why none was (`parseFailure`), when it was obtained (`obtainedAt`) and the publisher's origin note (`notice`). An ESEF report, on its own or in its package, goes to the ESEF reader, and so does HTML that holds inline XBRL; any other HTML or PDF goes to `parseStatementDocument`.
+- `parseStatementDocument(bytes, mediaType)`
+  A statement under the HGB from the HTML or the PDF a register shows (`IHgbStatement`): the balance sheet (§ 266 HGB) and, where one is published, the income statement (§ 275 HGB, by the total cost or the cost of sales method), each printed line with its outline code, label, kind and the amounts of both years, the unit (EUR, TEUR or Mio. EUR), the periods, and the key figures: balance sheet total, equity, net income and revenue. A PDF is read from its text layer.
+- `parseEsefPackage(zipBytes)`, `parseEsefReport(xhtmlBytes, reportPath?)`
+  A listed issuer's annual financial report in the European Single Electronic Format (`IEsefStatement`): the LEI, every numeric fact its inline XBRL tags (concept, period, dimensions, unit, and the value with scale and sign applied), and the key figures of its consolidated statements from the IFRS concepts `Assets`, `Equity`, `ProfitLoss` and `Revenue`. A package must hold exactly one report under `reports/`.
+- `unternehmensregisterNotice(publishedOn, deposited?)`, `unternehmensregisterOrigin`
+  The Unternehmensregister's origin note, "Auszug aus dem Unternehmensregister", with the day a document was posted or deposited.
+- `maxStatementBytes` (100 MiB), `maxPdfPages` (500), `maxEsefFacts` (100,000), `maxEsefPackageEntries` (10,000)
+- `FinancialStatementError` with the codes `invalid_input`, `unsupported_media_type`, `too_large`, `invalid_package`, `unreadable`, `no_text` and `unparseable`
+
+Amounts are decimal strings in the currency itself, the unit's factor applied (`1.234` printed in TEUR is `'1234000'`), never floats.
+
+```typescript
+import { FinancialStatementError, readFinancialStatement } from '@fin.cx/opendata/financialstatements';
+
+const statement = await readFinancialStatement({
+  filing: {
+    source: 'unternehmensregister',
+    kind: 'annual_accounts',
+    companyName: 'Muster Werkzeugbau GmbH',
+    fiscalYearStart: '2024-01-01',
+    fiscalYearEnd: '2024-12-31',
+    publishedOn: '2025-11-03',
+  },
+  bytes, // the PDF as saved from the register, a Uint8Array
+  mediaType: 'application/pdf',
+});
+// statement.raw: { bytes, mediaType: 'application/pdf', sha256: '...' }
+// statement.notice: 'Auszug aus dem Unternehmensregister, eingestellt am 03.11.2025'
+
+if (statement.parsed?.standard === 'hgb') {
+  statement.parsed.keyFigures.current;
+  // { totalAssets: '500000.00', equity: '300000.00', netIncome: '40000.00', revenue: '1000000.00' }
+} else if (statement.parseFailure) {
+  statement.parseFailure; // { code: 'unparseable', message: 'No balance sheet was found.' }
+}
+
+try {
+  await readFinancialStatement({ filing: statement.filing, bytes: scan, mediaType: 'image/png' });
+} catch (error) {
+  if (error instanceof FinancialStatementError) {
+    console.log(error.code); // 'unsupported_media_type': nothing is kept
+  }
+}
+```
+
+#### Read, never guessed
+
+`parsed` is null rather than guessed. Everything `parseStatementDocument` returns was printed and adds up: each position with parts equals their sum, each side of the balance sheet its total, both totals each other, and the lines of the income statement its net income, whether it prints its expenses with a minus or as amounts to subtract. A balance sheet whose current year does not add up, whose columns do not state their year or unit, that holds text where an amount belongs, or that is in a currency other than the euro ends in `unparseable`; `readFinancialStatement` then keeps the document with `parsed` null and the reason in `parseFailure`. A prior year that does not add up, and an income statement that does not, are left out with a note in `notes`. A PDF without a text layer, such as a scan, ends in `no_text`: nothing is recognised from images.
+
+The ESEF reader takes values as the report tags them. It reads the formats `num-dot-decimal`, `num-comma-decimal`, `fixed-zero` and `zerodash` (and the older `numdotdecimal` and `numcommadecimal`); a fact in another format is left out and counted in `notes`. A key figure tagged twice with values that differ at the coarser of their `decimals` is left out with a note.
+
+#### Where the documents come from
+
+The entry point makes no request; the caller obtains each document and passes its bytes in. The statements of financial years beginning after 31 December 2021 are published in the Unternehmensregister, earlier ones in the Bundesanzeiger. Both show a statement only after a security check (a captcha); the Unternehmensregister shows it as HTML and usually also as PDF. A balance sheet a micro company deposited (§ 326 Abs. 2 HGB) is retrieved only for a fee and after registration. Listed issuers publish their ESEF reports on their own sites as well.
+
+The Unternehmensregister's terms of use allow copying the statements it makes accessible by print or as a file (§ 3 Abs. 3) and mark them with the origin note "Auszug aus dem Unternehmensregister" and the day the document was posted, or for a deposited balance sheet the day it was deposited (§ 3 Abs. 5). A filing from the Unternehmensregister therefore needs `publishedOn`, and `notice` gives the note, so that a kept copy keeps it.
+
 ## Before You Start
 
 - No stock or fundamentals providers are pre-registered. You must register them before calling the services.
@@ -613,9 +677,18 @@ Four holidays apply only in part of a state:
 - `bundesbankCpiBaseUrl`, `bundesbankVpiMonthlyKey`, `bundesbankVpiAnnualKey`, `bundesbankVpiFirstMonth`, `bundesbankVpiFirstYear`, `destatisLicence`, `defaultCpiTimeoutMs`
 - `CpiError` with the codes `invalid_input`, `before_first_period`, `not_published`, `base_mismatch`, `series_withdrawn`, `busy`, `unavailable`, `unreachable`, `timeout`, `aborted` and `unexpected_answer`
 
+### Financial statements (`@fin.cx/opendata/financialstatements`)
+
+- `readFinancialStatement({ filing, bytes, mediaType, now? })`
+- `parseStatementDocument(bytes, mediaType)`
+- `parseEsefPackage(zipBytes)`, `parseEsefReport(xhtmlBytes, reportPath?)`
+- `unternehmensregisterNotice(publishedOn, deposited?)`, `unternehmensregisterOrigin`, `maxStatementBytes`, `maxPdfPages`, `maxEsefFacts`, `maxEsefPackageEntries`
+- the types `IFiling`, `IFinancialStatement`, `IHgbStatement`, `IEsefStatement`, `IKeyFigures`, `IStatementPosition` and their parts
+- `FinancialStatementError` with the codes `invalid_input`, `unsupported_media_type`, `too_large`, `invalid_package`, `unreadable`, `no_text` and `unparseable`
+
 ## 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.
+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. Financial statements come from the caller: `@fin.cx/opendata/financialstatements` reads the documents it is given and fetches none.
 
 The package carries two kinds of data: the holiday rules of `@fin.cx/opendata/holidays` (`ts/holidays/data.holidays.ts`), described at the end of this section, and the code tables that `@fin.cx/opendata/handelsregister` uses to decode the structured register content (`ts/handelsregister/data.codelists.ts`). The code tables are official code lists, published on XRepository (https://www.xrepository.de), and were taken on 2026-09-23:
 
@@ -674,6 +747,10 @@ The consumer price index of `@fin.cx/opendata/cpi` is read at run time, one requ
 
 - Not verified: limits on the number of requests to the Bundesbank's API (none is documented) and terms of use specific to it. The Bundesbank's terms for reusing statistics exclude data of third parties, so the figures are used under the Statistisches Bundesamt's licence. Whether the Bundesbank keeps the series of an old base for a while after a change of base year is not known; today the key of 2015=100 answers 404.
 
+The reader of `@fin.cx/opendata/financialstatements` follows the outlines of the balance sheet (§ 266 HGB) and the income statement (§ 275 HGB), the terms of use of the Unternehmensregister (`https://www.unternehmensregister.de/i18n-doc/D061_UReg_nutz_0118_de.pdf`, § 3) and its help page on searching, which names the security check, both read on 2026-10-10. The ESEF reader was also run on two reports issuers published, which are not part of the repository.
+
+- Not verified: the markup the Unternehmensregister and the Bundesanzeiger show a statement in today, and the PDF they make of it. No live statement was opened, to stay clear of the security check; the HTML and PDF readers are tested against documents written in the shape of published statements, not against saved ones. Whether readers can obtain a statement as filed in XML or XBRL is not known either; the help pages name HTML and PDF only.
+
 ## Behavior And Caveats
 
 - Historical market data is cached aggressively because it is treated as immutable.
@@ -681,6 +758,7 @@ The consumer price index of `@fin.cx/opendata/cpi` is read at run time, one requ
 - `StockDataService` is convenience-first. `StockPriceService` is the better low-level choice if you care about request-shape-specific cache behavior.
 - The register lookup reads the portal's German pages and asks for German explicitly. It depends on the portal's current page structure: when that changes, calls end in `unexpected_response` rather than in guessed data.
 - The structured register content is a non-binding service of the portal; the current printout is binding. Results carry `binding: false` and the portal's note.
+- The statement reader depends on how a statement is laid out: when a layout is not one it can read with certainty, the document is kept with `parsed` null rather than read in part or guessed. It reads the balance sheet and the income statement under the HGB and the numeric facts of ESEF reports; the notes and the management report are not read.
 - There is no hosted backend in this package. Everything is meant to run from your own TypeScript/Node process.
 
 ## Testing
@@ -689,7 +767,7 @@ The consumer price index of `@fin.cx/opendata/cpi` is read at run time, one requ
 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. 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. The consumer price index client is tested against the answers the Bundesbank's API gave on 2026-10-05 and two answers written by hand from them (`test/fixtures/cpi/`); the tests never contact it.
+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. The consumer price index client is tested against the answers the Bundesbank's API gave on 2026-10-05 and two answers written by hand from them (`test/fixtures/cpi/`); the tests never contact it. The financial statement reader is tested against HTML statements written by hand in the shape of the register's (`test/fixtures/financialstatements/`), PDFs the tests write themselves, and ESEF reports and packages the tests write, all with synthetic values; the tests contact no register.
 
 ## License and Legal Information
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/opendata',
-  version: '4.7.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, the German consumer price index with the arithmetic of index clauses, and stock and crypto prices and fundamentals from several providers.'
+  version: '4.8.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, the German consumer price index with the arithmetic of index clauses, published financial statements read from their HTML, PDF or ESEF documents, and stock and crypto prices and fundamentals from several providers.'
 }

package/ts/financialstatements/amounts.ts

@@ -0,0 +1,181 @@
+import type { IStatementUnit } from './interfaces.js';
+
+/** millionths of a euro per euro: amounts are kept as whole millionths, so no sum loses a digit */
+const microsPerEuro = 1_000_000n;
+
+/** a step at or below one cent: the amount was printed to the cent and is exact */
+const exactStep = 10_000n;
+
+/**
+ * An amount as this entry point computes with it: millionths of a euro, and the rounding it may
+ * carry. `slack` is twice the largest rounding error, also in millionths: zero for an amount printed
+ * to the cent, the step of the last printed digit for one printed rounded, and the sum of its terms'
+ * slack for a sum.
+ */
+export interface IAmount {
+  micros: bigint;
+  slack: bigint;
+  /** the digits after the decimal point the amount is written with */
+  fractionDigits: number;
+}
+
+/** a number as printed, before its unit is applied */
+export interface IPrintedAmount {
+  /** the printed digits as one integer: `1.234,5` is 12345 */
+  digits: bigint;
+  /** the digits after the decimal comma */
+  decimals: number;
+  /** the unit printed with the number, where one is */
+  unit: IStatementUnit | null;
+}
+
+export const unitEur: IStatementUnit = { label: 'EUR', factor: '1' };
+export const unitTeur: IStatementUnit = { label: 'TEUR', factor: '1000' };
+export const unitMioEur: IStatementUnit = { label: 'Mio. EUR', factor: '1000000' };
+
+/** the euro after a prefix such as `Mio.` or `T` */
+const euroSuffix = String.raw`(?:€|EUR\b|Euro\b|EURO\b)`;
+
+/** the units the statements print, millions and thousands before plain euros */
+const unitPatterns: Array<{ unit: IStatementUnit; pattern: string }> = [
+  { unit: unitMioEur, pattern: String.raw`\b(?:Mio\.?|Millionen)\s*${euroSuffix}` },
+  { unit: unitTeur, pattern: String.raw`\b(?:T|Tsd\.?\s*|Tausend\s+)${euroSuffix}` },
+  { unit: unitEur, pattern: String.raw`(?:€|\b${euroSuffix})` },
+];
+
+const unitAlternation = unitPatterns.map((entryArg) => `(${entryArg.pattern})`).join('|');
+
+/** the units a text names, in the order it names them */
+export const unitsIn = (textArg: string): IStatementUnit[] => {
+  const result: IStatementUnit[] = [];
+  for (const match of textArg.matchAll(new RegExp(unitAlternation, 'g'))) {
+    const index = match.slice(1).findIndex((groupArg) => groupArg !== undefined);
+    result.push(unitPatterns[index].unit);
+  }
+  return result;
+};
+
+/** a text with the units it names blanked out */
+export const withoutUnits = (textArg: string): string => textArg.replace(new RegExp(unitAlternation, 'g'), ' ');
+
+/** the currencies other than the euro a statement may name */
+const otherCurrencySource = String.raw`\b(?:USD|US-Dollar|CHF|GBP|JPY|CNY|DKK|SEK|NOK|PLN|CZK|HUF)\b|\$|£|¥`;
+
+/** whether a text names a currency other than the euro */
+export const namesOtherCurrency = (textArg: string): boolean => new RegExp(otherCurrencySource).test(textArg);
+
+/** a text with the currencies other than the euro it names blanked out */
+export const withoutOtherCurrencies = (textArg: string): string => textArg.replace(new RegExp(otherCurrencySource, 'g'), ' ');
+
+/** the unit alone, `TEUR` or `(in TEUR)`, as a line of its own */
+const unitOnlyPattern = new RegExp(String.raw`^\(?\s*(?:in\s+)?(?:${unitAlternation})\s*\)?$`);
+
+/** the explicit phrases a statement states its unit with: `Angaben in TEUR`, `(Beträge in Euro)` */
+const unitPhrasePattern = new RegExp(
+  String.raw`(?:\(\s*in\s+|\b(?:Angaben|Beträge|Betrag|Werte|Zahlen|Alle Beträge|Zahlenangaben)\s+in\s+)(?:${unitAlternation})`
+);
+
+/** the unit a line of context states, `Angaben in TEUR` or a line that is only a unit; null if none */
+export const unitStatedBy = (textArg: string): IStatementUnit | null => {
+  const text = normalizeSpaces(textArg);
+  if (text.length > 200) {
+    return null;
+  }
+  const phrase = unitPhrasePattern.exec(text);
+  if (phrase) {
+    return unitsIn(phrase[0])[0] ?? null;
+  }
+  return unitOnlyPattern.test(text) ? unitsIn(text)[0] ?? null : null;
+};
+
+/** collapses the spaces statements print, no-break and narrow ones among them */
+export const normalizeSpaces = (textArg: string): string => textArg.replace(/\s+/g, ' ').trim();
+
+const dashOnlyPattern = /^[-–—−]{1,3}$/;
+const numberPattern = /^([-–—−])?\s*(\d{1,3}(?:[. ]\d{3})+|\d+)(?:,(\d{1,6}))?$/;
+
+/**
+ * Reads an amount as German statements print it: `1.234.567,89`, `-1 234`, `– 12,5`, a dash alone
+ * for zero, with or without a unit before or after it (`EUR 1.234,56`, `1.234 T€`). Returns null for
+ * anything else, a year or a note number among them for the caller to tell apart.
+ */
+export const parsePrintedAmount = (textArg: string): IPrintedAmount | null => {
+  let text = normalizeSpaces(textArg);
+  if (text === '') {
+    return null;
+  }
+  let unit: IStatementUnit | null = null;
+  const leading = new RegExp(String.raw`^(?:${unitAlternation})\s*`).exec(text);
+  if (leading) {
+    unit = unitsIn(leading[0])[0];
+    text = text.slice(leading[0].length);
+  } else {
+    const trailing = new RegExp(String.raw`\s*(?:${unitAlternation})$`).exec(text);
+    if (trailing && trailing.index > 0) {
+      unit = unitsIn(trailing[0])[0];
+      text = text.slice(0, trailing.index);
+    }
+  }
+  if (dashOnlyPattern.test(text)) {
+    return { digits: 0n, decimals: 0, unit };
+  }
+  const match = numberPattern.exec(text);
+  if (!match) {
+    return null;
+  }
+  const decimals = match[3]?.length ?? 0;
+  const magnitude = BigInt(match[2].replace(/[. ]/g, '') + (match[3] ?? ''));
+  return { digits: match[1] ? -magnitude : magnitude, decimals, unit };
+};
+
+/** whether a text reads as an amount rather than as a year such as `2024` or `2024 EUR` */
+export const readsAsAmount = (textArg: string): boolean =>
+  parsePrintedAmount(textArg) !== null && !/^(?:19|20)\d{2}$/.test(normalizeSpaces(withoutUnits(textArg)));
+
+/** an amount in a unit: `1.234` in TEUR is 1,234,000 euros, rounded to the thousand */
+export const toAmount = (printedArg: IPrintedAmount, unitArg: IStatementUnit): IAmount => {
+  const step = BigInt(unitArg.factor) * 10n ** BigInt(6 - printedArg.decimals);
+  return {
+    micros: printedArg.digits * step,
+    slack: step <= exactStep ? 0n : step,
+    fractionDigits: fractionDigitsOf(step),
+  };
+};
+
+const fractionDigitsOf = (stepArg: bigint): number => {
+  let digits = 6;
+  for (let step = stepArg; digits > 0 && step % 10n === 0n; step /= 10n) {
+    digits--;
+  }
+  return digits;
+};
+
+export const zeroAmount: IAmount = { micros: 0n, slack: 0n, fractionDigits: 0 };
+
+export const addAmounts = (leftArg: IAmount, rightArg: IAmount): IAmount => ({
+  micros: leftArg.micros + rightArg.micros,
+  slack: leftArg.slack + rightArg.slack,
+  fractionDigits: Math.max(leftArg.fractionDigits, rightArg.fractionDigits),
+});
+
+export const negateAmount = (amountArg: IAmount): IAmount => ({ ...amountArg, micros: -amountArg.micros });
+
+export const sumAmounts = (amountsArg: IAmount[]): IAmount => amountsArg.reduce(addAmounts, zeroAmount);
+
+/**
+ * Whether two amounts can be the same figure: equal, or for figures printed rounded, no further
+ * apart than both their roundings together allow.
+ */
+export const amountsAgree = (leftArg: IAmount, rightArg: IAmount): boolean => {
+  const difference = leftArg.micros - rightArg.micros;
+  return (difference < 0n ? -difference : difference) * 2n <= leftArg.slack + rightArg.slack;
+};
+
+/** an amount as a decimal string in euros, written with its own digits: `1234000`, `-12.50` */
+export const formatAmount = (amountArg: IAmount): string => {
+  const negative = amountArg.micros < 0n;
+  const magnitude = negative ? -amountArg.micros : amountArg.micros;
+  const whole = (magnitude / microsPerEuro).toString();
+  const fraction = (magnitude % microsPerEuro).toString().padStart(6, '0').slice(0, amountArg.fractionDigits);
+  return `${negative ? '-' : ''}${whole}${fraction === '' ? '' : `.${fraction}`}`;
+};

package/ts/financialstatements/classes.financialstatementerror.ts

@@ -0,0 +1,35 @@
+/**
+ * Why a document was not read:
+ * - `invalid_input`: arguments this entry point does not take: no bytes, a date that is not one, a
+ *   statement from the Unternehmensregister without the day it was posted;
+ * - `unsupported_media_type`: a media type other than HTML, PDF, XHTML or a ZIP package;
+ * - `too_large`: a document, or the report in a package, larger than `maxStatementBytes`, a package
+ *   with more than `maxEsefPackageEntries` entries, a PDF with more than `maxPdfPages` pages, or a
+ *   report with more than `maxEsefFacts` facts;
+ * - `invalid_package`: a package that is not a readable ZIP, is encrypted, or does not hold exactly
+ *   one report under `reports/`;
+ * - `unreadable`: a document that does not open as what its media type says: a damaged or
+ *   password-protected PDF, HTML in an unknown encoding, XHTML that is not well-formed;
+ * - `no_text`: a PDF without a text layer, such as a scan;
+ * - `unparseable`: a readable document in which no statement was found with certainty: no balance
+ *   sheet, columns that do not say their year or unit, or current-year figures that do not add up.
+ */
+export type TFinancialStatementErrorCode =
+  | 'invalid_input'
+  | 'unsupported_media_type'
+  | 'too_large'
+  | 'invalid_package'
+  | 'unreadable'
+  | 'no_text'
+  | 'unparseable';
+
+/** The typed error of `@fin.cx/opendata/financialstatements`. */
+export class FinancialStatementError extends Error {
+  public readonly code: TFinancialStatementErrorCode;
+
+  constructor(code: TFinancialStatementErrorCode, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'FinancialStatementError';
+    this.code = code;
+  }
+}