@fin.cx/skr 1.3.0 → 2.0.0

package/ts/core/core.recipes.ts

@@ -0,0 +1,659 @@
+/**
+ * Booking recipes — pure builders: (input, policy) => IJournalDraft.
+ * No persistence, no chart lookups; amounts are integer cents and every
+ * fractional computation goes through @fin.cx/calculation.
+ */
+import * as plugins from './core.plugins.js';
+import type {
+  IJournalDraft,
+  IJournalLineDraft,
+  TCents,
+  TTaxScenario,
+} from './core.types.js';
+import type { IAccountPolicy } from './core.accountpolicy.js';
+import { isAutomatikAccount } from './core.accountpolicy.js';
+import { suggestBuKey } from './core.bukeys.js';
+
+const { splitGrossCents, vatFromNetCents } = plugins.calculation;
+
+export interface IVendorInvoiceInput {
+  date: Date;
+  /** creditor personal account (70000-99999) */
+  vendorAccount: string;
+  expenseAccount?: string;
+  /** invoice total that becomes payable (for §13b / igE this equals net) */
+  grossCents: TCents;
+  vatRatePercent?: number;
+  scenario?: TTaxScenario;
+  invoiceNumber?: string;
+  description: string;
+  costCenter1?: string;
+  docLink?: string;
+}
+
+export interface ICustomerInvoiceInput {
+  date: Date;
+  /** debtor personal account (10000-69999) */
+  customerAccount: string;
+  revenueAccount?: string;
+  grossCents: TCents;
+  vatRatePercent?: number;
+  scenario?: TTaxScenario;
+  invoiceNumber?: string;
+  description: string;
+  costCenter1?: string;
+  docLink?: string;
+}
+
+export interface IBankPaymentInput {
+  date: Date;
+  direction: 'outgoing' | 'incoming';
+  bankAccount?: string;
+  /** personal debtor/creditor account being settled */
+  counterpartyAccount: string;
+  /** open gross amount being settled */
+  expectedCents: TCents;
+  /** amount that actually moved on the bank account */
+  paidCents: TCents;
+  /** book the difference as Skonto with VAT correction at this rate */
+  skonto?: { ratePercent: number };
+  /** write off differences up to this size to rounding-diff accounts (default 0) */
+  diffToleranceCents?: TCents;
+  description: string;
+  reference?: string;
+}
+
+export interface IInternalTransferInput {
+  date: Date;
+  fromBankAccount: string;
+  toBankAccount: string;
+  amountCents: TCents;
+  description: string;
+  reference?: string;
+}
+
+export interface ISuspenseInput {
+  date: Date;
+  direction: 'incoming' | 'outgoing';
+  amountCents: TCents;
+  bankAccount?: string;
+  description: string;
+  reference?: string;
+}
+
+export interface ISuspenseResolutionInput {
+  date: Date;
+  direction: 'incoming' | 'outgoing';
+  amountCents: TCents;
+  /** the account the suspense amount really belongs to */
+  targetAccount: string;
+  description: string;
+  reference?: string;
+}
+
+export interface IFxDifferenceInput {
+  kind: 'payable' | 'receivable';
+  /** EUR value at booking date */
+  bookedCents: TCents;
+  /** EUR value actually settled */
+  settledCents: TCents;
+  counterAccount: string;
+  buchungstext: string;
+  belegfeld1?: string;
+}
+
+interface ILineSpec {
+  accountNumber: string;
+  counterAccount: string;
+  side: 'debit' | 'credit';
+  amountCents: TCents;
+  buKey?: IJournalLineDraft['buKey'];
+}
+
+function makeDraft(
+  base: {
+    date: Date;
+    description: string;
+    reference?: string;
+    scenario?: TTaxScenario;
+    belegfeld1?: string;
+    costCenter1?: string;
+    docLink?: string;
+  },
+  policy: IAccountPolicy,
+  lines: ILineSpec[],
+): IJournalDraft {
+  return {
+    date: base.date,
+    description: base.description,
+    reference: base.reference,
+    skrType: policy.skrType,
+    currency: 'EUR',
+    taxScenario: base.scenario,
+    lines: lines
+      .filter((line) => line.amountCents !== 0)
+      .map((line) => ({
+        accountNumber: line.accountNumber,
+        counterAccount: line.counterAccount,
+        side: line.side,
+        amountCents: line.amountCents,
+        buKey: line.buKey ?? '',
+        buchungstext: base.description,
+        belegfeld1: base.belegfeld1,
+        costCenter1: base.costCenter1,
+        docLink: base.docLink,
+      })),
+  };
+}
+
+function assertPositive(amountCents: TCents, label: string): void {
+  if (!Number.isSafeInteger(amountCents) || amountCents <= 0) {
+    throw new Error(`${label} must be a positive integer cent amount, got ${amountCents}`);
+  }
+}
+
+/**
+ * Eingangsrechnung (vendor invoice).
+ * domestic: expense net + Vorsteuer + creditor gross.
+ * §13b / igE: expense net + paired input/output VAT + creditor net.
+ * tax-free/import: expense gross + creditor gross.
+ */
+export function bookVendorInvoice(
+  input: IVendorInvoiceInput,
+  policy: IAccountPolicy,
+): IJournalDraft {
+  assertPositive(input.grossCents, 'grossCents');
+  const scenario = input.scenario ?? 'domestic_standard';
+  const rate =
+    input.vatRatePercent ?? (scenario === 'domestic_reduced' ? 7 : scenario === 'domestic_tax_free' ? 0 : 19);
+  const expenseAccount = input.expenseAccount ?? policy.expenseDefault;
+  const base = {
+    date: input.date,
+    description: input.description,
+    reference: input.invoiceNumber,
+    scenario,
+    belegfeld1: input.invoiceNumber,
+    costCenter1: input.costCenter1,
+    docLink: input.docLink,
+  };
+
+  const expenseIsAutomatik = isAutomatikAccount(policy, expenseAccount);
+
+  if (scenario === 'domestic_standard' || scenario === 'domestic_reduced') {
+    const { netCents, vatCents } = splitGrossCents(input.grossCents, rate);
+    const vatAccount = rate === 7 ? policy.vat.inputReduced : policy.vat.inputStandard;
+    return makeDraft(base, policy, [
+      {
+        accountNumber: expenseAccount,
+        counterAccount: input.vendorAccount,
+        side: 'debit',
+        amountCents: netCents,
+        buKey: suggestBuKey({
+          direction: 'inbound',
+          scenario,
+          ratePercent: rate,
+          targetIsAutomatik: expenseIsAutomatik,
+          hasExplicitVatLines: vatCents > 0,
+        }),
+      },
+      {
+        accountNumber: vatAccount,
+        counterAccount: input.vendorAccount,
+        side: 'debit',
+        amountCents: vatCents,
+      },
+      {
+        accountNumber: input.vendorAccount,
+        counterAccount: expenseAccount,
+        side: 'credit',
+        amountCents: input.grossCents,
+      },
+    ]);
+  }
+
+  if (scenario === 'reverse_charge_13b' || scenario === 'intra_eu_acquisition') {
+    // invoice total is net; German VAT is self-assessed in paired lines
+    const vatCents = vatFromNetCents(input.grossCents, rate);
+    const inputVatAccount =
+      scenario === 'reverse_charge_13b' ? policy.vat.reverseChargeInput : policy.vat.intraEuAcqInput;
+    const outputVatAccount =
+      scenario === 'reverse_charge_13b'
+        ? policy.vat.reverseChargeOutput
+        : policy.vat.intraEuAcqOutput;
+    return makeDraft(base, policy, [
+      {
+        accountNumber: expenseAccount,
+        counterAccount: input.vendorAccount,
+        side: 'debit',
+        amountCents: input.grossCents,
+        buKey: suggestBuKey({
+          direction: 'inbound',
+          scenario,
+          ratePercent: rate,
+          targetIsAutomatik: expenseIsAutomatik,
+          hasExplicitVatLines: vatCents > 0,
+        }),
+      },
+      {
+        accountNumber: inputVatAccount,
+        counterAccount: outputVatAccount,
+        side: 'debit',
+        amountCents: vatCents,
+      },
+      {
+        accountNumber: outputVatAccount,
+        counterAccount: inputVatAccount,
+        side: 'credit',
+        amountCents: vatCents,
+      },
+      {
+        accountNumber: input.vendorAccount,
+        counterAccount: expenseAccount,
+        side: 'credit',
+        amountCents: input.grossCents,
+      },
+    ]);
+  }
+
+  // domestic_tax_free, export_third_country (import without German VAT),
+  // intra_eu_supply is not a vendor scenario but degrades to the same shape
+  return makeDraft(base, policy, [
+    {
+      accountNumber: expenseAccount,
+      counterAccount: input.vendorAccount,
+      side: 'debit',
+      amountCents: input.grossCents,
+    },
+    {
+      accountNumber: input.vendorAccount,
+      counterAccount: expenseAccount,
+      side: 'credit',
+      amountCents: input.grossCents,
+    },
+  ]);
+}
+
+/**
+ * Ausgangsrechnung (customer invoice).
+ */
+export function bookCustomerInvoice(
+  input: ICustomerInvoiceInput,
+  policy: IAccountPolicy,
+): IJournalDraft {
+  assertPositive(input.grossCents, 'grossCents');
+  const scenario = input.scenario ?? 'domestic_standard';
+  const rate =
+    input.vatRatePercent ?? (scenario === 'domestic_reduced' ? 7 : scenario === 'domestic_standard' ? 19 : 0);
+  const base = {
+    date: input.date,
+    description: input.description,
+    reference: input.invoiceNumber,
+    scenario,
+    belegfeld1: input.invoiceNumber,
+    costCenter1: input.costCenter1,
+    docLink: input.docLink,
+  };
+
+  if (scenario === 'domestic_standard' || scenario === 'domestic_reduced') {
+    const revenueAccount =
+      input.revenueAccount ??
+      (rate === 7 ? policy.revenue.domesticReduced : policy.revenue.domesticStandard);
+    const revenueIsAutomatik = isAutomatikAccount(policy, revenueAccount);
+    const { netCents, vatCents } = splitGrossCents(input.grossCents, rate);
+    const vatAccount = rate === 7 ? policy.vat.outputReduced : policy.vat.outputStandard;
+    return makeDraft(base, policy, [
+      {
+        accountNumber: input.customerAccount,
+        counterAccount: revenueAccount,
+        side: 'debit',
+        amountCents: input.grossCents,
+      },
+      {
+        accountNumber: revenueAccount,
+        counterAccount: input.customerAccount,
+        side: 'credit',
+        amountCents: netCents,
+        buKey: suggestBuKey({
+          direction: 'outbound',
+          scenario,
+          ratePercent: rate,
+          targetIsAutomatik: revenueIsAutomatik,
+          hasExplicitVatLines: vatCents > 0,
+        }),
+      },
+      {
+        accountNumber: vatAccount,
+        counterAccount: input.customerAccount,
+        side: 'credit',
+        amountCents: vatCents,
+      },
+    ]);
+  }
+
+  let revenueAccount = input.revenueAccount;
+  if (!revenueAccount) {
+    if (scenario === 'intra_eu_supply') revenueAccount = policy.revenue.intraEuSupply;
+    else if (scenario === 'export_third_country') revenueAccount = policy.revenue.export;
+    else if (scenario === 'reverse_charge_13b') revenueAccount = policy.revenue.reverseCharge;
+    else {
+      throw new Error(
+        `Scenario '${scenario}' requires an explicit revenueAccount — no policy default exists`,
+      );
+    }
+  }
+  const revenueIsAutomatik = isAutomatikAccount(policy, revenueAccount);
+  return makeDraft(base, policy, [
+    {
+      accountNumber: input.customerAccount,
+      counterAccount: revenueAccount,
+      side: 'debit',
+      amountCents: input.grossCents,
+    },
+    {
+      accountNumber: revenueAccount,
+      counterAccount: input.customerAccount,
+      side: 'credit',
+      amountCents: input.grossCents,
+      buKey: suggestBuKey({
+        direction: 'outbound',
+        scenario,
+        ratePercent: 0,
+        targetIsAutomatik: revenueIsAutomatik,
+        hasExplicitVatLines: false,
+      }),
+    },
+  ]);
+}
+
+/**
+ * Bank payment clearing a debtor/creditor open amount, with Skonto
+ * (incl. VAT correction) or small-difference write-off.
+ */
+export function bookBankPayment(input: IBankPaymentInput, policy: IAccountPolicy): IJournalDraft {
+  assertPositive(input.expectedCents, 'expectedCents');
+  assertPositive(input.paidCents, 'paidCents');
+  const bank = input.bankAccount ?? policy.bank;
+  const tolerance = input.diffToleranceCents ?? 0;
+  const base = {
+    date: input.date,
+    description: input.description,
+    reference: input.reference,
+    belegfeld1: input.reference,
+  };
+  const diff = input.expectedCents - input.paidCents;
+  const lines: ILineSpec[] = [];
+
+  if (input.direction === 'outgoing') {
+    lines.push(
+      {
+        accountNumber: input.counterpartyAccount,
+        counterAccount: bank,
+        side: 'debit',
+        amountCents: input.expectedCents,
+      },
+      {
+        accountNumber: bank,
+        counterAccount: input.counterpartyAccount,
+        side: 'credit',
+        amountCents: input.paidCents,
+      },
+    );
+    if (diff > 0) {
+      if (input.skonto) {
+        const rate = input.skonto.ratePercent;
+        const { netCents, vatCents } = splitGrossCents(diff, rate);
+        const skontoAccount =
+          rate === 7 ? policy.skonto.receivedReduced : policy.skonto.receivedStandard;
+        const vatAccount = rate === 7 ? policy.vat.inputReduced : policy.vat.inputStandard;
+        lines.push({
+          accountNumber: skontoAccount,
+          counterAccount: input.counterpartyAccount,
+          side: 'credit',
+          amountCents: netCents,
+          buKey: vatCents > 0 ? '40' : '',
+        });
+        if (vatCents > 0) {
+          lines.push({
+            accountNumber: vatAccount,
+            counterAccount: input.counterpartyAccount,
+            side: 'credit',
+            amountCents: vatCents,
+          });
+        }
+      } else if (diff <= tolerance) {
+        lines.push({
+          accountNumber: policy.roundingDiff.gain,
+          counterAccount: input.counterpartyAccount,
+          side: 'credit',
+          amountCents: diff,
+        });
+      } else {
+        throw new Error(
+          `Underpayment of ${diff} cents exceeds tolerance ${tolerance} — pass skonto or resolve explicitly`,
+        );
+      }
+    } else if (diff < 0) {
+      const overpaid = -diff;
+      if (overpaid <= tolerance) {
+        lines.push({
+          accountNumber: policy.roundingDiff.loss,
+          counterAccount: input.counterpartyAccount,
+          side: 'debit',
+          amountCents: overpaid,
+        });
+      } else {
+        throw new Error(
+          `Overpayment of ${overpaid} cents exceeds tolerance ${tolerance} — resolve explicitly`,
+        );
+      }
+    }
+  } else {
+    lines.push(
+      {
+        accountNumber: bank,
+        counterAccount: input.counterpartyAccount,
+        side: 'debit',
+        amountCents: input.paidCents,
+      },
+      {
+        accountNumber: input.counterpartyAccount,
+        counterAccount: bank,
+        side: 'credit',
+        amountCents: input.expectedCents,
+      },
+    );
+    if (diff > 0) {
+      if (input.skonto) {
+        const rate = input.skonto.ratePercent;
+        const { netCents, vatCents } = splitGrossCents(diff, rate);
+        const skontoAccount =
+          rate === 7 ? policy.skonto.grantedReduced : policy.skonto.grantedStandard;
+        const vatAccount = rate === 7 ? policy.vat.outputReduced : policy.vat.outputStandard;
+        lines.push({
+          accountNumber: skontoAccount,
+          counterAccount: input.counterpartyAccount,
+          side: 'debit',
+          amountCents: netCents,
+          buKey: vatCents > 0 ? '40' : '',
+        });
+        if (vatCents > 0) {
+          lines.push({
+            accountNumber: vatAccount,
+            counterAccount: input.counterpartyAccount,
+            side: 'debit',
+            amountCents: vatCents,
+          });
+        }
+      } else if (diff <= tolerance) {
+        lines.push({
+          accountNumber: policy.roundingDiff.loss,
+          counterAccount: input.counterpartyAccount,
+          side: 'debit',
+          amountCents: diff,
+        });
+      } else {
+        throw new Error(
+          `Short payment of ${diff} cents exceeds tolerance ${tolerance} — pass skonto or resolve explicitly`,
+        );
+      }
+    } else if (diff < 0) {
+      const overReceived = -diff;
+      if (overReceived <= tolerance) {
+        lines.push({
+          accountNumber: policy.roundingDiff.gain,
+          counterAccount: input.counterpartyAccount,
+          side: 'credit',
+          amountCents: overReceived,
+        });
+      } else {
+        throw new Error(
+          `Over-receipt of ${overReceived} cents exceeds tolerance ${tolerance} — resolve explicitly`,
+        );
+      }
+    }
+  }
+
+  return makeDraft(base, policy, lines);
+}
+
+/**
+ * Bank-to-bank transfer via Geldtransit — two drafts, one per bank statement,
+ * so each side reconciles independently.
+ */
+export function bookInternalTransfer(
+  input: IInternalTransferInput,
+  policy: IAccountPolicy,
+): [IJournalDraft, IJournalDraft] {
+  assertPositive(input.amountCents, 'amountCents');
+  const base = {
+    date: input.date,
+    description: input.description,
+    reference: input.reference,
+    belegfeld1: input.reference,
+  };
+  const outgoing = makeDraft(base, policy, [
+    {
+      accountNumber: policy.geldtransit,
+      counterAccount: input.fromBankAccount,
+      side: 'debit',
+      amountCents: input.amountCents,
+    },
+    {
+      accountNumber: input.fromBankAccount,
+      counterAccount: policy.geldtransit,
+      side: 'credit',
+      amountCents: input.amountCents,
+    },
+  ]);
+  const incoming = makeDraft(base, policy, [
+    {
+      accountNumber: input.toBankAccount,
+      counterAccount: policy.geldtransit,
+      side: 'debit',
+      amountCents: input.amountCents,
+    },
+    {
+      accountNumber: policy.geldtransit,
+      counterAccount: input.toBankAccount,
+      side: 'credit',
+      amountCents: input.amountCents,
+    },
+  ]);
+  return [outgoing, incoming];
+}
+
+/**
+ * Park an unclear bank movement on the clearing account.
+ */
+export function bookToSuspense(input: ISuspenseInput, policy: IAccountPolicy): IJournalDraft {
+  assertPositive(input.amountCents, 'amountCents');
+  const bank = input.bankAccount ?? policy.bank;
+  const base = {
+    date: input.date,
+    description: input.description,
+    reference: input.reference,
+    belegfeld1: input.reference,
+  };
+  if (input.direction === 'incoming') {
+    return makeDraft(base, policy, [
+      { accountNumber: bank, counterAccount: policy.clearing, side: 'debit', amountCents: input.amountCents },
+      { accountNumber: policy.clearing, counterAccount: bank, side: 'credit', amountCents: input.amountCents },
+    ]);
+  }
+  return makeDraft(base, policy, [
+    { accountNumber: policy.clearing, counterAccount: bank, side: 'debit', amountCents: input.amountCents },
+    { accountNumber: bank, counterAccount: policy.clearing, side: 'credit', amountCents: input.amountCents },
+  ]);
+}
+
+/**
+ * Move a parked suspense amount to its real account once clarified.
+ */
+export function resolveSuspense(
+  input: ISuspenseResolutionInput,
+  policy: IAccountPolicy,
+): IJournalDraft {
+  assertPositive(input.amountCents, 'amountCents');
+  const base = {
+    date: input.date,
+    description: input.description,
+    reference: input.reference,
+    belegfeld1: input.reference,
+  };
+  if (input.direction === 'incoming') {
+    return makeDraft(base, policy, [
+      {
+        accountNumber: policy.clearing,
+        counterAccount: input.targetAccount,
+        side: 'debit',
+        amountCents: input.amountCents,
+      },
+      {
+        accountNumber: input.targetAccount,
+        counterAccount: policy.clearing,
+        side: 'credit',
+        amountCents: input.amountCents,
+      },
+    ]);
+  }
+  return makeDraft(base, policy, [
+    {
+      accountNumber: input.targetAccount,
+      counterAccount: policy.clearing,
+      side: 'debit',
+      amountCents: input.amountCents,
+    },
+    {
+      accountNumber: policy.clearing,
+      counterAccount: input.targetAccount,
+      side: 'credit',
+      amountCents: input.amountCents,
+    },
+  ]);
+}
+
+/**
+ * Realized FX difference lines for a settlement whose EUR value moved between
+ * booking and payment. Returns lines to embed into the settlement draft
+ * (empty array when there is no difference).
+ */
+export function fxDifferenceLines(
+  input: IFxDifferenceInput,
+  policy: IAccountPolicy,
+): IJournalLineDraft[] {
+  const diff = input.settledCents - input.bookedCents;
+  if (diff === 0) return [];
+  const isGain = input.kind === 'payable' ? diff < 0 : diff > 0;
+  const amountCents = Math.abs(diff);
+  return [
+    {
+      accountNumber: isGain ? policy.fx.gain : policy.fx.loss,
+      counterAccount: input.counterAccount,
+      side: isGain ? 'credit' : 'debit',
+      amountCents,
+      buKey: '',
+      buchungstext: input.buchungstext,
+      belegfeld1: input.belegfeld1,
+    },
+  ];
+}