@fin.cx/skr 1.3.1 → 2.0.0

package/ts/core/core.taxscenario.ts

@@ -0,0 +1,156 @@
+/**
+ * Tax scenario detection — a pure, confidence-scored cascade:
+ * document text patterns → counterparty country → amount plausibility →
+ * default. Ported from the finance.plus VatRuleDetector design, with the
+ * scenario vocabulary of core.types.
+ */
+import type { TBuKey, TCents, TTaxScenario } from './core.types.js';
+import { suggestBuKey } from './core.bukeys.js';
+
+export interface ITaxScenarioInput {
+  direction: 'inbound' | 'outbound';
+  /** ISO 3166-1 alpha-2, defaults to 'DE' */
+  homeCountry?: string;
+  counterpartyCountry?: string;
+  counterpartyVatId?: string;
+  documentText?: string;
+  netCents?: TCents;
+  vatCents?: TCents;
+  vatRatePercent?: number;
+}
+
+export interface ITaxScenarioDetection {
+  scenario: TTaxScenario;
+  confidence: number; // 0-100
+  detectedBy: 'text' | 'country' | 'amounts' | 'default';
+  reasoning: string;
+  suggestedBuKey: TBuKey;
+}
+
+export const EU_COUNTRIES = new Set([
+  'AT', 'BE', 'BG', 'CY', 'CZ', 'DK', 'EE', 'ES', 'FI', 'FR', 'GR', 'HR', 'HU',
+  'IE', 'IT', 'LT', 'LU', 'LV', 'MT', 'NL', 'PL', 'PT', 'RO', 'SE', 'SI', 'SK',
+]);
+
+const REVERSE_CHARGE_PATTERN =
+  /reverse[\s-]?charge|steuerschuldnerschaft\s+des\s+leistungsempfängers|§\s*13\s*b/i;
+const INTRA_EU_PATTERN =
+  /innergemeinschaftlich|intra[\s-]?community|steuerfreie\s+ig[\s-]?lieferung/i;
+const TAX_FREE_PATTERN = /steuerfrei|tax[\s-]?free|umsatzsteuerbefreit|§\s*4\s+ustg/i;
+const EXPORT_PATTERN = /ausfuhr|ausfuhrlieferung|export\s+delivery/i;
+
+function rateOf(input: ITaxScenarioInput): number {
+  if (typeof input.vatRatePercent === 'number') return input.vatRatePercent;
+  if (
+    typeof input.netCents === 'number' &&
+    typeof input.vatCents === 'number' &&
+    input.netCents > 0
+  ) {
+    const ratio = (input.vatCents / input.netCents) * 100;
+    if (Math.abs(ratio - 19) <= 0.5) return 19;
+    if (Math.abs(ratio - 7) <= 0.5) return 7;
+    if (ratio < 0.5) return 0;
+    return ratio;
+  }
+  return 19;
+}
+
+function detection(
+  scenario: TTaxScenario,
+  confidence: number,
+  detectedBy: ITaxScenarioDetection['detectedBy'],
+  reasoning: string,
+  input: ITaxScenarioInput,
+): ITaxScenarioDetection {
+  return {
+    scenario,
+    confidence,
+    detectedBy,
+    reasoning,
+    suggestedBuKey: suggestBuKey({
+      direction: input.direction,
+      scenario,
+      ratePercent: rateOf(input) === 7 ? 7 : rateOf(input) === 0 ? 0 : 19,
+      targetIsAutomatik: false,
+      hasExplicitVatLines: true,
+    }),
+  };
+}
+
+export function detectTaxScenario(input: ITaxScenarioInput): ITaxScenarioDetection {
+  const home = (input.homeCountry ?? 'DE').toUpperCase();
+  const text = input.documentText ?? '';
+  const rate = rateOf(input);
+
+  // Stage 1: explicit wording on the document
+  if (text) {
+    if (REVERSE_CHARGE_PATTERN.test(text)) {
+      return detection(
+        'reverse_charge_13b',
+        90,
+        'text',
+        'Document mentions reverse charge / §13b UStG',
+        input,
+      );
+    }
+    if (INTRA_EU_PATTERN.test(text)) {
+      return detection(
+        input.direction === 'inbound' ? 'intra_eu_acquisition' : 'intra_eu_supply',
+        90,
+        'text',
+        'Document mentions an intra-community transaction',
+        input,
+      );
+    }
+    if (EXPORT_PATTERN.test(text) && input.direction === 'outbound') {
+      return detection('export_third_country', 90, 'text', 'Document mentions Ausfuhr/export', input);
+    }
+    if (TAX_FREE_PATTERN.test(text)) {
+      return detection('domestic_tax_free', 85, 'text', 'Document mentions tax exemption', input);
+    }
+  }
+
+  // Stage 2: counterparty country (B2B assumed when a VAT ID is present)
+  const country = input.counterpartyCountry?.toUpperCase();
+  if (country && country !== home) {
+    if (EU_COUNTRIES.has(country)) {
+      const b2b = !!input.counterpartyVatId;
+      return detection(
+        input.direction === 'inbound' ? 'intra_eu_acquisition' : 'intra_eu_supply',
+        b2b ? 80 : 60,
+        'country',
+        `Counterparty in EU country ${country}${b2b ? ' with VAT ID' : ' without VAT ID'}`,
+        input,
+      );
+    }
+    return detection(
+      input.direction === 'inbound' ? 'reverse_charge_13b' : 'export_third_country',
+      75,
+      'country',
+      `Counterparty in third country ${country}`,
+      input,
+    );
+  }
+
+  // Stage 3: amount plausibility
+  if (typeof input.netCents === 'number' && typeof input.vatCents === 'number') {
+    if (input.netCents > 0 && input.vatCents === 0) {
+      return detection('domestic_tax_free', 60, 'amounts', 'Positive net with zero VAT', input);
+    }
+    if (rate === 7) {
+      return detection('domestic_reduced', 70, 'amounts', 'VAT/net ratio matches 7 %', input);
+    }
+    if (rate === 19) {
+      return detection('domestic_standard', 70, 'amounts', 'VAT/net ratio matches 19 %', input);
+    }
+  }
+
+  // Default
+  return detection(
+    rate === 7 ? 'domestic_reduced' : 'domestic_standard',
+    50,
+    'default',
+    'No signals — assuming domestic transaction at standard assumptions',
+    input,
+  );
+}

