@fin.cx/compatibility 5.0.0 → 5.1.0

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 };

package/ts/encoding/index.ts

@@ -57,3 +57,20 @@ export const encodeWindows1252 = (textArg: string): IWindows1252Result => {
   }
   return { bytes: Uint8Array.from(bytes), replaced };
 };
+
+const CODE_POINT_OF_HIGH_BYTE = new Map<number, number>(HIGH_BYTES.map(([codePointArg, byteArg]) => [byteArg, codePointArg]));
+
+/**
+ * Decodes Windows-1252 as the WHATWG Encoding Standard does: the 27 characters
+ * of 0x80–0x9F by the table above, every other byte as the code point of its
+ * own number (the five bytes the standard leaves to C1 controls included).
+ * It does not rest on the platform's decoder: Node 25.2.1 reads 0x96 as
+ * U+0096, not as the dash.
+ */
+export const decodeWindows1252 = (bytesArg: Uint8Array): string => {
+  let text = '';
+  for (const byte of bytesArg) {
+    text += String.fromCharCode(CODE_POINT_OF_HIGH_BYTE.get(byte) ?? byte);
+  }
+  return text;
+};

package/ts/error.ts

@@ -1,5 +1,5 @@
 /**
- * Why an exchange file could not be written:
+ * Why an exchange file could not be written or read:
  * - `invalid_bookings`: a draft the account policy refuses, the message names it; a general reversal among the
  *   bookings handed over to a correction Buchungsstapel (a correction file passed as the state handed over); or a row
  *   or booking a Buchungsstapel does not hold (no day, an amount that is not positive) or whose Belegdatum lies
@@ -10,16 +10,42 @@
  * - `invalid_documents`: a document of a document-image archive DATEV does not take (its GUID, its format), or none;
  * - `nothing_to_correct`: a correction Buchungsstapel whose current bookings are the ones handed over;
  * - `handed_over_cost_centres_unknown`: a correction of a period whose bookings handed over include one whose cost
- *   centres its record does not state (stored before 4.1) and no rows sent were given; the message names it.
+ *   centres its record does not state (stored before 4.1) and no rows sent were given; the message names it;
+ * - `invalid_buchungsliste`: a Buchungsliste that cannot be read or booked as it is: no header line, a required
+ *   column missing, a field that is not of its format, a field this version does not map, or a row that gives no
+ *   valid entry; `details` names the line, the row and the field where it can.
  */
-export type TCompatibilityErrorCode = 'invalid_bookings' | 'invalid_header' | 'export_failed' | 'invalid_documents' | 'nothing_to_correct' | 'handed_over_cost_centres_unknown';
+export type TCompatibilityErrorCode =
+  | 'invalid_bookings'
+  | 'invalid_header'
+  | 'export_failed'
+  | 'invalid_documents'
+  | 'nothing_to_correct'
+  | 'handed_over_cost_centres_unknown'
+  | 'invalid_buchungsliste';
+
+/** Where a refusal of a file read stands, as far as it is known; empty for a file written. */
+export interface ICompatibilityErrorDetails {
+  /** the data row, from 1 */
+  row?: number;
+  /** the line of the file, from 1 */
+  line?: number;
+  /** the field, by the name of its column as the file states it */
+  field?: string;
+  /** the field's value as the file states it */
+  value?: string;
+  /** what the check of the entry found (`@fin.cx/skr` `validateJournalDraft`) */
+  errors?: string[];
+}
 
 export class CompatibilityError extends Error {
   public readonly code: TCompatibilityErrorCode;
+  public readonly details: ICompatibilityErrorDetails;
 
-  constructor(codeArg: TCompatibilityErrorCode, messageArg: string) {
+  constructor(codeArg: TCompatibilityErrorCode, messageArg: string, detailsArg: ICompatibilityErrorDetails = {}) {
     super(messageArg);
     this.name = 'CompatibilityError';
     this.code = codeArg;
+    this.details = detailsArg;
   }
 }

package/ts/extf/index.ts

@@ -164,9 +164,9 @@ const comparableOf = (bookingsArg: readonly IExportBooking[]): IExportBooking[]
  * what a booking says (its day, amount, side, accounts, BU key, Belegfeld 1,
  * cost centres, and whether it is a general reversal) and not on its wording or its document link. The rows are
  * compared as a multiset: a row that stands twice in one and once in the other differs once. Both sides are compared
- * as a file states them (`comparableOf`: a `"` as `'`, Belegfeld 1 cut to 36 characters, a character Windows-1252
- * cannot hold as `?`), so bookings stored of rows before writing and bookings read from a file compare alike. A
- * booking stored before 4.1, which does not record its cost centres, never differs on them (`pairBookings`); compare
+ * as a file states them (`comparableOf`: a `"` in a text field as `'`, Belegfeld 1 as skr's writer writes it, a
+ * character Windows-1252 cannot hold as `?`), so bookings stored of rows before writing and bookings read from a
+ * file compare alike. A booking stored before 4.1, which does not record its cost centres, never differs on them (`pairBookings`); compare
  * `bookingsOfRows` of the rows sent for an answer that counts them. A booking a Buchungsstapel cannot hold (no day,
  * no positive amount) is refused (`invalid_bookings`).
  */
@@ -280,7 +280,8 @@ export interface IBuchungsstapelFile {
   rows: IDatevBuchungsstapelRow[];
   /**
    * The bookings the file states, read back from its bytes (`@fin.cx/skr` `readExtfBuchungsstapel`): a `"` in a
-   * text field as `'`, Belegfeld 1 cut to 36 characters, a character Windows-1252 cannot hold as `?`. What a file
+   * text field as `'`, Belegfeld 1 as skr's writer writes it (cut to 36 characters before skr 7.3.0; since then a value
+   * DATEV does not take mapped, `datevBelegfeldOf`), a character Windows-1252 cannot hold as `?`. What a file
    * read back is compared with, and what a correction's `handedOver` is (4.1 and before: the rows' bookings before
    * writing).
    */
@@ -433,8 +434,9 @@ export const rowsAsWritten = (rowsArg: readonly IDatevBuchungsstapelRow[]): IDat
 /**
  * The bookings of rows as a Buchungsstapel file states them (`rowsAsWritten`): what a file handed over, read back
  * with `readExtfBuchungsstapel`, is compared with. `bookingsOfRows` of the rows before writing keeps what the file
- * does not (a `"` in Belegfeld 1, a Belegfeld 1 longer than its 36 characters, a character Windows-1252 cannot
- * hold), and Belegfeld 1 is compared, so such a booking would differ from the file forever.
+ * does not (a Belegfeld 1 the writer changes: cut to 36 characters before skr 7.3.0, mapped since where DATEV does
+ * not take it; a character Windows-1252 cannot hold), and Belegfeld 1 is compared, so such a booking would differ
+ * from the file forever.
  */
 export const bookingsAsWritten = (rowsArg: readonly IDatevBuchungsstapelRow[]): IExportBooking[] => bookingsOfRows(rowsAsWritten(rowsArg));
 

package/ts/index.ts

@@ -2,3 +2,4 @@ export * from './error.js';
 export * from './encoding/index.js';
 export * as extf from './extf/index.js';
 export * as belegbilder from './belegbilder/index.js';
+export * as buchungsliste from './buchungsliste/index.js';