@fin.cx/chartdata 2.13.0 → 2.15.0

package/ts/chartdata.types.ts

@@ -16,6 +16,83 @@ export type TAccountType = 'asset' | 'liability' | 'equity' | 'revenue' | 'expen
  */
 export type TAccountRole = 'asset_sale_proceeds' | 'disposal_book_value';
 
+/**
+ * What an account books of a business's securities (Wertpapiere): holding
+ * them, their income, their sale, their valuation at a closing date and the
+ * taxes withheld from their income. A booking of securities finds its
+ * account by this role together with the account's `taxRule`: within a
+ * chart, no two accounts share both.
+ * - holdings, by the balance-sheet item (§ 266 Abs. 2 HGB):
+ *   'holding_fixed' (Wertpapiere des Anlagevermögens, A.III.5),
+ *   'holding_fixed_shares' (those whose income falls under the
+ *   Teileinkünfteverfahren, A.III.5), 'holding_fixed_bonds' (fixed-interest
+ *   ones, A.III.5), 'holding_current' (sonstige Wertpapiere, B.III.2);
+ * - their income (dividends, distributions, coupons) by whether the
+ *   securities are fixed or current assets: 'income_fixed', 'income_current';
+ * - the sale of current assets, stated net: 'sale_gain_current',
+ *   'sale_loss_current';
+ * - the sale of fixed assets, stated gross on the accounts of a fixed asset's
+ *   disposal (`accountRole`): what it fetched, 'sale_proceeds_fixed_gain' and
+ *   'sale_proceeds_fixed_loss', and the book value it leaves the books with,
+ *   'book_value_fixed_gain' and 'book_value_fixed_loss', by whether the sale
+ *   makes a book gain or a book loss;
+ * - the costs of a sale DATEV states apart, 'sale_costs_gain' and
+ *   'sale_costs_loss' (§ 8b Abs. 2 Satz 2 KStG);
+ * - the valuation at a closing date (§ 253 Abs. 3 to 5 HGB): a fixed asset's
+ *   write-down for a lasting or a temporary decline,
+ *   'writedown_fixed_lasting' and 'writedown_fixed_temporary', a current
+ *   asset's, 'writedown_current', and the write-ups, 'writeup_fixed',
+ *   'writeup_current', and 'writeup' where one account takes either;
+ * - the taxes withheld from their income: 'capital_gains_tax'
+ *   (Kapitalertragsteuer) and 'capital_gains_tax_soli' (the Solidaritätszuschlag
+ *   on it), 'foreign_withholding_tax' (a foreign tax to be credited or
+ *   deducted), 'foreign_tax_exempt_income' (a foreign tax on income exempt at
+ *   home), and 'foreign_tax_refund' (a foreign tax to be refunded);
+ * - 'margin_interest': the interest on a short-term debt, such as a broker's
+ *   margin loan.
+ */
+export type TSecuritiesRole =
+  | 'holding_fixed'
+  | 'holding_fixed_shares'
+  | 'holding_fixed_bonds'
+  | 'holding_current'
+  | 'income_fixed'
+  | 'income_current'
+  | 'sale_gain_current'
+  | 'sale_loss_current'
+  | 'sale_proceeds_fixed_gain'
+  | 'sale_proceeds_fixed_loss'
+  | 'book_value_fixed_gain'
+  | 'book_value_fixed_loss'
+  | 'sale_costs_gain'
+  | 'sale_costs_loss'
+  | 'writedown_fixed_lasting'
+  | 'writedown_fixed_temporary'
+  | 'writedown_current'
+  | 'writeup_fixed'
+  | 'writeup_current'
+  | 'writeup'
+  | 'capital_gains_tax'
+  | 'capital_gains_tax_soli'
+  | 'foreign_withholding_tax'
+  | 'foreign_tax_exempt_income'
+  | 'foreign_tax_refund'
+  | 'margin_interest';
+
+/**
+ * A rule of the income tax law an income or expense account is kept for, as
+ * its DATEV name states it:
+ * - 'estg_3_40_kstg_8b': income from shares and the expenses of it under the
+ *   Teileinkünfteverfahren (§ 3 Nr. 40, § 3c Abs. 2 EStG) or, for a
+ *   corporation, § 8b KStG — DATEV names these accounts "§ 3 Nr. 40 EStG bzw.
+ *   § 8b … KStG". DATEV's interface to the corporate income tax treats their
+ *   income as 100 % tax-free and their expenses as 100 % non-deductible, its
+ *   interface to the trade tax 40 % each (Kontenrahmen SKR 03 and SKR 04,
+ *   gültig für 2026, footnote 9); the corrections are made in the return, not
+ *   in the books.
+ */
+export type TTaxRule = 'estg_3_40_kstg_8b';
+
 /**
  * Built-in DATEV tax automatism of an account. Lines on automatik accounts
  * must carry no BU key (automatism applies) or key 40 (automatism cancelled).
@@ -35,6 +112,107 @@ export interface IUstvaMapping {
   role: 'base' | 'tax';
 }
 
+/**
+ * Where an account's movements go in the Anlage EÜR (the standardised
+ * Einnahmenüberschussrechnung, § 60 Abs. 4 EStDV), by the Kennzahl of the
+ * form's line (`ANLAGE_EUER_FORMS`; the line number itself changes with the
+ * form year, the Kennzahl does not):
+ * - `{ kennzahl }`: the movements of both sides, netted toward the line's own
+ *   side: a line of receipts counts credits less debits (a sales deduction
+ *   lowers the receipts), a line of expenses debits less credits (a received
+ *   discount lowers the goods);
+ * - `{ debitKennzahl, creditKennzahl }`: each side on a line of its own, not
+ *   netted: the VAT paid to the tax office (Kz 186) and the VAT it refunded
+ *   (Kz 141) on one account.
+ */
+export type TEuerMapping = { kennzahl: number } | { debitKennzahl: number; creditKennzahl: number };
+
+/**
+ * Why an account's movements are no part of the Anlage EÜR, which counts
+ * receipts and expenses when paid (§ 4 Abs. 3, § 11 EStG):
+ * - 'balance_sheet': a payment moves between the business's own money, claims
+ *   and debts (bank, cash, receivables, payables, loans, provisions, equity);
+ * - 'fixed_asset': a fixed asset's cost reaches the form through its
+ *   depreciation and, at its disposal, its residual book value (AfA, GWG,
+ *   Restbuchwerte), not through the asset account;
+ * - 'inventory': stock and its changes: goods count when paid, and a
+ *   cash-basis book keeps no inventory;
+ * - 'valuation': a value at a closing date, which a cash-basis book does not
+ *   state (currency revaluation, the valuation of the cash funds);
+ * - 'pass_through': durchlaufende Posten, received and spent in another's name
+ *   and for another's account (§ 4 Abs. 3 Satz 2 EStG);
+ * - 'reverse_charge': the tax a recipient owes on an intra-Community
+ *   acquisition or under § 13b UStG and deducts as input tax in the same
+ *   return: no receipt and no payment of its own (Anleitung zur Anlage EÜR,
+ *   Zeile 58); what a return leaves to pay counts as paid VAT (Kz 186);
+ * - 'closing': a carry-forward, closing or statistical account, which records
+ *   no business transaction;
+ * - 'deferred_current_asset': a current asset named in § 4 Abs. 3 Satz 4
+ *   EStG — shares, securities, land and buildings —, whose cost counts only
+ *   when its sale's proceeds are received or it is withdrawn, as goods
+ *   (Zeile 29, Kz 100), through the list of such assets in the Anlage AVEÜR
+ *   (Zeilen 93 bis 96), not when it is paid.
+ */
+export type TEuerExclusion =
+  | 'balance_sheet'
+  | 'fixed_asset'
+  | 'inventory'
+  | 'valuation'
+  | 'pass_through'
+  | 'reverse_charge'
+  | 'closing'
+  | 'deferred_current_asset';
+
+/**
+ * The part of the Anlage EÜR a line belongs to: Betriebseinnahmen (Zeilen
+ * 12 bis 22), Betriebsausgaben (Zeilen 24 bis 76 of the 2026 form), or the
+ * private Entnahmen and Einlagen of a sole proprietor (Zeilen 107 and 108).
+ */
+export type TEuerSection = 'income' | 'expense' | 'private';
+
+/** One line of the Anlage EÜR of a form year that an account's movements can go to. */
+export interface IEuerFormLine {
+  /**
+   * The line's Kennzahl on the form. Unique among the lines of a form's
+   * table; the form reuses some numbers in its general and closing sections,
+   * which the table does not hold.
+   */
+  kennzahl: number;
+  /** the line ("Zeile") on the year's form */
+  line: number;
+  /** the line's text on the form; a line of two columns names its column ("nicht abziehbar", "abziehbar") */
+  label: string;
+  section: TEuerSection;
+  /**
+   * How the line enters its section's sum (Zeilen 23 and 76): 1 adds, -1
+   * subtracts (the travel to the first place of business, Zeile 73, and the
+   * non-deductible amounts, Zeile 75), 0 not at all (a "davon" line, the
+   * column "nicht abziehbar", the Entnahmen and Einlagen).
+   */
+  sign: 1 | -1 | 0;
+  /** the side whose movements the line counts, net of the other: receipts and Einlagen credit, expenses and Entnahmen debit */
+  side: 'debit' | 'credit';
+}
+
+/** The lines of the Anlage EÜR of one form year, as the BMF published the form. */
+export interface IEuerForm {
+  year: number;
+  lines: IEuerFormLine[];
+  /** the published form these lines were read from */
+  provenance: string;
+}
+
+/**
+ * The lines an account's movements go to in a form year:
+ * - 'netted': both sides, netted, on one line;
+ * - 'split': each side on a line of its own;
+ * - 'excluded': none, and why.
+ */
+export type TEuerAccountLines =
+  | { kind: 'netted'; line: IEuerFormLine }
+  | { kind: 'split'; debitLine: IEuerFormLine; creditLine: IEuerFormLine }
+  | { kind: 'excluded'; exclusion: TEuerExclusion };
+
 export interface IChartAccount {
   accountNumber: string;
   accountName: string;
@@ -42,6 +220,10 @@ export interface IChartAccount {
   accountType: TAccountType;
   /** what the account is for beyond its type and HGB position; unset = they say it all */
   accountRole?: TAccountRole;
+  /** what the account books of a business's securities; unset = nothing of its own */
+  securitiesRole?: TSecuritiesRole;
+  /** the income tax rule the account is kept for, as its DATEV name states it; unset = none of its own */
+  taxRule?: TTaxRule;
   description?: string;
   automatikFunction?: TAutomatikFunction;
   /** BU keys allowed on lines of this account ('' = none). Unset = all. */
@@ -53,6 +235,10 @@ export interface IChartAccount {
   hgb275Position?: string;
   /** E-Bilanz de-gaap-ci taxonomy position (A3 — not yet populated) */
   ebilanzPosition?: string;
+  /** the Anlage EÜR line(s) the account's movements go to; every account has this or `euerExclusion` */
+  euer?: TEuerMapping;
+  /** why the account's movements are no part of the Anlage EÜR */
+  euerExclusion?: TEuerExclusion;
   /** where this record's facts come from (source, date) */
   provenance: string;
   /** first year this record is valid for */
@@ -66,7 +252,8 @@ export interface IChart {
   accounts: IChartAccount[];
 }
 
-export type TMappingDimension = 'ustva' | 'hgb266' | 'hgb275' | 'ebilanz';
+/** 'euer' counts an account covered when it maps to the Anlage EÜR or is excluded from it with a reason. */
+export type TMappingDimension = 'ustva' | 'hgb266' | 'hgb275' | 'ebilanz' | 'euer';
 
 export interface IMappingCoverage {
   dimension: TMappingDimension;