package/ts/core/core.types.ts

@@ -0,0 +1,74 @@
+import type { TCents } from '@fin.cx/calculation';
+
+export type { TCents };
+
+export type TSKRType = 'SKR03' | 'SKR04';
+
+/**
+ * DATEV BU-Schlüssel (Steuerschlüssel), field 9 of the Buchungsstapel row.
+ * String-typed: '' means "no key" and keys keep leading semantics ('40').
+ * The set is intentionally conservative — only keys the core emits.
+ */
+export type TBuKey =
+  | ''
+  | '1'
+  | '2'
+  | '3'
+  | '8'
+  | '9'
+  | '18'
+  | '19'
+  | '40'
+  | '91'
+  | '94';
+
+export type TTaxScenario =
+  | 'domestic_standard'
+  | 'domestic_reduced'
+  | 'domestic_tax_free'
+  | 'intra_eu_supply'
+  | 'intra_eu_acquisition'
+  | 'reverse_charge_13b'
+  | 'export_third_country';
+
+export type TLineSide = 'debit' | 'credit';
+
+/**
+ * One journal line. counterAccount is the explicit DATEV Gegenkonto for this
+ * line — recipes know the pairing, so nothing has to be reconstructed later
+ * (v1 derived pairs greedily and lossily).
+ */
+export interface IJournalLineDraft {
+  accountNumber: string;
+  counterAccount: string;
+  side: TLineSide;
+  amountCents: TCents;
+  buKey: TBuKey;
+  buchungstext: string;
+  belegfeld1?: string;
+  belegfeld2?: string;
+  costCenter1?: string;
+  costCenter2?: string;
+  docLink?: string;
+  /** informational VAT share carried on the line (v1 compatibility) */
+  vatAmountCents?: TCents;
+}
+
+export interface IJournalDraft {
+  date: Date;
+  description: string;
+  reference?: string;
+  skrType: TSKRType;
+  currency: 'EUR';
+  taxScenario?: TTaxScenario;
+  /** id of the entry this draft reverses (Storno linkage, part of the hash) */
+  reversalOf?: string;
+  lines: IJournalLineDraft[];
+}
+
+export interface IValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+  normalized: IJournalDraft;
+}

