@fin.cx/skr 1.3.0 → 2.0.0

package/ts/core/core.bukeys.ts

@@ -0,0 +1,146 @@
+/**
+ * DATEV BU-Schlüssel (Steuerschlüssel) — single source of truth.
+ *
+ * Provenance (2026-07-09): cross-checked against multiple independent German
+ * bookkeeping sources. Key semantics that v1 (skr.postingkeys.ts) and the
+ * finance.plus reference implementation got wrong are corrected here:
+ *   - 18/19 are steuerpflichtiger innergemeinschaftlicher Erwerb (§1a UStG)
+ *     at 7%/19% — NOT generic "Vorsteuer ig Lieferungen".
+ *   - 91/94 are Leistungsempfänger schuldet die Steuer (§13b UStG) at 7%/19%.
+ * The official DATEV Steuerschlüssel-Tabelle (Hilfe-Center Dokument 0904313)
+ * is portal-gated; verification against it plus one manual DATEV import per
+ * release candidate is the final gate (see readme.plan.md, M0 Phase 0).
+ */
+import type { TBuKey, TTaxScenario } from './core.types.js';
+
+export interface IBuKeyRule {
+  key: TBuKey;
+  description: string;
+  taxType: 'none' | 'ust' | 'vst' | 'vst_ust' | 'automatik_aufhebung';
+  ratePercent: number | null;
+  scenarios: TTaxScenario[];
+}
+
+export const BU_KEY_RULES: Record<Exclude<TBuKey, ''>, IBuKeyRule> = {
+  '1': {
+    key: '1',
+    description: 'Umsatzsteuerfrei (§4 UStG)',
+    taxType: 'ust',
+    ratePercent: 0,
+    scenarios: ['domestic_tax_free', 'intra_eu_supply', 'export_third_country'],
+  },
+  '2': {
+    key: '2',
+    description: 'Umsatzsteuer 7 %',
+    taxType: 'ust',
+    ratePercent: 7,
+    scenarios: ['domestic_reduced'],
+  },
+  '3': {
+    key: '3',
+    description: 'Umsatzsteuer 19 %',
+    taxType: 'ust',
+    ratePercent: 19,
+    scenarios: ['domestic_standard'],
+  },
+  '8': {
+    key: '8',
+    description: 'Vorsteuer 7 %',
+    taxType: 'vst',
+    ratePercent: 7,
+    scenarios: ['domestic_reduced'],
+  },
+  '9': {
+    key: '9',
+    description: 'Vorsteuer 19 %',
+    taxType: 'vst',
+    ratePercent: 19,
+    scenarios: ['domestic_standard'],
+  },
+  '18': {
+    key: '18',
+    description: 'Steuerpflichtiger innergemeinschaftlicher Erwerb 7 % (§1a UStG)',
+    taxType: 'vst_ust',
+    ratePercent: 7,
+    scenarios: ['intra_eu_acquisition'],
+  },
+  '19': {
+    key: '19',
+    description: 'Steuerpflichtiger innergemeinschaftlicher Erwerb 19 % (§1a UStG)',
+    taxType: 'vst_ust',
+    ratePercent: 19,
+    scenarios: ['intra_eu_acquisition'],
+  },
+  '40': {
+    key: '40',
+    description: 'Aufhebung der Automatik',
+    taxType: 'automatik_aufhebung',
+    ratePercent: null,
+    scenarios: [
+      'domestic_standard',
+      'domestic_reduced',
+      'domestic_tax_free',
+      'intra_eu_supply',
+      'intra_eu_acquisition',
+      'reverse_charge_13b',
+      'export_third_country',
+    ],
+  },
+  '91': {
+    key: '91',
+    description: 'Leistungsempfänger schuldet die Steuer 7 % (§13b UStG)',
+    taxType: 'vst_ust',
+    ratePercent: 7,
+    scenarios: ['reverse_charge_13b'],
+  },
+  '94': {
+    key: '94',
+    description: 'Leistungsempfänger schuldet die Steuer 19 % (§13b UStG)',
+    taxType: 'vst_ust',
+    ratePercent: 19,
+    scenarios: ['reverse_charge_13b'],
+  },
+};
+
+export function isKnownBuKey(value: string): value is TBuKey {
+  return value === '' || Object.prototype.hasOwnProperty.call(BU_KEY_RULES, value);
+}
+
+export function getBuKeyRule(key: TBuKey): IBuKeyRule | null {
+  if (key === '') return null;
+  return BU_KEY_RULES[key];
+}
+
+/**
+ * Suggest the BU key for the expense/revenue line of a booking.
+ *
+ * targetIsAutomatik: Automatikkonten compute tax themselves on DATEV import.
+ * When the entry carries explicit VAT lines, the automatism must be cancelled
+ * with key 40; a plain automatik line without explicit VAT gets no key.
+ */
+export function suggestBuKey(params: {
+  direction: 'inbound' | 'outbound';
+  scenario: TTaxScenario;
+  ratePercent: number;
+  targetIsAutomatik: boolean;
+  hasExplicitVatLines: boolean;
+}): TBuKey {
+  if (params.targetIsAutomatik) {
+    return params.hasExplicitVatLines ? '40' : '';
+  }
+  const reduced = params.ratePercent === 7;
+  switch (params.scenario) {
+    case 'domestic_standard':
+    case 'domestic_reduced':
+      if (params.direction === 'inbound') return reduced ? '8' : '9';
+      return reduced ? '2' : '3';
+    case 'intra_eu_acquisition':
+      return reduced ? '18' : '19';
+    case 'reverse_charge_13b':
+      return params.direction === 'inbound' ? (reduced ? '91' : '94') : '1';
+    case 'domestic_tax_free':
+    case 'intra_eu_supply':
+    case 'export_third_country':
+      return params.direction === 'outbound' ? '1' : '';
+  }
+}

