@fin.cx/compatibility 5.0.1 → 5.1.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@fin.cx/compatibility",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "private": false,
-  "description": "Exchange formats of third-party accounting systems: the EXTF Buchungsstapel in Windows-1252 on the rows of @fin.cx/skr, and the document-image archive (document.xml and ZIP)",
+  "description": "Exchange formats of third-party accounting systems: the EXTF Buchungsstapel in Windows-1252 on the rows of @fin.cx/skr, the document-image archive (document.xml and ZIP), and a payroll program's Buchungsliste read into journal drafts",
   "main": "dist_ts/index.js",
   "typings": "dist_ts/index.d.ts",
   "type": "module",
@@ -19,6 +19,10 @@
       "types": "./dist_ts/belegbilder/index.d.ts",
       "default": "./dist_ts/belegbilder/index.js"
     },
+    "./buchungsliste": {
+      "types": "./dist_ts/buchungsliste/index.d.ts",
+      "default": "./dist_ts/buchungsliste/index.js"
+    },
     "./package.json": "./package.json"
   },
   "repository": {
@@ -29,6 +33,7 @@
     "extf",
     "buchungsstapel",
     "belegbilder",
+    "buchungsliste",
     "windows-1252",
     "accounting",
     "export",
@@ -45,11 +50,11 @@
     "@push.rocks/smartarchive": "^5.4.1"
   },
   "devDependencies": {
-    "@fin.cx/skr": "^7.3.0",
-    "@git.zone/tsbuild": "^5.0.0",
+    "@fin.cx/skr": "^8.0.0",
+    "@git.zone/tsbuild": "^5.1.2",
     "@git.zone/tsrun": "^3.0.2",
-    "@git.zone/tstest": "^6.3.2",
-    "@types/node": "^26.6.2"
+    "@git.zone/tstest": "^7.2.0",
+    "@types/node": "^26.6.3"
   },
   "files": [
     "ts/**/*",
@@ -58,7 +63,7 @@
     "license.md"
   ],
   "peerDependencies": {
-    "@fin.cx/skr": "^7.0.1"
+    "@fin.cx/skr": "^7.0.1 || ^8.0.0"
   },
   "scripts": {
     "test": "(tstest test/ --verbose)",

package/readme.md

@@ -1,9 +1,10 @@
 # @fin.cx/compatibility
 
-Exchange formats of third-party accounting systems: the files a German tax advisor's system imports. The package's name carries no vendor's name; the formats and files keep the names the importing system expects (EXTF, `DATEV_Belege_<label>.zip`, the Datev field names in `@fin.cx/skr`'s rows). Two formats, each on its own entry point:
+Exchange formats of third-party accounting systems: the files a German tax advisor's system imports. The package's name carries no vendor's name; the formats and files keep the names the importing system expects (EXTF, `DATEV_Belege_<label>.zip`, the Datev field names in `@fin.cx/skr`'s rows, the Buchungsliste). Three formats, each on its own entry point:
 
 - `@fin.cx/compatibility/extf`: the **EXTF Buchungsstapel**. The rows and the text come from `@fin.cx/skr` (`journalDraftsToDatevRows`, `writeExtfBuchungsstapel`); this module checks the drafts, writes the file in Windows-1252 and says which characters the encoding could not hold.
 - `@fin.cx/compatibility/belegbilder`: the **document-image archive**, a DATEV Document-Package: `document.xml` after DATEV's `Document_v060.xsd` plus one `<GUID>.<extension>` per document (a PDF or a picture), as one ZIP, linked to the bookings through the GUID in their Beleglink (field 20, `BEDI "GUID"`).
+- `@fin.cx/compatibility/buchungsliste`: the **Buchungsliste** a payroll program exports for a bookkeeping system's ASCII import (Lexware lohn+gehalt's), read into `@fin.cx/skr` journal drafts, one per row, as skr reads a Buchungsstapel.
 
 It reads no clock, keeps no state and writes nothing anywhere: files go back to the caller as bytes.
 