package/ts/core/core.validate.ts

@@ -0,0 +1,119 @@
+/**
+ * Pure journal validation. No chart lookups, no persistence — structural and
+ * arithmetic invariants only. Account-existence checks belong to the
+ * persistence layer, which owns the chart of accounts.
+ */
+import type { IJournalDraft, IJournalLineDraft, IValidationResult } from './core.types.js';
+import { isKnownBuKey } from './core.bukeys.js';
+import type { IAccountPolicy } from './core.accountpolicy.js';
+import { isAutomatikAccount } from './core.accountpolicy.js';
+
+export const DATEV_MAX_BUCHUNGSTEXT = 60;
+export const DATEV_MAX_BELEGFELD = 36;
+
+/**
+ * Validate (and normalize) a journal draft.
+ *
+ * Normalization: negative amounts are flipped to the opposite side so the
+ * ledger only ever stores positive amounts with an explicit side.
+ * Balance check is EXACT — integer cents, no tolerance.
+ */
+export function validateJournalDraft(
+  draft: IJournalDraft,
+  policy?: IAccountPolicy,
+): IValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  const normalizedLines: IJournalLineDraft[] = draft.lines.map((line) => {
+    if (line.amountCents < 0) {
+      return {
+        ...line,
+        amountCents: -line.amountCents,
+        side: line.side === 'debit' ? 'credit' : 'debit',
+      };
+    }
+    return { ...line };
+  });
+  const normalized: IJournalDraft = { ...draft, lines: normalizedLines };
+
+  if (!(draft.date instanceof Date) || Number.isNaN(draft.date.getTime())) {
+    errors.push('Journal draft requires a valid date');
+  }
+  if (!draft.description) {
+    warnings.push('Journal draft has no description');
+  }
+  if (draft.currency !== 'EUR') {
+    errors.push(`Core booking currency must be EUR, got '${draft.currency}'`);
+  }
+  if (normalizedLines.length < 2) {
+    errors.push('A journal entry requires at least two lines');
+  }
+
+  let debitTotal = 0;
+  let creditTotal = 0;
+
+  normalizedLines.forEach((line, index) => {
+    const label = `line ${index + 1} (${line.accountNumber || '?'})`;
+
+    if (!Number.isSafeInteger(line.amountCents)) {
+      errors.push(`${label}: amountCents must be a safe integer, got ${line.amountCents}`);
+      return;
+    }
+    if (line.amountCents === 0) {
+      errors.push(`${label}: amount must not be zero`);
+      return;
+    }
+    if (!line.accountNumber) {
+      errors.push(`${label}: accountNumber is required`);
+    }
+    if (!line.counterAccount) {
+      errors.push(`${label}: counterAccount (Gegenkonto) is required`);
+    } else if (line.counterAccount === line.accountNumber) {
+      errors.push(`${label}: account and counterAccount must differ`);
+    }
+    if (!isKnownBuKey(line.buKey)) {
+      errors.push(`${label}: unknown BU key '${line.buKey}'`);
+    }
+    if (line.buchungstext && line.buchungstext.length > DATEV_MAX_BUCHUNGSTEXT) {
+      warnings.push(
+        `${label}: buchungstext exceeds ${DATEV_MAX_BUCHUNGSTEXT} chars and will be truncated in DATEV export`,
+      );
+    }
+    if (line.belegfeld1 && line.belegfeld1.length > DATEV_MAX_BELEGFELD) {
+      warnings.push(
+        `${label}: belegfeld1 exceeds ${DATEV_MAX_BELEGFELD} chars and will be truncated in DATEV export`,
+      );
+    }
+
+    if (policy) {
+      if (isAutomatikAccount(policy, line.accountNumber) && line.buKey !== '' && line.buKey !== '40') {
+        errors.push(
+          `${label}: Automatikkonto must not carry BU key '${line.buKey}' (only none or 40)`,
+        );
+      }
+      if (
+        line.accountNumber === policy.debtorsControl ||
+        line.accountNumber === policy.creditorsControl
+      ) {
+        errors.push(
+          `${label}: direct posting to control account ${line.accountNumber} — use a personal account`,
+        );
+      }
+    }
+
+    if (line.side === 'debit') {
+      debitTotal += line.amountCents;
+    } else {
+      creditTotal += line.amountCents;
+    }
+  });
+
+  if (errors.length === 0 && debitTotal !== creditTotal) {
+    errors.push(
+      `Entry is not balanced: debit ${debitTotal} cents !== credit ${creditTotal} cents`,
+    );
+  }
+
+  return { valid: errors.length === 0, errors, warnings, normalized };
+}