package/ts/core/core.datev.captions.ts

@@ -0,0 +1,133 @@
+/**
+ * DATEV Buchungsstapel (EXTF 700, Formatversion 13) column captions — 125 fields.
+ * Extracted 1:1 from a DATEV-importable reference file; do not edit by hand.
+ * Field 114 (index 113) is Festschreibung. The physical file must be written
+ * as CP1252 with CRLF line endings (IO-layer concern, not core's).
+ */
+export const DATEV_COLUMN_CAPTIONS: string[] = [
+  "Umsatz (ohne Soll/Haben-Kz)",
+  "Soll/Haben-Kennzeichen",
+  "WKZ Umsatz",
+  "Kurs",
+  "Basisumsatz",
+  "WKZ Basisumsatz",
+  "Konto",
+  "Gegenkonto (ohne BU-Schlüssel)",
+  "BU-Schlüssel",
+  "Belegdatum",
+  "Belegfeld 1",
+  "Belegfeld 2",
+  "Skonto",
+  "Buchungstext",
+  "Postensperre",
+  "Diverse Adressnummer",
+  "Geschäftspartnerbank",
+  "Sachverhalt",
+  "Zinssperre",
+  "Beleglink",
+  "Beleginfo – Art 1",
+  "Beleginfo – Inhalt 1",
+  "Beleginfo – Art 2",
+  "Beleginfo – Inhalt 2",
+  "Beleginfo – Art 3",
+  "Beleginfo – Inhalt 3",
+  "Beleginfo – Art 4",
+  "Beleginfo – Inhalt 4",
+  "Beleginfo – Art 5",
+  "Beleginfo – Inhalt 5",
+  "Beleginfo – Art 6",
+  "Beleginfo – Inhalt 6",
+  "Beleginfo – Art 7",
+  "Beleginfo – Inhalt 7",
+  "Beleginfo – Art 8",
+  "Beleginfo – Inhalt 8",
+  "KOST1 – Kostenstelle",
+  "KOST2 – Kostenstelle",
+  "Kost Menge",
+  "EU-Land u. USt-IdNr.",
+  "EU-Steuersatz",
+  "Abw. Versteuerungsart",
+  "Sachverhalt L+L",
+  "Funktionsergänzung L+L",
+  "BU 49 Hauptfunktionstyp",
+  "BU 49 Hauptfunktionsnummer",
+  "BU 49 Funktionsergänzung",
+  "Zusatzinformation – Art 1",
+  "Zusatzinformation – Inhalt 1",
+  "Zusatzinformation – Art 2",
+  "Zusatzinformation – Inhalt 2",
+  "Zusatzinformation – Art 3",
+  "Zusatzinformation – Inhalt 3",
+  "Zusatzinformation – Art 4",
+  "Zusatzinformation – Inhalt 4",
+  "Zusatzinformation – Art 5",
+  "Zusatzinformation – Inhalt 5",
+  "Zusatzinformation – Art 6",
+  "Zusatzinformation – Inhalt 6",
+  "Zusatzinformation – Art 7",
+  "Zusatzinformation – Inhalt 7",
+  "Zusatzinformation – Art 8",
+  "Zusatzinformation – Inhalt 8",
+  "Zusatzinformation – Art 9",
+  "Zusatzinformation – Inhalt 9",
+  "Zusatzinformation – Art 10",
+  "Zusatzinformation – Inhalt 10",
+  "Zusatzinformation – Art 11",
+  "Zusatzinformation – Inhalt 11",
+  "Zusatzinformation – Art 12",
+  "Zusatzinformation – Inhalt 12",
+  "Zusatzinformation – Art 13",
+  "Zusatzinformation – Inhalt 13",
+  "Zusatzinformation – Art 14",
+  "Zusatzinformation – Inhalt 14",
+  "Zusatzinformation – Art 15",
+  "Zusatzinformation – Inhalt 15",
+  "Zusatzinformation – Art 16",
+  "Zusatzinformation – Inhalt 16",
+  "Zusatzinformation – Art 17",
+  "Zusatzinformation – Inhalt 17",
+  "Zusatzinformation – Art 18",
+  "Zusatzinformation – Inhalt 18",
+  "Zusatzinformation – Art 19",
+  "Zusatzinformation – Inhalt 19",
+  "Zusatzinformation – Art 20",
+  "Zusatzinformation – Inhalt 20",
+  "Stück",
+  "Gewicht",
+  "Zahlweise",
+  "Forderungsart",
+  "Veranlagungsjahr",
+  "Zugeordnete Fälligkeit",
+  "Skontotyp",
+  "Auftragsnummer",
+  "Buchungstyp",
+  "USt-Schlüssel (Anzahlungen)",
+  "EU-Mitgliedstaat (Anzahlungen)",
+  "Sachverhalt L+L (Anzahlungen)",
+  "EU-Steuersatz (Anzahlungen)",
+  "Erlöskonto (Anzahlungen)",
+  "Herkunft-Kz",
+  "Leerfeld",
+  "KOST-Datum",
+  "SEPA-Mandatsreferenz",
+  "Skontosperre",
+  "Gesellschaftername",
+  "Beteiligtennummer",
+  "Identifikationsnummer",
+  "Zeichnernummer",
+  "Postensperre bis",
+  "Bezeichnung",
+  "Kennzeichen",
+  "Festschreibung",
+  "Leistungsdatum",
+  "Datum Zuord.",
+  "Fälligkeit",
+  "Generalumkehr",
+  "Steuersatz",
+  "Land",
+  "Abrechnungsreferent",
+  "BVV-Position",
+  "EU-Mitgliedstaat u. UStID (Ursprung)",
+  "EU-Steuersatz (Ursprung)",
+  "Abw. Skontokonto",
+];