@@ -17,7 +18,7 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
 pnpm install @fin.cx/compatibility @fin.cx/skr
 ```
 
-`@fin.cx/skr` (^7.0.1) is a peer dependency: the drafts and the account policy the EXTF writer takes are built by your copy of skr, and the writer turns them into rows with the same copy, so the rows follow the chart the drafts were booked on (which accounts are Automatikkonten, which carry VAT). A second copy of skr of another major would write rows by another chart; a package manager that finds your skr outside the range says so as an unmet peer.
+`@fin.cx/skr` (^7.0.1 || ^8.0.0) is a peer dependency: the drafts and the account policy the EXTF writer takes are built by your copy of skr, and the writer turns them into rows with the same copy, so the rows follow the chart the drafts were booked on (which accounts are Automatikkonten, which carry VAT). The Buchungsliste is booked into drafts by your copy as well. A second copy of skr of another major would write rows by another chart; a package manager that finds your skr outside the range says so as an unmet peer.
 
 ## Usage
 
@@ -82,12 +83,59 @@ The archive is what DATEV's XML-Schnittstelle online takes as a Document-Package
 - Characters XML 1.0 does not allow (C0 controls other than tab, line feed and carriage return, a surrogate not in a pair, U+FFFE, U+FFFF) are left out of a description and of `generatingSystem` before they are cut.
 - Refused with `CompatibilityError` `invalid_documents`: no document, more than 4999 (the schema's bound), a GUID of another form, a format outside `BELEGBILD_FORMATS`, one GUID for two different files (another format, or other bytes).
 
+## Buchungsliste
+
+The Buchungsliste is the text file a payroll program exports for the ASCII import of a bookkeeping system: Lexware lohn+gehalt writes it under 'Berichte - Buchungsliste' with the target 'Export - Datei', and Lexware buchhaltung reads it under 'Datei - Import - Text/ASCII' (Buchungsdaten). This module reads it into journal drafts, one per row, as `@fin.cx/skr` `importExtfBuchungsstapel` reads a Buchungsstapel: each row becomes a Buchungsstapel row, skr's `journalDraftOfDatevRow` books it (its tax unfolded onto the policy's tax accounts by its Steuerschlüssel or by the automatism of its account), and `validateJournalDraft` checks it against the policy.
+
+```typescript
+import * as skrCore from '@fin.cx/skr/core';
+import { buchungsliste } from '@fin.cx/compatibility';
+// or: import * as buchungsliste from '@fin.cx/compatibility/buchungsliste';
+
+const { entries, warnings } = buchungsliste.importBuchungsliste(bytes, skrCore.SKR03_DEFAULT_POLICY);
+entries[0].draft; // skrCore.IJournalDraft, dated by the row's Belegdatum
+entries[0].datevRow; // the Buchungsstapel row it was booked from (buchungslisteRowToDatevRow)
+entries[0].buchungslisteRow; // the row as the file states it: { row, line, belegDatum, betragCents, sollkonto, … }
+warnings; // ['column 9 "Lohnart" is no field of a Buchungsliste this reader knows; its values are not read']
+
+const { rows } = buchungsliste.readBuchungsliste(bytes); // the rows alone, without booking them
+```
+
+What the sources say (Lexware FAQ 000013133 "Export Buchungsdaten aus Lexware lohn+gehalt in Lexware buchhaltung", printed 2023-11-08; "Lexware buchhaltung pro/premium, Schnittstellenbeschreibung ASCII/ANSI-Schnittstelle", section 2 "Buchungsdaten"):
+
+- The import reads the file as ANSI (Windows-1252) with "Erster Datensatz enthält Feldnamen": the first line names the fields. The bytes are decoded with `decodeWindows1252`.
+- The fields and their formats: Belegdatum and Buchungsdatum (TT.MM.JJJJ), Buchungsperiode (2 digits), Belegnummernkreis (9 characters), Belegnummer (20), Buchungstext (79), Buchungsbetrag (10 digits before the decimal comma, 2 after: "250,00"), Sollkonto and Habenkonto (9 digits), Steuerschlüssel (2 digits, DATEV's keys), Kostenstelle and Kostenträger (19 characters), Zusatzangaben (2 digits, the § 13b cases), EU Land and EU % (since 2022).
+- The payroll program writes one booking per Lohnart ('lang'; a company pension, a company car and some other cases book a Soll and a Haben of the same amount, which cancel), one per account ('kurz', each with the text 'Lohn & Gehalt Monat'), or the long list per cost centre ('nach Kostenstellen aufgeteilt'), against its Lohn- und Gehalt Verrechnungskonto (SKR 03 1755). The Belegnummer is the Nummernkreis ('LG' unless changed), the year, the month and the Lohnart; the Belegdatum is the last day of the period unless set.
+
+How a row is read:
+
+- **The columns are taken by their names**, in any case, with or without spaces, the umlauts written out or not: Belegdatum, Buchungsdatum, Buchungsperiode, Belegnummernkreis, Belegnummer, Buchungstext, Buchungsbetrag, Währung, Sollkonto, Habenkonto, Steuerschlüssel, Kostenstelle (or "Kostenstelle 1"), Kostenträger (or "Kostenstelle 2"), Zusatzangaben, EU Land, EU %. A column of any other name, or of none, is not read and named in `warnings`.
+- **The booking**: the amount from the Sollkonto (Konto) to the Habenkonto (Gegenkonto), on the Belegdatum. A **negative amount** keeps both accounts in their places and books the other way, as a Buchungsstapel row states it, by its Soll/Haben mark: `H` and the amount without its sign. It is no general reversal (field 118).
+- **The Steuerschlüssel is the BU key** of the row, one of the keys skr knows (`BU_KEY_RULES`: 1, 2, 3, 8, 9, 18, 19, 40, 91, 94). Which account it is on, and what tax it books, is skr's: a key of a tax on an Automatikkonto, for example, is refused by skr's check. The bookkeeping system's table also names keys skr does not know (4, 5, 6, 7, 16, 17, for rates of other periods, such as 5 % and 16 %); a row with one is refused.
+- **Belegfeld 1** is the Belegnummer, led by the Belegnummernkreis where the file states both and the Belegnummer does not already begin with it, joined without a separator; either alone where the file states only one. skr's writer maps a value DATEV does not take when it writes the row (skr 7.3.0 and later).
+- **Cost centres**: the Kostenstelle is KOST1, the Kostenträger KOST2.
+- **Kept, not booked**: the Buchungsdatum and the Buchungsperiode stand on the row (`buchungsDatum`, `buchungsperiode`); a draft is dated by its Belegdatum, as a Buchungsstapel row is.
+- **The chart is your skr's.** skr 8's SKR 03 knows 8611 "Verrechnete sonstige Sachbezüge aus Fahrzeug-Gestellung 19 % USt" as an Automatikkonto at 19 %: a company car's row onto it without a key books the VAT out of the amount. skr 7 knows 8611 as no Automatikkonto, and the same row books no VAT.
+
+Refused with `CompatibilityError` `invalid_buchungsliste`, the message naming the line and the row, and `details` the `line`, the `row`, the `field` (its column's name as the file states it) and its `value`:
+
+- a file that begins with the byte order mark of UTF-8, or has no first line; a first line whose names are separated by none of semicolon, tab and comma;
+- a required column missing (Belegdatum, Buchungsbetrag, Sollkonto, Habenkonto), each named, or two columns of one field;
+- a row of another number of fields than the first line; a quote never closed, or text after a closing quote;
+- a day not TT.MM.JJJJ (or none in the Belegdatum); an amount that is not digits with, if any, a decimal comma and at most 2 decimals, at most 10 digits before it (dots may group the thousands, a minus sign may lead it), or 0; an account not of 1 to 9 digits; a Steuerschlüssel skr does not know; a Buchungsperiode not of 1 or 2 digits; a Währung other than EUR (or empty);
+- a row that states Zusatzangaben, an EU Land or an EU %: this version maps none of them (the § 13b and OSS cases need a decision it does not make);
+- the first row skr cannot book (a tax whose account cannot be told) or whose draft its check refuses (`details.errors`).
+
+**Unconfirmed until a real export of lohn+gehalt has been read.** No such export has been seen. The field names lohn+gehalt writes in the first line (a secondary source names `Belegdatum;Belegnummer;Buchungstext;Buchungsbetrag;Währung;Sollkonto;Habenkonto;Kostenstelle 1`), the delimiter, the quoting and the line ending are not known; hence the reader takes the columns by name and the delimiter from the first line (the first of semicolon, tab and comma outside quotes), takes a field in double quotes with a quote written twice inside, a line break inside quotes, lines ending in CRLF, LF or CR, and skips a line that states nothing. Unconfirmed as well: that "Kostenstelle 2" is the second cost-centre level (KOST2), how the file writes an empty numeric field (a `0` in Zusatzangaben or EU % is refused, as any value there) and a Steuerschlüssel (written with a leading zero, `09`, or as `0`, it is refused), whether the Belegnummer already holds the Nummernkreis, whether a Währung column is written as `EUR`, and whether amounts are ever negative.
+
 ## Windows-1252
 
 `encodeWindows1252(text)` follows the WHATWG Encoding Standard. Bytes 0x00–0x7F and 0xA0–0xFF are the code points of the same number, and 0x80–0x9F carry the 27 characters € ‚ ƒ „ … † ‡ ˆ ‰ Š ‹ Œ Ž ‘ ’ “ ” • – — ˜ ™ š › œ ž Ÿ.
 
 A character outside the encoding becomes one `?` and is listed in `replaced`, so nothing is lost unreported. This includes C1 controls, U+FFFD, and anything outside the Basic Latin and Latin-1 ranges other than those 27.
 
+`decodeWindows1252(bytes)` reads the same table back, every other byte (the five the standard leaves to C1 controls included) as the code point of its own number; it does not rest on the platform's decoder.
+
 Compared with `iconv-lite` 0.7.3 over every code point of the Basic Multilingual Plane, the output is the same except in two cases:
 
 - U+FFFD: iconv-lite writes byte 0x9D, a C1 control; this module writes `?`.
@@ -95,6 +143,7 @@ Compared with `iconv-lite` 0.7.3 over every code point of the Basic Multilingual
 
 ## Open
 
+- **The Buchungsliste as lohn+gehalt writes it**: its field names, delimiter, quoting and line ending are unconfirmed until a real export has been read (see Buchungsliste).
 - **The `document.xml` layout** (`<archive><content><document guid>…`, no namespace) is the one this module took over from its first user. No primary description of the importing system's schema was available when it was written. The layout should be confirmed by one import at a tax advisor before it is relied on.
 
 ## License and Legal Information

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/compatibility',
-  version: '5.0.1',
-  description: 'Exchange formats of third-party accounting systems: the EXTF Buchungsstapel in Windows-1252 on the rows of @fin.cx/skr, and the document-image archive (document.xml and ZIP)'
+  version: '5.1.0',
+  description: 'Exchange formats of third-party accounting systems: the EXTF Buchungsstapel in Windows-1252 on the rows of @fin.cx/skr, the document-image archive (document.xml and ZIP), and a payroll program\'s Buchungsliste read into journal drafts'
 }

package/ts/buchungsliste/index.ts

@@ -0,0 +1,499 @@
+import * as plugins from './plugins.js';
+import { CompatibilityError, type ICompatibilityErrorDetails } from '../error.js';
+import { decodeWindows1252 } from '../encoding/index.js';
+
+export { CompatibilityError, type TCompatibilityErrorCode, type ICompatibilityErrorDetails } from '../error.js';
+
+export type IDatevBuchungsstapelRow = plugins.skrCore.IDatevBuchungsstapelRow;
+
+/*
+ * The Buchungsliste is the text file a payroll program exports for the ASCII import of a bookkeeping system (Lexware
+ * lohn+gehalt: 'Berichte - Buchungsliste', target 'Export - Datei'; read by Lexware buchhaltung's 'Datei - Import -
+ * Text/ASCII', Buchungsdaten). Sources: Lexware FAQ 000013133 "Export Buchungsdaten aus Lexware lohn+gehalt in Lexware
+ * buchhaltung" (printed 2023-11-08) and "Lexware buchhaltung pro/premium, Schnittstellenbeschreibung ASCII/ANSI-
+ * Schnittstelle", section 2 "Buchungsdaten".
+ * - The import reads the file as ANSI (Windows-1252) with "Erster Datensatz enthält Feldnamen": the first line names
+ *   the fields.
+ * - Its fields: Belegdatum and Buchungsdatum (TT.MM.JJJJ), Buchungsperiode (2 digits), Belegnummernkreis (9
+ *   characters), Belegnummer (20), Buchungstext (79), Buchungsbetrag (10 digits before the decimal comma, 2 after:
+ *   "250,00"), Sollkonto and Habenkonto (9 digits), Steuerschlüssel (2 digits, DATEV's keys), Kostenstelle and
+ *   Kostenträger (19 characters), Zusatzangaben (2 digits, the § 13b cases), EU Land (2 characters) and EU % (2 + 2
+ *   digits), the last two since the 2022 version.
+ * - The payroll program writes one booking per Lohnart ('lang'; some cases, a company pension or a company car, book a
+ *   Soll and a Haben of the same amount that cancel), one per account ('kurz', text 'Lohn & Gehalt Monat') or the long
+ *   list per cost centre, against its Lohn- und Gehalt Verrechnungskonto; the Belegnummer is the Nummernkreis ('LG'
+ *   by default), the year, the month and the Lohnart.
+ *
+ * Unconfirmed until a real export of lohn+gehalt has been read: the field names it writes in the first line (one
+ * secondary source names "Belegdatum;Belegnummer;Buchungstext;Buchungsbetrag;Währung;Sollkonto;Habenkonto;Kostenstelle
+ * 1"), the delimiter, the quoting and the line ending. The reader therefore takes its columns from the first line,
+ * by name, and the delimiter from it as well; what follows from that is marked "unconfirmed" below.
+ */
+
+/** The fields of a Buchungsliste this reader knows, by the bookkeeping import's names. */
+type TBuchungslisteField =
+  | 'belegdatum'
+  | 'buchungsdatum'
+  | 'buchungsperiode'
+  | 'belegnummernkreis'
+  | 'belegnummer'
+  | 'buchungstext'
+  | 'buchungsbetrag'
+  | 'waehrung'
+  | 'sollkonto'
+  | 'habenkonto'
+  | 'steuerschluessel'
+  | 'kostenstelle'
+  | 'kostentraeger'
+  | 'zusatzangaben'
+  | 'euLand'
+  | 'euProzent';
+
+/** How a field is named in a refusal when the file names no column of it. */
+const FIELD_NAMES: Readonly<Record<TBuchungslisteField, string>> = {
+  belegdatum: 'Belegdatum',
+  buchungsdatum: 'Buchungsdatum',
+  buchungsperiode: 'Buchungsperiode',
+  belegnummernkreis: 'Belegnummernkreis',
+  belegnummer: 'Belegnummer',
+  buchungstext: 'Buchungstext',
+  buchungsbetrag: 'Buchungsbetrag',
+  waehrung: 'Währung',
+  sollkonto: 'Sollkonto',
+  habenkonto: 'Habenkonto',
+  steuerschluessel: 'Steuerschlüssel',
+  kostenstelle: 'Kostenstelle',
+  kostentraeger: 'Kostenträger',
+  zusatzangaben: 'Zusatzangaben',
+  euLand: 'EU Land',
+  euProzent: 'EU %',
+};
+
+/**
+ * The field of each column name, as `columnKeyOf` reads it. The names are the import's (section 2 of its
+ * description), and "Währung", "Kostenstelle 1" and "Kostenstelle 2" a payroll program may write instead (unconfirmed):
+ * the second cost-centre level is DATEV's KOST2, as the Kostenträger is.
+ */
+const FIELD_OF_COLUMN: ReadonlyMap<string, TBuchungslisteField> = new Map<string, TBuchungslisteField>([
+  ['belegdatum', 'belegdatum'],
+  ['buchungsdatum', 'buchungsdatum'],
+  ['buchungsperiode', 'buchungsperiode'],
+  ['belegnummernkreis', 'belegnummernkreis'],
+  ['belegnummer', 'belegnummer'],
+  ['buchungstext', 'buchungstext'],
+  ['buchungsbetrag', 'buchungsbetrag'],
+  ['waehrung', 'waehrung'],
+  ['sollkonto', 'sollkonto'],
+  ['habenkonto', 'habenkonto'],
+  ['steuerschluessel', 'steuerschluessel'],
+  ['kostenstelle', 'kostenstelle'],
+  ['kostenstelle1', 'kostenstelle'],
+  ['kostentraeger', 'kostentraeger'],
+  ['kostenstelle2', 'kostentraeger'],
+  ['zusatzangaben', 'zusatzangaben'],
+  ['euland', 'euLand'],
+  ['eu%', 'euProzent'],
+]);
+
+/** The fields a row cannot be booked without. */
+const REQUIRED_FIELDS: readonly TBuchungslisteField[] = ['belegdatum', 'buchungsbetrag', 'sollkonto', 'habenkonto'];
+
+/** The fields this version reads but does not map (§ 13b and the OSS cases need a decision it does not make): a row that states one is refused. */
+const UNMAPPED_FIELDS: readonly TBuchungslisteField[] = ['zusatzangaben', 'euLand', 'euProzent'];
+
+/** The delimiters a Buchungsliste may separate its fields by (unconfirmed), in the order the first line is tried for them. */
+const DELIMITERS: readonly string[] = [';', '\t', ','];
+
+/**
+ * A column name as it is compared: in lower case, the umlauts and ß written out (ae, oe, ue, ss), without spaces and
+ * other punctuation but `%`. "Kostenträger", "KOSTENTRAEGER" and "Kosten träger" are one name.
+ */
+const columnKeyOf = (nameArg: string): string =>
+  nameArg
+    .toLowerCase()
+    .replace(/ä/gu, 'ae')
+    .replace(/ö/gu, 'oe')
+    .replace(/ü/gu, 'ue')
+    .replace(/ß/gu, 'ss')
+    .replace(/[^a-z0-9%]/gu, '');
+
+/** One row of a Buchungsliste as the file states it: one booking of the amount from the Sollkonto to the Habenkonto. */
+export interface IBuchungslisteRow {
+  /** the data row, from 1 */
+  row: number;
+  /** the line of the file it begins on, from 1: the first line names the fields */
+  line: number;
+  /** the Belegdatum, midnight UTC; the draft's day */
+  belegDatum: Date;
+  /** the Buchungsdatum, midnight UTC, where the file states one; kept, not booked (a draft is dated by its Belegdatum) */
+  buchungsDatum?: Date;
+  /** the Buchungsperiode, where the file states one; kept, not booked */
+  buchungsperiode?: number;
+  belegnummernkreis?: string;
+  belegnummer?: string;
+  /** empty where the file states none */
+  buchungstext: string;
+  /** the Buchungsbetrag in cents as the file states it, negative with a minus sign; never 0 */
+  betragCents: number;
+  sollkonto: string;
+  habenkonto: string;
+  /** the Steuerschlüssel, one of DATEV's keys `@fin.cx/skr` knows; empty where the file states none */
+  steuerschluessel: plugins.skrCore.TBuKey;
+  /** DATEV's KOST1 */
+  kostenstelle?: string;
+  /** DATEV's KOST2 */
+  kostentraeger?: string;
+}
+
+export interface IBuchungsliste {
+  /** in the order of the file */
+  rows: IBuchungslisteRow[];
+  /** what was read but not taken, each naming its column: a column of a name this reader does not know, or of none */
+  warnings: string[];
+}
+
+/** One record of the text: its fields and the line it begins on. */
+interface IRecord {
+  line: number;
+  fields: string[];
+}
+
+/** A Buchungsliste that cannot be read as it is. */
+const refusal = (messageArg: string, detailsArg: ICompatibilityErrorDetails): CompatibilityError =>
+  new CompatibilityError('invalid_buchungsliste', messageArg, detailsArg);
+
+/**
+ * The delimiter the first line separates its names by: the first of semicolon, tab and comma that stands in it outside
+ * double quotes (unconfirmed which one lohn+gehalt writes). Refuses a first line that has none: a single name cannot
+ * be the four fields a row needs.
+ */
+const delimiterOf = (firstLineArg: string, lineArg: number): string => {
+  const outside = new Set<string>();
+  let quoted = false;
+  for (const char of firstLineArg) {
+    if (char === '"') {
+      quoted = !quoted;
+    } else if (!quoted) {
+      outside.add(char);
+    }
+  }
+  const delimiter = DELIMITERS.find((delimiterArg) => outside.has(delimiterArg));
+  if (delimiter === undefined) {
+    throw refusal(`line ${lineArg}: the field names of the first line are separated by none of semicolon, tab and comma`, { line: lineArg });
+  }
+  return delimiter;
+};
+
+/**
+ * The records of the text, each with the line it begins on: fields separated by the delimiter, a record ending at
+ * CRLF, LF or CR outside double quotes. A field in double quotes holds the delimiter, a line break and a quote written
+ * twice. A quote left open to the end of the text, or text after a closing quote before the next delimiter, is no
+ * field of such a file: refused, naming the line.
+ */
+const recordsOf = (textArg: string, delimiterArg: string): IRecord[] => {
+  const records: IRecord[] = [];
+  let fields: string[] = [];
+  let current = '';
+  let quoted = false;
+  let closed = false;
+  let line = 1;
+  let recordLine = 1;
+  const endField = (): void => {
+    fields.push(current);
+    current = '';
+    closed = false;
+  };
+  for (let index = 0; index < textArg.length; index += 1) {
+    const char = textArg[index];
+    const lineBreak = char === '\n' || (char === '\r' && textArg[index + 1] !== '\n');
+    if (quoted) {
+      if (char === '"' && textArg[index + 1] === '"') {
+        current += '"';
+        index += 1;
+      } else if (char === '"') {
+        quoted = false;
+        closed = true;
+      } else {
+        current += char;
+        line += lineBreak ? 1 : 0;
+      }
+    } else if (char === delimiterArg) {
+      endField();
+    } else if (char === '\r' || char === '\n') {
+      if (lineBreak) {
+        endField();
+        records.push({ line: recordLine, fields });
+        fields = [];
+        line += 1;
+        recordLine = line;
+      }
+    } else if (closed) {
+      throw refusal(`line ${line}: field ${fields.length + 1} has text after its closing quote`, { line });
+    } else if (char === '"' && current === '') {
+      quoted = true;
+    } else {
+      current += char;
+    }
+  }
+  if (quoted) {
+    throw refusal(`line ${recordLine}: field ${fields.length + 1} opens a quote that is never closed`, { line: recordLine });
+  }
+  // the last record, where the text does not end in a line break
+  if (current !== '' || closed || fields.length > 0) {
+    endField();
+    records.push({ line: recordLine, fields });
+  }
+  return records;
+};
+
+/** Whether a record states nothing: an empty line, or one of empty fields only. */
+const isBlank = (recordArg: IRecord): boolean => recordArg.fields.every((fieldArg) => fieldArg.trim() === '');
+
+/** A day from `TT.MM.JJJJ`, midnight UTC, or undefined. */
+const dayOf = (valueArg: string): Date | undefined => {
+  const match = /^(\d{2})\.(\d{2})\.(\d{4})$/u.exec(valueArg);
+  if (!match) return undefined;
+  const [day, month, year] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day ? date : undefined;
+};
+
+/**
+ * An amount in cents from a decimal comma with at most 2 digits after it, at most 10 digits before it, optionally
+ * grouped by dots in threes and led by a minus sign ("1.234,56", "-250,00", "250"), or undefined.
+ */
+const centsOf = (valueArg: string): number | undefined => {
+  const match = /^(-?)(\d{1,3}(?:\.\d{3})+|\d+)(?:,(\d{1,2}))?$/u.exec(valueArg);
+  if (!match) return undefined;
+  const euros = match[2].replace(/\./gu, '');
+  if (euros.length > 10) return undefined;
+  const cents = Number(euros) * 100 + Number((match[3] ?? '').padEnd(2, '0'));
+  return match[1] === '-' ? -cents : cents;
+};
+
+/**
+ * Reads a Buchungsliste: Windows-1252 bytes, the first line naming the fields, one booking per line after it. The
+ * columns are taken by their names (in any case, with or without spaces, the umlauts written out or not), the
+ * delimiter from the first line (semicolon, tab or comma); a field may stand in double quotes, a quote written twice
+ * inside; lines end in CRLF, LF or CR; a line that states nothing is skipped. A column of a name this reader does not
+ * know is not read and named in `warnings`.
+ *
+ * Refuses with `CompatibilityError` `invalid_buchungsliste`, naming the line, the row and the field: a file in UTF-8
+ * with a byte order mark; no first line; a required column missing (Belegdatum, Buchungsbetrag, Sollkonto,
+ * Habenkonto), or two columns of one field; a row of another number of fields than the first line; a day not
+ * TT.MM.JJJJ; an amount not of the form above, or 0; an account not of 1 to 9 digits; a Steuerschlüssel `@fin.cx/skr`
+ * does not know; a Buchungsperiode not of 1 or 2 digits; a Währung other than EUR; and a row that states Zusatzangaben,
+ * an EU Land or an EU %, which this version does not map.
+ */
+export const readBuchungsliste = (bytesArg: Uint8Array): IBuchungsliste => {
+  if (bytesArg[0] === 0xef && bytesArg[1] === 0xbb && bytesArg[2] === 0xbf) {
+    throw refusal('the Buchungsliste begins with the byte order mark of UTF-8; it is read as Windows-1252 (ANSI)', { line: 1 });
+  }
+  const text = decodeWindows1252(bytesArg);
+  const lines = text.split(/\r\n|\n|\r/u);
+  // the first line that states anything names the fields
+  const firstLineIndex = lines.findIndex((lineArg) => /[^\s;,"]/u.test(lineArg));
+  if (firstLineIndex < 0) {
+    throw refusal('the Buchungsliste has no first line naming its fields', {});
+  }
+  const delimiter = delimiterOf(lines[firstLineIndex], firstLineIndex + 1);
+  const [captionRecord, ...dataRecords] = recordsOf(text, delimiter).filter((recordArg) => !isBlank(recordArg));
+  if (captionRecord === undefined) {
+    throw refusal('the Buchungsliste has no first line naming its fields', {});
+  }
+  const captions = captionRecord.fields.map((fieldArg) => fieldArg.trim());
+
+  // the column of each field the first line names
+  const warnings: string[] = [];
+  const columnOf = new Map<TBuchungslisteField, number>();
+  captions.forEach((captionArg, columnArg) => {
+    const field = FIELD_OF_COLUMN.get(columnKeyOf(captionArg));
+    if (field === undefined) {
+      warnings.push(
+        captionArg === ''
+          ? `column ${columnArg + 1} has no name; its values are not read`
+          : `column ${columnArg + 1} "${captionArg}" is no field of a Buchungsliste this reader knows; its values are not read`,
+      );
+      return;
+    }
+    const earlier = columnOf.get(field);
+    if (earlier !== undefined) {
+      throw refusal(
+        `line ${captionRecord.line}: columns ${earlier + 1} "${captions[earlier]}" and ${columnArg + 1} "${captionArg}" both state the ${FIELD_NAMES[field]}`,
+        { line: captionRecord.line, field: captionArg },
+      );
+    }
+    columnOf.set(field, columnArg);
+  });
+  const missing = REQUIRED_FIELDS.filter((fieldArg) => !columnOf.has(fieldArg));
+  if (missing.length > 0) {
+    throw refusal(`line ${captionRecord.line}: the Buchungsliste has no column ${missing.map((fieldArg) => FIELD_NAMES[fieldArg]).join(', ')}`, {
+      line: captionRecord.line,
+      field: FIELD_NAMES[missing[0]],
+    });
+  }
+  /** the name of a field's column as the file states it */
+  const nameOf = (fieldArg: TBuchungslisteField): string => {
+    const column = columnOf.get(fieldArg);
+    return column === undefined ? FIELD_NAMES[fieldArg] : captions[column];
+  };
+
+  const rows = dataRecords.map((recordArg, indexArg): IBuchungslisteRow => {
+    const row = indexArg + 1;
+    const { line } = recordArg;
+    if (recordArg.fields.length !== captions.length) {
+      throw refusal(`row ${row} (line ${line}) has ${recordArg.fields.length} fields, not the ${captions.length} of the first line`, { row, line });
+    }
+    const at = (fieldArg: TBuchungslisteField): string => {
+      const column = columnOf.get(fieldArg);
+      return column === undefined ? '' : recordArg.fields[column].trim();
+    };
+    const malformed = (fieldArg: TBuchungslisteField, messageArg: string): CompatibilityError =>
+      refusal(`row ${row} (line ${line}): ${messageArg}`, { row, line, field: nameOf(fieldArg), value: at(fieldArg) });
+    const day = (fieldArg: TBuchungslisteField): Date | undefined => {
+      if (at(fieldArg) === '') return undefined;
+      const value = dayOf(at(fieldArg));
+      if (!value) throw malformed(fieldArg, `the ${nameOf(fieldArg)} "${at(fieldArg)}" is no day TT.MM.JJJJ`);
+      return value;
+    };
+    const account = (fieldArg: TBuchungslisteField): string => {
+      if (!/^\d{1,9}$/u.test(at(fieldArg))) throw malformed(fieldArg, `the ${nameOf(fieldArg)} "${at(fieldArg)}" is no account number of 1 to 9 digits`);
+      return at(fieldArg);
+    };
+
+    for (const field of UNMAPPED_FIELDS) {
+      if (at(field) !== '') {
+        throw malformed(field, `the row states ${nameOf(field)} "${at(field)}"; this version maps no Zusatzangaben (§ 13b), EU Land or EU %`);
+      }
+    }
+    const currency = at('waehrung');
+    if (currency !== '' && currency !== 'EUR') {
+      throw malformed('waehrung', `the row is in ${currency}; these books are in euro`);
+    }
+    const belegDatum = day('belegdatum');
+    if (!belegDatum) throw malformed('belegdatum', `the row states no ${nameOf('belegdatum')}`);
+    const buchungsDatum = day('buchungsdatum');
+    const period = at('buchungsperiode');
+    if (period !== '' && !/^\d{1,2}$/u.test(period)) {
+      throw malformed('buchungsperiode', `the ${nameOf('buchungsperiode')} "${period}" is no period of 1 or 2 digits`);
+    }
+    const betragCents = centsOf(at('buchungsbetrag'));
+    if (betragCents === undefined) {
+      throw malformed(
+        'buchungsbetrag',
+        `the ${nameOf('buchungsbetrag')} "${at('buchungsbetrag')}" is no amount of digits with, if any, a decimal comma and at most 2 decimals (at most 10 digits before it)`,
+      );
+    }
+    if (betragCents === 0) throw malformed('buchungsbetrag', `the ${nameOf('buchungsbetrag')} "${at('buchungsbetrag')}" books nothing`);
+    const sollkonto = account('sollkonto');
+    const habenkonto = account('habenkonto');
+    const key = at('steuerschluessel');
+    if (!plugins.skrCore.isKnownBuKey(key)) {
+      throw malformed(
+        'steuerschluessel',
+        `the ${nameOf('steuerschluessel')} "${key}" is no DATEV key these books know (${Object.keys(plugins.skrCore.BU_KEY_RULES).join(', ')})`,
+      );
+    }
+    const texts = {
+      ...(at('belegnummernkreis') !== '' ? { belegnummernkreis: at('belegnummernkreis') } : {}),
+      ...(at('belegnummer') !== '' ? { belegnummer: at('belegnummer') } : {}),
+      ...(at('kostenstelle') !== '' ? { kostenstelle: at('kostenstelle') } : {}),
+      ...(at('kostentraeger') !== '' ? { kostentraeger: at('kostentraeger') } : {}),
+    };
+    return {
+      row,
+      line,
+      belegDatum,
+      ...(buchungsDatum ? { buchungsDatum } : {}),
+      ...(period !== '' ? { buchungsperiode: Number(period) } : {}),
+      buchungstext: at('buchungstext'),
+      betragCents,
+      sollkonto,
+      habenkonto,
+      steuerschluessel: key,
+      ...texts,
+    };
+  });
+  return { rows, warnings };
+};
+
+/**
+ * Belegfeld 1 of a row: its Belegnummer, led by its Belegnummernkreis where the file states both and the Belegnummer
+ * does not already begin with it (the payroll program forms the Belegnummer from the Nummernkreis, the year, the month
+ * and the Lohnart; whether the file states the Nummernkreis inside it as well is unconfirmed), the two joined without
+ * a separator. Either alone where the file states only one.
+ */
+const belegfeld1Of = (rowArg: IBuchungslisteRow): string | undefined => {
+  const { belegnummernkreis, belegnummer } = rowArg;
+  if (belegnummernkreis !== undefined && belegnummer !== undefined) {
+    return belegnummer.startsWith(belegnummernkreis) ? belegnummer : `${belegnummernkreis}${belegnummer}`;
+  }
+  return belegnummer ?? belegnummernkreis;
+};
+
+/**
+ * The Buchungsstapel row of a Buchungsliste row (`@fin.cx/skr` `IDatevBuchungsstapelRow`): the amount on the Sollkonto
+ * as Konto, the Habenkonto as Gegenkonto. A negative amount keeps both accounts in their places and books the other
+ * way, as a Buchungsstapel states it, by its Soll/Haben mark: `H`, the amount without its sign. It is no general
+ * reversal (field 118). The Steuerschlüssel is the BU key; the Kostenstelle KOST1 and the Kostenträger KOST2;
+ * Belegfeld 1 the Belegnummernkreis and Belegnummer (`belegfeld1Of`), as the file states them: skr's writer maps a
+ * value DATEV does not take when it writes the row (skr 7.3.0 and later).
+ */
+export const buchungslisteRowToDatevRow = (rowArg: IBuchungslisteRow): IDatevBuchungsstapelRow => {
+  const belegfeld1 = belegfeld1Of(rowArg);
+  return {
+    umsatzCents: Math.abs(rowArg.betragCents),
+    sollHaben: rowArg.betragCents < 0 ? 'H' : 'S',
+    konto: rowArg.sollkonto,
+    gegenKonto: rowArg.habenkonto,
+    buSchluessel: rowArg.steuerschluessel,
+    belegDatum: rowArg.belegDatum,
+    ...(belegfeld1 !== undefined ? { belegfeld1 } : {}),
+    buchungstext: rowArg.buchungstext,
+    ...(rowArg.kostenstelle !== undefined ? { kost1: rowArg.kostenstelle } : {}),
+    ...(rowArg.kostentraeger !== undefined ? { kost2: rowArg.kostentraeger } : {}),
+  };
+};
+
+/** One row of a Buchungsliste with the Buchungsstapel row and the journal draft it gives. */
+export interface IImportedBuchungslisteRow {
+  /** the data row, from 1 */
+  row: number;
+  buchungslisteRow: IBuchungslisteRow;
+  datevRow: IDatevBuchungsstapelRow;
+  draft: plugins.skrCore.IJournalDraft;
+}
+
+/**
+ * Reads a Buchungsliste and gives each row's journal draft, as `@fin.cx/skr` `importExtfBuchungsstapel` gives a
+ * Buchungsstapel's: each row's Buchungsstapel row (`buchungslisteRowToDatevRow`) booked by skr's
+ * `journalDraftOfDatevRow` (its tax unfolded onto the policy's tax accounts by its key or by the automatism of its
+ * account) and checked against the policy (`validateJournalDraft`). Refuses the first row that cannot be read or
+ * booked with `CompatibilityError` `invalid_buchungsliste`, naming it (`details.row`, `.line`; what the check found in
+ * `details.errors`). What the reading did not take is in `warnings` (`readBuchungsliste`).
+ */
+export const importBuchungsliste = (
+  bytesArg: Uint8Array,
+  policyArg: plugins.skrCore.IAccountPolicy,
+): { entries: IImportedBuchungslisteRow[]; warnings: string[] } => {
+  const { rows, warnings } = readBuchungsliste(bytesArg);
+  const entries = rows.map((buchungslisteRow): IImportedBuchungslisteRow => {
+    const { row, line } = buchungslisteRow;
+    const datevRow = buchungslisteRowToDatevRow(buchungslisteRow);
+    let draft: plugins.skrCore.IJournalDraft;
+    try {
+      draft = plugins.skrCore.journalDraftOfDatevRow(datevRow, policyArg);
+    } catch (error) {
+      if (error instanceof plugins.skrCore.DatevImportError) {
+        throw refusal(`row ${row} (line ${line}): ${error.message}`, { row, line });
+      }
+      throw error;
+    }
+    const validation = plugins.skrCore.validateJournalDraft(draft, policyArg);
+    if (!validation.valid) {
+      throw refusal(`row ${row} (line ${line}) gives no valid entry: ${validation.errors.join('; ')}`, { row, line, errors: validation.errors });
+    }
+    return { row, buchungslisteRow, datevRow, draft };
+  });
+  return { entries, warnings };
+};

package/ts/buchungsliste/plugins.ts

@@ -0,0 +1,3 @@
+import * as skrCore from '@fin.cx/skr/core';
+
+export { skrCore };