package/ts/core/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Stateless booking core: pure types, BU keys, tax scenario detection,
+ * account policies, booking recipes, validation, DATEV Buchungsstapel writer,
+ * and hash chaining. Nothing in here touches MongoDB, the filesystem, or the
+ * network — plain inputs in, validated journal drafts / DATEV rows out.
+ */
+export * from './core.types.js';
+export * from './core.bukeys.js';
+export * from './core.taxscenario.js';
+export * from './core.accountpolicy.js';
+export * from './core.validate.js';
+export * from './core.recipes.js';
+export * from './core.datev.js';
+export { DATEV_COLUMN_CAPTIONS } from './core.datev.captions.js';
+export * from './core.hash.js';

package/ts/index.ts

@@ -1,4 +1,35 @@
 export * from './skr.types.js';
+export * as core from './core/index.js';
+export * from './skr.errors.js';
+export { JournalPoster, buildHashPayload } from './skr.posting.js';
+export type { IPostDraftOptions } from './skr.posting.js';
+export {
+  festschreibePeriod,
+  getPeriodState,
+  assertPeriodOpen,
+  periodOf,
+  fiscalYearOf,
+} from './skr.period.js';
+export type { ILedgerPeriodState } from './skr.period.js';
+export { getSequenceState } from './skr.sequence.js';
+export type { ILedgerSequenceState } from './skr.sequence.js';
+export { aggregateTrialBalance, aggregateAccountBalance } from './skr.balances.js';
+export type {
+  IAccountBalanceCents,
+  ITrialBalanceCents,
+  IBalanceQueryOptions,
+} from './skr.balances.js';
+export { verifyHashChain } from './skr.verify.js';
+export type { IChainVerificationResult } from './skr.verify.js';
+export { migrateToV2 } from './skr.migrate.js';
+export type { IMigrationReport } from './skr.migrate.js';
+export {
+  transactionDataToDraft,
+  journalInputToDraft,
+  entryToTransactionView,
+  accountLineViews,
+  mapNumericPostingKey,
+} from './skr.txview.js';
 export { Account } from './skr.classes.account.js';
 export { Transaction } from './skr.classes.transaction.js';
 export { JournalEntry } from './skr.classes.journalentry.js';

package/ts/plugins.ts

@@ -1,3 +1,6 @@
+// @fin.cx scope
+import * as calculation from '@fin.cx/calculation';
+
 // @push.rocks scope
 import * as smartdata from '@push.rocks/smartdata';
 import * as smartunique from '@push.rocks/smartunique';
@@ -53,6 +56,7 @@ const smartfile = {
 };
 
 export {
+  calculation,
   smartdata,
   smartunique,
   smarttime,