package/ts/core/core.datev.ts

@@ -0,0 +1,174 @@
+/**
+ * DATEV Buchungsstapel (EXTF 700, Formatversion 13) row model and writer.
+ *
+ * Layout verified against a DATEV-importable reference file (2026-07-09):
+ * 125 data columns, 31 header fields, decimal-comma amounts, Belegdatum TTMM,
+ * text fields quoted, field 114 = Festschreibung. The writer emits a CSV
+ * STRING with CRLF; persisting it as CP1252 is the IO layer's job.
+ * One manual import into real DATEV per release candidate remains the final
+ * conformance gate (readme.plan.md, M0).
+ */
+import * as plugins from './core.plugins.js';
+import type { IJournalDraft, TBuKey, TCents } from './core.types.js';
+import { DATEV_COLUMN_CAPTIONS } from './core.datev.captions.js';
+import { DATEV_MAX_BELEGFELD, DATEV_MAX_BUCHUNGSTEXT } from './core.validate.js';
+
+const { centsToString } = plugins.calculation;
+
+export const DATEV_COLUMN_COUNT = 125;
+export const DATEV_HEADER_FIELD_COUNT = 31;
+
+export interface IDatevBuchungsstapelRow {
+  umsatzCents: TCents;
+  sollHaben: 'S' | 'H';
+  konto: string;
+  gegenKonto: string;
+  buSchluessel: TBuKey;
+  belegDatum: Date;
+  belegfeld1?: string;
+  belegfeld2?: string;
+  buchungstext: string;
+  belegLink?: string;
+  kost1?: string;
+  kost2?: string;
+  festschreibung?: boolean;
+}
+
+export interface IDatevExtfHeaderOptions {
+  /** deterministic input — core never reads the clock */
+  createdAt: Date;
+  consultantNumber: number;
+  clientNumber: number;
+  fiscalYearStart: Date;
+  dateFrom: Date;
+  dateTo: Date;
+  label: string;
+  festschreibung: boolean;
+  accountLength?: number;
+  /** 2-char producer id in the header */
+  origin?: string;
+  exportedBy?: string;
+}
+
+function pad(value: number, width: number): string {
+  return String(value).padStart(width, '0');
+}
+
+function formatYyyymmdd(date: Date): string {
+  return `${date.getUTCFullYear()}${pad(date.getUTCMonth() + 1, 2)}${pad(date.getUTCDate(), 2)}`;
+}
+
+function formatTtmm(date: Date): string {
+  return `${pad(date.getUTCDate(), 2)}${pad(date.getUTCMonth() + 1, 2)}`;
+}
+
+function formatTimestamp(date: Date): string {
+  return (
+    formatYyyymmdd(date) +
+    pad(date.getUTCHours(), 2) +
+    pad(date.getUTCMinutes(), 2) +
+    pad(date.getUTCSeconds(), 2) +
+    pad(date.getUTCMilliseconds(), 3)
+  );
+}
+
+function formatAmount(cents: TCents): string {
+  return centsToString(cents).replace('.', ',').replace('-', '-');
+}
+
+function quote(value: string, maxLength?: number): string {
+  let sanitized = value.replace(/"/g, "'");
+  if (maxLength && sanitized.length > maxLength) {
+    sanitized = sanitized.slice(0, maxLength);
+  }
+  return `"${sanitized}"`;
+}
+
+/**
+ * Flatten journal drafts into DATEV rows — one row per line, with the line's
+ * explicit counterAccount as Gegenkonto (no pair reconstruction).
+ */
+export function journalDraftsToDatevRows(
+  drafts: IJournalDraft[],
+  options?: { festschreibung?: boolean },
+): IDatevBuchungsstapelRow[] {
+  const rows: IDatevBuchungsstapelRow[] = [];
+  for (const draft of drafts) {
+    for (const line of draft.lines) {
+      rows.push({
+        umsatzCents: line.amountCents,
+        sollHaben: line.side === 'debit' ? 'S' : 'H',
+        konto: line.accountNumber,
+        gegenKonto: line.counterAccount,
+        buSchluessel: line.buKey,
+        belegDatum: draft.date,
+        belegfeld1: line.belegfeld1 ?? draft.reference,
+        belegfeld2: line.belegfeld2,
+        buchungstext: line.buchungstext || draft.description,
+        belegLink: line.docLink,
+        kost1: line.costCenter1,
+        kost2: line.costCenter2,
+        festschreibung: options?.festschreibung,
+      });
+    }
+  }
+  return rows;
+}
+
+function rowToFields(row: IDatevBuchungsstapelRow): string[] {
+  const fields = new Array<string>(DATEV_COLUMN_COUNT).fill('');
+  fields[0] = formatAmount(row.umsatzCents); // 1 Umsatz
+  fields[1] = quote(row.sollHaben); // 2 Soll/Haben-Kennzeichen
+  fields[6] = row.konto; // 7 Konto
+  fields[7] = row.gegenKonto; // 8 Gegenkonto
+  if (row.buSchluessel !== '') fields[8] = quote(row.buSchluessel); // 9 BU-Schlüssel
+  fields[9] = formatTtmm(row.belegDatum); // 10 Belegdatum
+  if (row.belegfeld1) fields[10] = quote(row.belegfeld1, DATEV_MAX_BELEGFELD); // 11
+  if (row.belegfeld2) fields[11] = quote(row.belegfeld2, DATEV_MAX_BELEGFELD); // 12
+  fields[13] = quote(row.buchungstext, DATEV_MAX_BUCHUNGSTEXT); // 14 Buchungstext
+  if (row.belegLink) fields[19] = quote(row.belegLink); // 20 Beleglink
+  if (row.kost1) fields[36] = quote(row.kost1); // 37 KOST1
+  if (row.kost2) fields[37] = quote(row.kost2); // 38 KOST2
+  if (row.festschreibung !== undefined) fields[113] = row.festschreibung ? '1' : '0'; // 114
+  return fields;
+}
+
+function buildHeaderLine(header: IDatevExtfHeaderOptions): string {
+  const fields = new Array<string>(DATEV_HEADER_FIELD_COUNT).fill('');
+  fields[0] = '"EXTF"';
+  fields[1] = '700';
+  fields[2] = '21';
+  fields[3] = '"Buchungsstapel"';
+  fields[4] = '13';
+  fields[5] = formatTimestamp(header.createdAt);
+  fields[7] = quote(header.origin ?? 'SK');
+  fields[8] = quote(header.exportedBy ?? 'fin.cx/skr');
+  fields[10] = String(header.consultantNumber);
+  fields[11] = String(header.clientNumber);
+  fields[12] = formatYyyymmdd(header.fiscalYearStart);
+  fields[13] = String(header.accountLength ?? 4);
+  fields[14] = formatYyyymmdd(header.dateFrom);
+  fields[15] = formatYyyymmdd(header.dateTo);
+  fields[16] = quote(header.label, 30);
+  fields[18] = '1'; // Buchungstyp: Finanzbuchführung
+  fields[20] = header.festschreibung ? '1' : '0';
+  fields[21] = '"EUR"';
+  return fields.join(';');
+}
+
+/**
+ * Produce the complete EXTF file content (header, caption row, data rows).
+ */
+export function writeExtfBuchungsstapel(
+  rows: IDatevBuchungsstapelRow[],
+  header: IDatevExtfHeaderOptions,
+): { csv: string; filename: string } {
+  const lines: string[] = [
+    buildHeaderLine(header),
+    DATEV_COLUMN_CAPTIONS.join(';'),
+    ...rows.map((row) => rowToFields(row).join(';')),
+  ];
+  const csv = lines.join('\r\n') + '\r\n';
+  const filename = `EXTF_Buchungsstapel_${formatYyyymmdd(header.dateFrom)}_${formatYyyymmdd(header.dateTo)}.csv`;
+  return { csv, filename };
+}

package/ts/core/core.hash.ts

@@ -0,0 +1,76 @@
+/**
+ * Canonical serialization + SHA-256 chaining for the GoBD audit trail.
+ * Pure functions — the persistence layer decides what goes into the chain;
+ * this module guarantees the representation is stable across releases.
+ */
+import * as plugins from './core.plugins.js';
+
+/**
+ * Deterministic string form of a value: object keys sorted recursively,
+ * Dates as ISO strings, undefined properties omitted, array order preserved.
+ * Non-integer numbers are rejected — monetary values must be integer cents.
+ */
+export function canonicalize(value: unknown): string {
+  return JSON.stringify(sortValue(value));
+}
+
+function sortValue(value: unknown): unknown {
+  if (value === null || value === undefined) return value ?? null;
+  if (value instanceof Date) return value.toISOString();
+  if (Array.isArray(value)) return value.map((entry) => sortValue(entry));
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) throw new Error(`Cannot canonicalize non-finite number ${value}`);
+    if (!Number.isInteger(value)) {
+      throw new Error(
+        `Cannot canonicalize non-integer number ${value} — monetary values must be integer cents`,
+      );
+    }
+    return value;
+  }
+  if (typeof value === 'object') {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+      const entry = (value as Record<string, unknown>)[key];
+      if (entry !== undefined) sorted[key] = sortValue(entry);
+    }
+    return sorted;
+  }
+  return value;
+}
+
+/**
+ * Hash of one chain entry: SHA-256 over predecessor hash + canonical payload.
+ */
+export function entryHash(prevHash: string, payload: unknown): string {
+  return plugins.sha256FromStringSync(`${prevHash}\n${canonicalize(payload)}`);
+}
+
+/**
+ * Chain genesis per ledger scope (one chain per skrType + fiscal year).
+ */
+export function genesisHash(skrType: string, fiscalYear: number): string {
+  return plugins.sha256FromStringSync(`GENESIS:${skrType}:${fiscalYear}`);
+}
+
+/**
+ * Walk a sequence of already-canonicalized entries and verify the chain.
+ * Returns the first mismatch or null when intact.
+ */
+export function verifyChain(
+  entries: Array<{ sequenceNumber: number; prevHash: string; entryHash: string; payload: unknown }>,
+  genesis: string,
+): { index: number; reason: string } | null {
+  let expectedPrev = genesis;
+  for (let index = 0; index < entries.length; index++) {
+    const entry = entries[index];
+    if (entry.prevHash !== expectedPrev) {
+      return { index, reason: `prevHash mismatch at sequence ${entry.sequenceNumber}` };
+    }
+    const recomputed = entryHash(entry.prevHash, entry.payload);
+    if (recomputed !== entry.entryHash) {
+      return { index, reason: `entryHash mismatch at sequence ${entry.sequenceNumber}` };
+    }
+    expectedPrev = entry.entryHash;
+  }
+  return null;
+}

package/ts/core/core.plugins.ts

@@ -0,0 +1,9 @@
+// The stateless core imports ONLY pure-computation dependencies.
+// No smartdata, no filesystem, no network, no crypto certs — this module must
+// stay usable without MongoDB or any runtime environment beyond JS itself.
+// smarthash is permitted as the sole exception for SHA-256 string hashing
+// (pure computation, needed for the GoBD hash chain).
+import * as calculation from '@fin.cx/calculation';
+import { sha256FromStringSync } from '@push.rocks/smarthash';
+
+export { calculation, sha256FromStringSync };