@fin.cx/chartdata 2.16.0 → 3.0.0

package/ts/chartdata.types.ts

@@ -59,6 +59,23 @@ export type TAccountRole = 'asset_sale_proceeds' | 'disposal_book_value';
  *   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.
+ * The roles DATEV's standard charts hold no account of their own for: the
+ * books book them on the account of their position, or on an individual
+ * account (`IIndividualAccountDeclaration`) where they keep them apart;
+ * `INDIVIDUAL_ACCOUNT_TEMPLATES` suggests the parent of the results the law
+ * keeps apart:
+ * - balances: 'options_held' (options bought, at their premium),
+ *   'variation_margin_paid' and 'variation_margin_received' (a future's or a
+ *   CFD's daily settlement held until it closes), 'accrued_interest_claim'
+ *   (Stückzinsen paid, interest accrued), 'lending_claim' (securities lent:
+ *   the claim to their return), 'written_options' (a writer's obligation at
+ *   the premium received), 'short_sale_obligations' (securities owed after a
+ *   short sale), 'collateral_received' (cash collateral to give back);
+ * - results kept apart: 'termingeschaeft_gain' and 'termingeschaeft_loss'
+ *   (§ 15 Abs. 4 Satz 3 EStG offsets the losses only against such gains),
+ *   'stillhalter_income' (a writer's premium earned), 'short_sale_gain' and
+ *   'short_sale_loss', 'compensation_paid' (payments in place of a dividend
+ *   on securities sold short).
  */
 export type TSecuritiesRole =
   | 'holding_fixed'
@@ -90,7 +107,96 @@ export type TSecuritiesRole =
   | 'borrow_fees'
   | 'writedown_other_current'
   | 'expected_loss_provision'
-  | 'provision_release';
+  | 'provision_release'
+  | 'options_held'
+  | 'variation_margin_paid'
+  | 'variation_margin_received'
+  | 'accrued_interest_claim'
+  | 'lending_claim'
+  | 'written_options'
+  | 'short_sale_obligations'
+  | 'collateral_received'
+  | 'termingeschaeft_gain'
+  | 'termingeschaeft_loss'
+  | 'stillhalter_income'
+  | 'short_sale_gain'
+  | 'short_sale_loss'
+  | 'compensation_paid';
+
+/**
+ * What an account books of a business's payroll: the pay and the employer's
+ * costs of it, the pay's taxes and contributions the business owes until it
+ * pays them, and what a payroll leaves to clear. A payroll run finds its
+ * account by this role: within a chart, no two accounts share one, and every
+ * role has its account in both standard charts (DATEV Kontenrahmen SKR 03
+ * Art.-Nr. 11174, pp. 8, 10, 11, 17, 22, 27, and SKR 04 Art.-Nr. 11175,
+ * pp. 4, 13, 18, 21, 22, gültig für 2026). DATEV's collective accounts
+ * ("Löhne und Gehälter", "Soziale Abgaben und Aufwendungen für
+ * Altersversorgung") take no role.
+ *
+ * The pay, under the wages and salaries (§ 275 Abs. 2 Nr. 6 a HGB, `GuV 6a`):
+ * - 'wages' (Löhne), 'salaries' (Gehälter), 'managing_director_salaries' (a
+ *   GmbH's shareholder-managing directors), 'temporary_wages'
+ *   (Aushilfslöhne), 'minijob_wages' (Löhne für Minijobs);
+ * - 'benefits_in_kind' (Sachzuwendungen und Dienstleistungen an
+ *   Arbeitnehmer), 'capital_formation_benefits' (vermögenswirksame
+ *   Leistungen), 'commuting_allowances' (Fahrtkostenerstattung Wohnung/
+ *   Arbeitsstätte);
+ * - the flat wage tax the employer bears: 'minijob_flat_tax',
+ *   'employee_flat_tax', 'temporary_flat_tax'.
+ *
+ * The employer's contributions, under the social security and pensions
+ * (Nr. 6 b, `GuV 6b`): 'employer_social_security' (gesetzliche soziale
+ * Aufwendungen: the employer's share and the levies U1, U2 and U3),
+ * 'minijob_social_security' (the flat contributions for a Minijob),
+ * 'accident_insurance' (Berufsgenossenschaft), 'pension' (Aufwendungen für
+ * Altersversorgung) and 'pension_flat_tax' (the flat tax on such benefits,
+ * Direktversicherungen).
+ *
+ * What a payroll earns, under the other operating income (Nr. 4, `GuV 4`):
+ * 'company_car_benefit' (the private use of a company car as a supply to the
+ * employee, with 19 % VAT) and 'levy_refunds' (Erstattungen nach dem
+ * Aufwendungsausgleichsgesetz, the sick-pay and maternity refunds of U1 and
+ * U2); 'levy_refund_claims' is the claim on the health insurer until it pays.
+ *
+ * What the business owes (§ 266 Abs. 3 C.8 HGB): 'net_pay' (Verbindlichkeiten
+ * aus Lohn und Gehalt), 'wage_tax' (Lohn- und Kirchensteuer, with the
+ * Solidaritätszuschlag), 'social_security' (the contributions of both sides
+ * and the levies), 'employee_withholdings' (what is withheld from an employee
+ * for another, such as a garnishment), 'capital_formation_payable' (the
+ * savings an employee's contract receives), 'estimated_contributions' (the
+ * contributions estimated in the month they are due, § 23 Abs. 1 SGB IV);
+ * and 'clearing', the Lohn- und Gehaltsverrechnungskonto, a balance on
+ * either side (DATEV states it under the other assets or the other
+ * liabilities by its balance).
+ */
+export type TPayrollRole =
+  | 'wages'
+  | 'salaries'
+  | 'managing_director_salaries'
+  | 'temporary_wages'
+  | 'minijob_wages'
+  | 'benefits_in_kind'
+  | 'capital_formation_benefits'
+  | 'commuting_allowances'
+  | 'minijob_flat_tax'
+  | 'employee_flat_tax'
+  | 'temporary_flat_tax'
+  | 'employer_social_security'
+  | 'minijob_social_security'
+  | 'accident_insurance'
+  | 'pension'
+  | 'pension_flat_tax'
+  | 'company_car_benefit'
+  | 'levy_refunds'
+  | 'levy_refund_claims'
+  | 'net_pay'
+  | 'wage_tax'
+  | 'social_security'
+  | 'employee_withholdings'
+  | 'capital_formation_payable'
+  | 'estimated_contributions'
+  | 'clearing';
 
 /**
  * A rule of the income tax law an income or expense account is kept for, as
@@ -235,6 +341,8 @@ export interface IChartAccount {
   accountRole?: TAccountRole;
   /** what the account books of a business's securities; unset = nothing of its own */
   securitiesRole?: TSecuritiesRole;
+  /** what the account books of a business's payroll; unset = nothing of its own */
+  payrollRole?: TPayrollRole;
   /** the income tax rule the account is kept for, as its DATEV name states it; unset = none of its own */
   taxRule?: TTaxRule;
   /**
@@ -242,6 +350,8 @@ export interface IChartAccount {
    * are no part of the tax balance sheet; unset = both
    */
   commercialOnly?: true;
+  /** an individual account of the books (`IIndividualAccountDeclaration`): the DATEV account it belongs to; unset = a DATEV account */
+  parentAccountNumber?: string;
   description?: string;
   automatikFunction?: TAutomatikFunction;
   /** BU keys allowed on lines of this account ('' = none). Unset = all. */
@@ -307,3 +417,91 @@ export interface IScenarioKennzahlen {
   inputVatReverseCharge: number; // Kz 67 (Vorsteuer §13b)
   importVat: number; // Kz 62 (entrichtete EUSt)
 }
+
+/** The numbers a DATEV standard chart of a year assigns (listed accounts and headings), and of them those it reserves ("R"). */
+export interface IDatevNumbers {
+  chart: TChartName;
+  year: number;
+  assigned: readonly string[];
+  reserved: readonly string[];
+}
+
+/**
+ * What an individual account changes deliberately of what it inherits from its parent: a value replaces the
+ * parent's, `null` drops it. The Anlage EÜR takes `euer` or `euerExclusion`, not both.
+ */
+export interface IIndividualAccountOverrides {
+  hgb266Position?: string | null;
+  hgb275Position?: string | null;
+  ustva?: IUstvaMapping | null;
+  euer?: TEuerMapping;
+  euerExclusion?: TEuerExclusion;
+  accountRole?: TAccountRole | null;
+  taxRule?: TTaxRule | null;
+  commercialOnly?: true | null;
+}
+
+/**
+ * An account the books set up themselves (an Individualkonto) on a number the DATEV standard chart leaves free,
+ * belonging to one of its accounts (the parent, `parentAccountNumber`): it is what its parent is — its type, its
+ * balance-sheet or income-statement position, its UStVA and Anlage EÜR mapping, its account role, its tax rule
+ * and DATEV's mark "HB" — unless `overrides` changes one deliberately. It does not take the parent's DATEV tax
+ * automatism (DATEV applies one only to the accounts it marks) nor its securities role, which names one account of
+ * a chart: an individual account takes one only where its declaration names it. The declarations are the books';
+ * chartdata stores none.
+ */
+export interface IIndividualAccountDeclaration {
+  accountNumber: string;
+  accountName: string;
+  parentAccountNumber: string;
+  securitiesRole?: TSecuritiesRole;
+  overrides?: IIndividualAccountOverrides;
+}
+
+/**
+ * Why an individual account cannot be:
+ * - `number_invalid`: its number is no four digits;
+ * - `number_assigned`: DATEV assigns or reserves the number in the chart of the year;
+ * - `number_duplicate`: two declarations take the number;
+ * - `name_missing`: the account has no name;
+ * - `parent_unknown`: the chart holds no account of the parent's number;
+ * - `parent_individual`: the parent is itself an individual account;
+ * - `parent_not_allowed`: the parent is a carry-forward, closing or statistical account, which records no business
+ *   transaction;
+ * - `class_mismatch`: the number lies in another account class (its first digit) than the parent;
+ * - `not_following_parent`: the number does not follow its parent: an account of the chart stands between them.
+ *   DATEV leaves the free numbers after an account for its individual accounts and passes the account's marks for
+ *   the trade and corporate income tax programs ("G", "K") on to them, up to the next account of the standard chart
+ *   (DATEV Kontenrahmen SKR 03 and SKR 04, gültig für 2026, Erläuterungen, S. 37), so an individual account
+ *   elsewhere would be another account's in DATEV's tax programs;
+ * - `role_taken`: another account of the chart books the securities role under the same tax rule;
+ * - `override_invalid`: an override names no balance-sheet position of § 266 HGB, no income-statement position of
+ *   § 275 HGB, or one the account's type does not take (a balance-sheet account has a balance-sheet position, a
+ *   profit-and-loss account an income-statement position); an Anlage EÜR line no form year holds, a split line on
+ *   the other side; or both a line and an exclusion.
+ */
+export type TIndividualAccountProblemCode =
+  | 'number_invalid'
+  | 'number_assigned'
+  | 'number_duplicate'
+  | 'name_missing'
+  | 'parent_unknown'
+  | 'parent_individual'
+  | 'parent_not_allowed'
+  | 'class_mismatch'
+  | 'not_following_parent'
+  | 'role_taken'
+  | 'override_invalid';
+
+export interface IIndividualAccountProblem {
+  accountNumber: string;
+  code: TIndividualAccountProblemCode;
+  message: string;
+}
+
+/** A suggestion for an individual account the books need for a securities role: the parent it belongs to and a name. */
+export interface IIndividualAccountTemplate {
+  securitiesRole: TSecuritiesRole;
+  parentAccountNumber: string;
+  accountName: string;
+}