@fin.cx/chartdata 2.14.0 → 2.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fin.cx/chartdata",
-  "version": "2.14.0",
+  "version": "2.16.0",
   "private": false,
   "description": "Year-versioned German SKR03/SKR04 chart-of-accounts datasets with Automatikkonto functions, BU-key rules, UStVA-Kennzahl and Anlage EÜR mappings",
   "main": "dist_ts/index.js",

package/readme.md

@@ -27,6 +27,18 @@ For reporting bugs, issues, or security vulnerabilities, please visit [community
   not tell it apart from the others of its position: a fixed asset's sale
   proceeds (`asset_sale_proceeds`) and the book value of a disposed fixed
   asset (`disposal_book_value`), listed per chart by `getAccountsByRole`
+- Securities accounts (Wertpapiere) with their securities role
+  (`securitiesRole`): the holdings of fixed and current assets, their income,
+  their sale (net for current assets, gross on a Finanzanlage's disposal
+  accounts), the costs of a sale, write-downs and write-ups, the taxes withheld
+  from their income and the margin interest, listed per chart by
+  `getAccountsBySecuritiesRole` and found one by one with `getSecuritiesAccount`
+- DATEV's mark "HB" (`commercialOnly`): an account posted in the commercial
+  balance sheet only
+- The tax rule an income or expense account is kept for (`taxRule`):
+  `estg_3_40_kstg_8b` on every account DATEV names "§ 3 Nr. 40 EStG bzw. § 8b …
+  KStG", whose income DATEV's corporate-tax interface treats as tax-free and
+  whose expenses as non-deductible
 - Account→Anlage EÜR mappings (`euer`) for the Einnahmenüberschussrechnung
   (§ 4 Abs. 3 EStG, § 60 Abs. 4 EStDV), with the lines of the 2025 and 2026
   forms (`ANLAGE_EUER_FORMS`); every account maps or is excluded with its
@@ -75,6 +87,61 @@ getAccountsByRole('SKR04', 2026, 'disposal_book_value').map((account) => account
 // ['4855', '4856', '4857', '4858', '6895', '6896', '6897', '6898']
 ```
 
+### Securities
+
+A booking of securities finds its account by the securities role and the tax
+rule; within a chart no two accounts share both. DATEV keeps an account under
+§ 3 Nr. 40 EStG / § 8b KStG beside most ordinary ones (`taxRule:
+'estg_3_40_kstg_8b'`); whether a dividend or a gain belongs there is the
+booking's decision, not the account's: a holding of less than 10 % at the start
+of the calendar year receives taxable dividends (§ 8b Abs. 4 KStG), while a
+share's sale gain falls under § 8b Abs. 2 KStG whatever the holding.
+
+```ts
+import { getSecuritiesAccount, getAccountsBySecuritiesRole } from '@fin.cx/chartdata';
+
+getSecuritiesAccount('SKR04', 2026, 'holding_current')?.accountNumber; // '1510' Sonstige Wertpapiere
+getSecuritiesAccount('SKR04', 2026, 'sale_gain_current', 'estg_3_40_kstg_8b')?.accountNumber; // '4906'
+getSecuritiesAccount('SKR03', 2026, 'income_current')?.accountNumber; // '2654'
+getSecuritiesAccount('SKR03', 2026, 'income_current', 'estg_3_40_kstg_8b')?.accountNumber; // '2655'
+getSecuritiesAccount('SKR03', 2026, 'sale_costs_gain'); // null: DATEV keeps the costs of a sale only under § 8b
+getAccountsBySecuritiesRole('SKR03', 2026, 'sale_proceeds_fixed_gain').map((account) => account.accountNumber);
+// ['8838', '8839']: a Finanzanlage's sale stated gross, on the accounts of a fixed asset's disposal
+```
+
+| Role | What it books | SKR03 | SKR04 |
+| --- | --- | --- | --- |
+| `holding_fixed`, `holding_fixed_shares`, `holding_fixed_bonds` | Wertpapiere des Anlagevermögens (A.III.5) | 0525, 0530, 0535 | 0900, 0910, 0920 |
+| `holding_current` | Sonstige Wertpapiere (B.III.2) | 1348 | 1510 |
+| `income_fixed` / `income_current` | dividends, distributions, coupons (GuV 10 / 11) | 2620 (§ 8b 2625) / 2654 (§ 8b 2655) | 7010 (§ 8b 7014) / 7115 (§ 8b 7103) |
+| `sale_gain_current` / `sale_loss_current` | a current asset's sale, net (GuV 4 / 8) | 2725 (§ 8b 2726) / 2325 (§ 8b 2326) | 4905 (§ 8b 4906) / 6905 (§ 8b 6906) |
+| `sale_proceeds_fixed_*`, `book_value_fixed_*` | a Finanzanlage's sale, gross | 8838/8818, 2317/2312 (§ 8b 8839/8819, 2318/2313) | 4851/6891, 4857/6897 (§ 8b 4852/6892, 4858/6898) |
+| `sale_costs_gain` / `sale_costs_loss` | the costs of a sale under § 8b KStG | 4976 / 4977 | 6857 / 6858 |
+| `writedown_fixed_lasting`, `writedown_fixed_temporary`, `writedown_current` | write-downs (GuV 12) | 4870 (§ 8b 4871), 4866, 4875 (§ 8b 4876) | 7200 (§ 8b 7204), 7201, 7210 (§ 8b 7214) |
+| `writeup_fixed`, `writeup_current`, `writeup` | write-ups (GuV 4) | 2712, 2715, § 8b 2714 | 4912, 4915, § 8b 4914 |
+| `capital_gains_tax`, `capital_gains_tax_soli` | Kapitalertragsteuer and its Solidaritätszuschlag (GuV 14) | 2213, 2216 | 7630, 7633 |
+| `foreign_withholding_tax`, `foreign_tax_exempt_income` | foreign tax to credit or deduct; on income exempt at home (GuV 14) | 2219, 2218 | 7639, 7638 |
+| `foreign_tax_refund` | a foreign tax to be refunded (B.II.4) | 1542 | 1440 |
+| `margin_interest` | interest on a short-term debt (GuV 13) | 2110 | 7310 |
+| `borrow_fees` | interest-like expenses such as the fees of securities borrowed (GuV 13) | 2140 | 7330 |
+| `writedown_other_current` | a write-down of a current asset that is no security, usual amount: an option bought, a margin paid (GuV 8) | 4886 | 6910 |
+| `expected_loss_provision` | the provision for an expected loss from a pending transaction, a written option (B.3; HB) | 0976 | 3092 |
+| `provision_release` | the income of a provision released (GuV 4) | 2735 | 4930 |
+
+None of them carries a tax function or a UStVA figure. DATEV marks the provision
+for an expected loss "HB" (`commercialOnly`): it is posted in the commercial
+balance sheet only, as § 5 Abs. 4a EStG allows none in the tax balance sheet;
+so do the write-downs of a Finanzanlage for a decline that does not last (SKR03
+4866, SKR04 7201), which tax law allows only for a lasting one. In the Anlage EÜR the
+holdings are no part of the form (fixed assets reach it by their residual book
+value, current ones of § 4 Abs. 3 Satz 4 EStG by their cost when sold:
+`deferred_current_asset`); income and gains on sale are receipts free of VAT or
+not taxable for VAT (Kz 103), a loss on sale is cost at the sale (Kz 100), the costs of a
+sale other expenses (Kz 183), write-downs and write-ups values at a closing date
+(`valuation`), so are a provision and its release, the margin interest and
+interest-like expenses other debt interest (Kz 234), and the taxes on income a
+withdrawal (Kz 122, § 12 Nr. 3 EStG).
+
 ### Anlage EÜR
 
 Every account of a chart either maps to the Anlage EÜR or is excluded from it
@@ -112,7 +179,9 @@ getMappingCoverage('SKR04', 2026, usedAccountNumbers, 'euer').missing; // []
   `pass_through` (§ 4 Abs. 3 Satz 2 EStG), `reverse_charge` (the tax of an
   intra-Community acquisition or under § 13b UStG: such invoices contain no
   input tax, Anleitung zur Anlage EÜR, Zeile 58, and the tax is no receipt;
-  what a return leaves to pay counts as paid VAT, Kz 186) and `closing`.
+  what a return leaves to pay counts as paid VAT, Kz 186), `closing` and
+  `deferred_current_asset` (shares, securities, land and buildings held as
+  current assets, whose cost counts at their sale, § 4 Abs. 3 Satz 4 EStG).
 - A line's `sign` says how it enters its section's sum: 1 adds, -1 subtracts
   (Zeilen 73 and 75), 0 not at all (a "davon" line, the column "nicht
   abziehbar", the Entnahmen and Einlagen).

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@fin.cx/chartdata',
-  version: '2.14.0',
+  version: '2.16.0',
   description: 'Year-versioned German SKR03/SKR04 chart-of-accounts datasets with Automatikkonto functions, BU-key rules, UStVA-Kennzahl and Anlage EÜR mappings'
 }

package/ts/chartdata.lookup.ts

@@ -7,6 +7,8 @@ import type {
   TChartName,
   TEuerAccountLines,
   TMappingDimension,
+  TSecuritiesRole,
+  TTaxRule,
 } from './chartdata.types.js';
 import { euerLinesOf, type IEuerLinesOptions } from './chartdata.euer.js';
 import { SKR03_2026 } from './data/skr03.2026.js';
@@ -83,6 +85,34 @@ export function getAccountsByRole(
   return getChart(chart, year).accounts.filter((account) => account.accountRole === role);
 }
 
+/**
+ * The accounts of a chart with the securities role (`IChartAccount.securitiesRole`),
+ * in the chart's order: one without a tax rule and, where DATEV keeps one apart,
+ * one under § 3 Nr. 40 EStG / § 8b KStG. Throws for unknown chart/year
+ * combinations, as `getChart`.
+ */
+export function getAccountsBySecuritiesRole(
+  chart: TChartName,
+  year: number,
+  role: TSecuritiesRole,
+): IChartAccount[] {
+  return getChart(chart, year).accounts.filter((account) => account.securitiesRole === role);
+}
+
+/**
+ * The one account of a chart that books the securities role under the tax rule
+ * (`taxRule`; none: the account without one), or `null` where the chart keeps
+ * none for it. Throws for unknown chart/year combinations, as `getChart`.
+ */
+export function getSecuritiesAccount(
+  chart: TChartName,
+  year: number,
+  role: TSecuritiesRole,
+  taxRule?: TTaxRule,
+): IChartAccount | null {
+  return getAccountsBySecuritiesRole(chart, year, role).find((account) => account.taxRule === taxRule) ?? null;
+}
+
 function hasMapping(account: IChartAccount, dimension: TMappingDimension): boolean {
   switch (dimension) {
     case 'ustva':

package/ts/chartdata.types.ts

@@ -16,6 +16,96 @@ 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;
+ * - 'borrow_fees': interest-like expenses (zinsähnliche Aufwendungen), such as
+ *   the fees of securities borrowed for a short sale;
+ * - 'writedown_other_current': the write-down of a current asset that is
+ *   neither inventory nor a security, at the usual amount (an option bought,
+ *   a variation margin paid);
+ * - 'expected_loss_provision': the provision for an expected loss from a
+ *   pending transaction (§ 249 Abs. 1 HGB: a written option worth more than
+ *   its premium), which tax law does not allow (§ 5 Abs. 4a EStG);
+ * - 'provision_release': the income of a provision released.
+ */
+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'
+  | 'borrow_fees'
+  | 'writedown_other_current'
+  | 'expected_loss_provision'
+  | 'provision_release';
+
+/**
+ * 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).
@@ -69,7 +159,12 @@ export type TEuerMapping = { kennzahl: number } | { debitKennzahl: number; credi
  *   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.
+ *   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'
@@ -78,7 +173,8 @@ export type TEuerExclusion =
   | 'valuation'
   | 'pass_through'
   | 'reverse_charge'
-  | 'closing';
+  | 'closing'
+  | 'deferred_current_asset';
 
 /**
  * The part of the Anlage EÜR a line belongs to: Betriebseinnahmen (Zeilen
@@ -137,6 +233,15 @@ 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;
+  /**
+   * DATEV's mark "HB": the account is posted in the commercial balance sheet only (Handelsbilanz), its amounts
+   * are no part of the tax balance sheet; unset = both
+   */
+  commercialOnly?: true;
   description?: string;
   automatikFunction?: TAutomatikFunction;
   /** BU keys allowed on lines of this account ('' = none). Unset = all. */