/** * Belegfeld 1 and 2 as DATEV takes them, and the Beleginfo that keeps what a * mapped value stood for (SKR-BF1). * * The DATEV format description (developer.datev.de, "Buchungsstapel", read * 2026-09-30) gives fields 11 and 12 as `^(["][\w$&%*+\-\/]{0,36}["])$`: * "Sonderzeichen: $ & % * + - / Andere Zeichen sind unzulässig (insbesondere * Leerzeichen, Umlaute, Punkt, Komma, Semikolon und Doppelpunkt)". Belegfeld 1 * is the key DATEV clears an open item by: a payment clears the invoice only * where it repeats its Belegfeld 1. Fields 21 to 36 are eight Beleginfo pairs, * "Art" of at most 20 characters and "Inhalt" of at most 210; "Eine Beleginfo * besteht immer aus den Bestandteilen Beleginfo-Art und Beleginfo-Inhalt", * so both parts are given. */ import * as plugins from './core.plugins.js'; /** * The longest Belegfeld 1 and 2 (Buchungsstapel fields 11 and 12). On the * length of Belegfeld 2 the German page gives 36 and the English page 12 * (read 2026-09-25); 36 is kept. */ export const DATEV_MAX_BELEGFELD = 36; /** The longest Beleginfo-Art (fields 21, 23 … 35). */ export const DATEV_MAX_BELEGINFO_ART = 20; /** The longest Beleginfo-Inhalt (fields 22, 24 … 36). */ export const DATEV_MAX_BELEGINFO_INHALT = 210; /** How many Beleginfo pairs a row has (fields 21 to 36). */ export const DATEV_MAX_BELEGINFO_PAIRS = 8; /** * The characters of a Belegfeld: ASCII letters, digits and `$ & % * + - /`. * The expression's `\w` would also take `_`, which the list of characters does * not name, so the narrower of the two holds. */ const BELEGFELD = /^[A-Za-z0-9$&%*+\-/]+$/u; const OUTSIDE_BELEGFELD = /[^A-Za-z0-9$&%*+\-/]/gu; /** How many base-36 characters of the original text's SHA-256 a mapped value carries. */ const HASH_LENGTH = 6; const TRANSLITERATION: Readonly> = { ä: 'ae', ö: 'oe', ü: 'ue', Ä: 'Ae', Ö: 'Oe', Ü: 'Ue', ß: 'ss' }; /** One Beleginfo pair of a Buchungsstapel row (fields 21 to 36): what the information is, and the information. */ export interface IDatevBelegInfo { art: string; inhalt: string; } /** Whether a value is a Belegfeld 1 or 2 DATEV takes: 1 to 36 of ASCII letters, digits and `$ & % * + - /`. */ export function isDatevBelegfeld(value: unknown): boolean { return typeof value === 'string' && value.length >= 1 && value.length <= DATEV_MAX_BELEGFELD && BELEGFELD.test(value); } /** Why a Beleginfo is not one DATEV takes, or `undefined` where it is: 1 to 8 pairs, each of both parts within their lengths. */ export function datevBelegInfoFault(belegInfo: unknown): string | undefined { if (!Array.isArray(belegInfo) || belegInfo.length < 1 || belegInfo.length > DATEV_MAX_BELEGINFO_PAIRS) { return `a Beleginfo is 1 to ${DATEV_MAX_BELEGINFO_PAIRS} pairs of Art and Inhalt`; } for (const [index, pair] of belegInfo.entries()) { const { art, inhalt } = (pair ?? {}) as Partial; if (typeof art !== 'string' || art.length < 1 || art.length > DATEV_MAX_BELEGINFO_ART) { return `Beleginfo ${index + 1}: its Art is 1 to ${DATEV_MAX_BELEGINFO_ART} characters`; } if (typeof inhalt !== 'string' || inhalt.length < 1 || inhalt.length > DATEV_MAX_BELEGINFO_INHALT) { return `Beleginfo ${index + 1}: its Inhalt is 1 to ${DATEV_MAX_BELEGINFO_INHALT} characters`; } } return undefined; } /** * `HASH_LENGTH` base-36 characters of the SHA-256 of a text: the low-order * digits of its first 64 bits (`% 36 ** 6`), each as likely as any other, so * the six carry their full 31 bits. */ function hashOf(text: string): string { return (BigInt(`0x${plugins.sha256FromStringSync(text).slice(0, 16)}`) % 36n ** BigInt(HASH_LENGTH)).toString(36).padStart(HASH_LENGTH, '0'); } /** * The Belegfeld 1 or 2 DATEV takes for a text, one deterministic mapping for * an invoice, its payments, its corrections, a set-off, the carry-forward and * the opening alike, so they share the open item's key. A value DATEV takes is * its own Belegfeld, unchanged. Any other text: the umlauts and ß * transliterated (ä → ae, ß → ss), every other character DATEV does not take * a `-`, runs of `-` one, none at either end; then, since that lost what the * text was (a space, a dot, a cut at 36), `-` and six base-36 characters of * the SHA-256 of the original text, the whole within 36 characters: `RE 1` * gives `RE-1-` and its hash, never `RE-1`, so two texts that map alike stay * apart. `undefined` for a text of nothing but white space. */ export function datevBelegfeldOf(text: string): string | undefined { if (isDatevBelegfeld(text)) { return text; } if (text.trim() === '') { return undefined; } const mapped = [...text] .map((character) => TRANSLITERATION[character] ?? character) .join('') .replace(OUTSIDE_BELEGFELD, '-') .replace(/-+/gu, '-') .replace(/^-|-$/gu, ''); const hash = hashOf(text); const kept = mapped.slice(0, DATEV_MAX_BELEGFELD - HASH_LENGTH - 1).replace(/-$/u, ''); return kept === '' ? hash : `${kept}-${hash}`; } /** * A text's Belegfeld (`datevBelegfeldOf`) with, where the mapping changed it, * the original text as a Beleginfo pair (`art`, by default * "Rechnungsnummer"), its Inhalt cut at 210 characters: what DATEV shows of * the Beleg beside the key. `undefined` for a text of nothing but white space. */ export function datevBelegfeldWithInfoOf( text: string, art = 'Rechnungsnummer', ): { belegfeld: string; belegInfo?: IDatevBelegInfo[] } | undefined { const belegfeld = datevBelegfeldOf(text); if (belegfeld === undefined) { return undefined; } if (belegfeld === text) { return { belegfeld }; } return { belegfeld, belegInfo: [{ art: art.slice(0, DATEV_MAX_BELEGINFO_ART), inhalt: text.slice(0, DATEV_MAX_BELEGINFO_INHALT) }] }; } /** What a caller states of a Buchungsstapel row's Belegfelder: Belegfeld 1 and 2, and its own Beleginfo, if any. */ export interface IDatevBelegfelder { belegfeld1?: string; belegfeld2?: string; belegInfo?: IDatevBelegInfo[]; } /** * The Belegfelder a Buchungsstapel row is written with (SKR-BF1): Belegfeld * 1 and 2 as DATEV takes them (`datevBelegfeldOf`; a text of nothing but white * space is none), and, where that changed a text, the original as a Beleginfo * pair ("Rechnungsnummer" for Belegfeld 1, "Belegfeld 2" for Belegfeld 2, * the Inhalt cut at 210 characters), unless the caller gave a Beleginfo of its * own. `mapped` names the fields the mapping changed. Deterministic: an * invoice and its payment that state one text get one Belegfeld 1. */ export function datevBelegfelderOf(fields: IDatevBelegfelder): IDatevBelegfelder & { mapped: Array<'belegfeld1' | 'belegfeld2'> } { const result: IDatevBelegfelder & { mapped: Array<'belegfeld1' | 'belegfeld2'> } = { mapped: [] }; const pairs: IDatevBelegInfo[] = []; for (const [field, art] of [['belegfeld1', 'Rechnungsnummer'], ['belegfeld2', 'Belegfeld 2']] as const) { const value = fields[field]; if (value === undefined || value === '' || isDatevBelegfeld(value)) { if (value !== undefined) result[field] = value; continue; } result.mapped.push(field); const mapped = datevBelegfeldOf(value); if (mapped === undefined) continue; result[field] = mapped; pairs.push({ art, inhalt: value.slice(0, DATEV_MAX_BELEGINFO_INHALT) }); } const belegInfo = fields.belegInfo ?? (pairs.length > 0 ? pairs : undefined); if (belegInfo !== undefined) result.belegInfo = belegInfo; return result; }