@opencxh/domain 1.287.0 → 1.290.0

package/dist/entities/financing/types.d.ts

@@ -0,0 +1,135 @@
+import { Cents } from '../money/money';
+/**
+ * Balance items with detail under a ledger account (plan 039 §3.6b, datamodel §5): loans, the
+ * director's current account, participations and deposits. One row per item; `kind` says which
+ * terms it has. Bank accounts live apart (`BankAccount`): they hold statement lines, these hold a
+ * schedule.
+ */
+export type FinancingKind = "loan_received" | "loan_given" | "current_account" | "participation" | "deposit_paid" | "fixed_asset" | "accrual";
+export interface LoanTerms {
+    kind: "loan_received" | "loan_given";
+    principalCents: Cents;
+    /** Yearly, as a decimal string: `"4.5"`. */
+    ratePercent: string;
+    method: "annuity" | "linear" | "bullet";
+    termMonths: number;
+    /** The first instalment. Later ones fall on the same day of the month. */
+    firstDueOn: string;
+    /** Interest expense (received) or income (given). */
+    interestAccountId: string;
+}
+export interface CurrentAccountTerms {
+    kind: "current_account";
+    /** A business rate: what the tax authority expects between a BV and its director. */
+    ratePercent: string;
+    cadence: "quarterly" | "yearly";
+    /** Interest income when the director owes, expense when the BV owes. */
+    interestIncomeAccountId: string;
+    interestExpenseAccountId: string;
+    /** Wet excessief lenen: a signal above this debt of the director. A setting, default € 500.000. */
+    thresholdCents?: Cents;
+}
+export interface ParticipationTerms {
+    kind: "participation";
+    /** History of the stake: a change adds a row, nothing is overwritten. */
+    stakes: {
+        from: string;
+        percent: string;
+        shares?: number;
+    }[];
+    acquisitionCents: Cents;
+    valuation: "cost" | "net_asset_value";
+    /** Proposed at a stake of 5% or more; a person confirms it. */
+    participationExemption: boolean;
+    dividendAccountId?: string;
+}
+export interface DepositTerms {
+    kind: "deposit_paid";
+    refundableOn?: string;
+}
+/**
+ * A fixed asset, depreciated straight-line per month from the month it was acquired. The item
+ * sits under the cost account; depreciation lands on the accumulated-depreciation account, so the
+ * annual accounts show cost and accumulated apart. Acquisition itself is booked by its invoice.
+ */
+export interface FixedAssetTerms {
+    kind: "fixed_asset";
+    acquiredOn: string;
+    costCents: Cents;
+    residualCents: Cents;
+    lifeMonths: number;
+    /** Expense: `Afschrijving inventaris`. */
+    depreciationAccountId: string;
+    /** Contra-asset: `Afschrijving inventaris` under the fixed assets. */
+    accumulatedAccountId: string;
+}
+/**
+ * An amount spread over months (transitoria): prepaid insurance released to costs, revenue
+ * invoiced ahead released to revenue, costs accrued before their invoice. `expense` debits the
+ * result account and credits the item's balance account each month; `revenue` the other way.
+ * `upfront`: the whole amount was booked on the balance account first (prepaid, invoiced
+ * ahead), so the item starts at it and runs down; otherwise it builds up (accrued).
+ */
+export interface AccrualTerms {
+    kind: "accrual";
+    direction: "expense" | "revenue";
+    totalCents: Cents;
+    /** The first month released, as its first day. */
+    firstMonth: string;
+    months: number;
+    resultAccountId: string;
+    upfront: boolean;
+}
+export type FinancingTerms = LoanTerms | CurrentAccountTerms | ParticipationTerms | DepositTerms | FixedAssetTerms | AccrualTerms;
+export interface FinancingItem {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    kind: FinancingKind;
+    /** `"Lening Rabobank 2026"`, `"Rekening-courant J. de Vries"`. */
+    name: string;
+    /** The ledger account it sits under; its lines carry this item as `subAccountId`. */
+    ledgerAccountId: string;
+    /** The other party: a crm company (bank, participation, landlord) or a person by name (the director). */
+    counterpartyCompanyId?: string;
+    counterpartyName?: string;
+    currency: string;
+    terms: FinancingTerms;
+    openedOn?: string;
+    closedOn?: string;
+    archived?: boolean;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * A prepared posting from an item's schedule (datamodel §5.2): an instalment, a quarter's
+ * interest. One per (item, sequence), so a repeated run makes no twin.
+ */
+export interface ScheduledPosting {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    financingItemId: string;
+    sequence: number;
+    dueOn: string;
+    /**
+     * The lines as they become an entry. For `bank_line` these are the non-bank side only: the bank
+     * line that pays it adds its own side. Their sum is what the bank line must be, signed.
+     */
+    lines: {
+        accountId: string;
+        amountCents: Cents;
+        subAccountId?: string;
+        description?: string;
+    }[];
+    /** What the bank line should show: − for an instalment paid, + for one received. */
+    expectedBankCents: Cents;
+    /** planned: in the future · due: today or earlier · posted · skipped (by a person, with a reason). */
+    status: "planned" | "due" | "posted" | "skipped";
+    /** Paid through a bank line (an instalment) or posted by itself when due (interest on a balance). */
+    settlesVia: "bank_line" | "direct";
+    entryId?: string;
+    skipReason?: string;
+    /** For the list: `"Termijn 21"`, `"Rente Q3"`. */
+    label: string;
+}

package/dist/entities/ledger/closing.d.ts

@@ -0,0 +1,18 @@
+import { Cents } from '../money/money';
+import { ReportLine } from '../reports/reports';
+import { JournalLineData, LedgerAccount } from './types';
+/**
+ * The year-end closing entry: every result account's movement over the year back to zero, the
+ * balance onto the equity result account (plan 039 §3.8). The P&L of a closed year leaves this
+ * entry out, so it still shows the year; the balance sees the result where it now sits.
+ */
+export declare function yearEndClosingLines(input: {
+    accounts: readonly LedgerAccount[];
+    /** The year's lines only. */
+    lines: readonly ReportLine[];
+    resultAccountId: string;
+    currency: string;
+}): {
+    lines: JournalLineData[];
+    resultCents: Cents;
+};

package/dist/entities/ledger/closing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/ledger/entry.d.ts

@@ -0,0 +1,83 @@
+import { BookingDocument } from '../../platform/bookkeeping';
+import { FiscalPeriod, JournalEntry, JournalKind, JournalLineData, LedgerAccount, PostingRule, TaxAccountMapping } from './types';
+export type EntryProblem = {
+    code: "entry_unbalanced";
+    params: {
+        cents: string;
+    };
+} | {
+    code: "entry_too_few_lines";
+} | {
+    code: "entry_unknown_account";
+    params: {
+        account: string;
+    };
+} | {
+    code: "entry_account_archived";
+    params: {
+        account: string;
+    };
+} | {
+    code: "entry_sub_account_required";
+    params: {
+        account: string;
+    };
+} | {
+    code: "entry_no_period";
+    params: {
+        day: string;
+    };
+} | {
+    code: "entry_period_closed";
+    params: {
+        day: string;
+    };
+};
+/** Everything that stops an entry, checked in memory before the insert (plan 039 §4.4 step 1). */
+export declare function entryProblems(entry: {
+    date: string;
+    lines: readonly JournalLineData[];
+}, context: {
+    accounts: readonly LedgerAccount[];
+    period?: Pick<FiscalPeriod, "status">;
+    /**
+     * `closed`: into a closed period too (the accountant, later). `locked`: into any, for the
+     * year end only — its lines carry no VAT, so a period locked by a VAT return stays true.
+     */
+    allow?: "closed" | "locked";
+}): EntryProblem[];
+/** `"MEM-2026-0042"`. A split year numbers under the year it starts in. */
+export declare function entryNumber(journalCode: string, fiscalYear: string, seq: number): string;
+/** The fields the hash covers: everything that says what was booked, where, by whom, after what. */
+export type HashedEntry = Omit<JournalEntry, "id" | "organizationId" | "hash" | "createdAt">;
+export declare function hashedPartOf(entry: JournalEntry | HashedEntry): HashedEntry;
+/**
+ * Canonical JSON: keys sorted at every depth, `undefined` dropped. The same entry always gives the
+ * same string, so a re-computed hash only differs when something was changed.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** A reversal: the same lines, every amount the other way. */
+export declare function reversedLines(lines: readonly JournalLineData[]): JournalLineData[];
+export interface DocumentPostingContext {
+    accounts: readonly LedgerAccount[];
+    rules: readonly PostingRule[];
+    taxAccounts: readonly TaxAccountMapping[];
+}
+export type DocumentEntry = {
+    ok: true;
+    journalKind: JournalKind;
+    lines: JournalLineData[];
+    description: string;
+} | {
+    ok: false;
+    problem: string;
+};
+/**
+ * A sale or a purchase as balanced lines (plan 039 §4.6). A sale: debtors debit the gross, revenue
+ * credit per line, VAT payable credit per code. A purchase the mirror, on creditors and VAT to
+ * reclaim. A credit note needs nothing of its own: its amounts are already negative.
+ *
+ * ponytail: a reverse-charge purchase books no self-assessed VAT yet (both sides of box 4); the
+ * VAT return in step 7 adds it.
+ */
+export declare function entryLinesOf(doc: BookingDocument, context: DocumentPostingContext): DocumentEntry;

package/dist/entities/ledger/index.d.ts

@@ -0,0 +1,6 @@
+export * from './closing';
+export * from './entry';
+export * from './periods';
+export * from './template';
+export * from './types';
+export * from './xaf';

package/dist/entities/ledger/ledger.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/ledger/periods.d.ts

@@ -0,0 +1,9 @@
+import { FiscalPeriod } from './types';
+/**
+ * The twelve monthly periods of the fiscal year that starts in `startMonth` (1-12) of `year`.
+ * Periods are rows, not derived from the calendar: a 4-4-5 year or a thirteenth period is a
+ * different list, not a different rule (plan 039 §4.1 #6).
+ */
+export declare function monthlyPeriods(year: number, startMonth?: number): Pick<FiscalPeriod, "fiscalYear" | "index" | "from" | "to" | "status">[];
+/** The period a day falls in, or `undefined`: a day outside every year cannot be posted. */
+export declare function periodOf<P extends Pick<FiscalPeriod, "from" | "to">>(periods: readonly P[], day: string): P | undefined;

package/dist/entities/ledger/template.d.ts

@@ -0,0 +1,35 @@
+import { JournalKind, LedgerAccountRole, LedgerAccountType } from './types';
+/**
+ * A chart of accounts to start from, as data (plan 039 datamodel §4.1): copied into an
+ * administration when it is set up, never read again after, so changing it touches no one.
+ */
+export interface TemplateAccount {
+    code: string;
+    name: string;
+    type: LedgerAccountType;
+    reportGroup: string;
+    /** RGS reference code (level 4, an account), from the official list of the version below. */
+    rgs: string;
+    role?: LedgerAccountRole;
+    requiresSubAccount?: boolean;
+}
+export interface LedgerTemplate {
+    key: string;
+    label: string;
+    /** The RGS version the codes come from: `"3.5"`. An XAF export states it. */
+    rgsVersion: string;
+    accounts: TemplateAccount[];
+    journals: {
+        code: string;
+        name: string;
+        kind: JournalKind;
+    }[];
+}
+/**
+ * A BV's chart, each account on its RGS 3.5 reference code (Def-versie RGS 3.5_2,
+ * referentiegrootboekschema.nl). Names follow the code they carry: "Omzet diensten laag" and not
+ * "Omzet laag", because the code says services at the low rate and a report grouped by RGS must
+ * mean what the name says.
+ */
+export declare const NL_BV_TEMPLATE: LedgerTemplate;
+export declare const LEDGER_TEMPLATES: readonly LedgerTemplate[];

package/dist/entities/ledger/types.d.ts

@@ -0,0 +1,178 @@
+import { BookingDocument } from '../../platform/bookkeeping';
+import { Cents } from '../money/money';
+/**
+ * Our own books (plan 039 datamodel §4). One row per posting with its lines as a column, a hash
+ * chain and gapless numbers guarded by unique indexes, and a line table that is only ever derived.
+ */
+export type LedgerAccountType = "asset" | "liability" | "equity" | "revenue" | "expense";
+export interface LedgerAccount {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    /** `"1100"`, unique per administration. */
+    code: string;
+    name: string;
+    type: LedgerAccountType;
+    /** Mapping onto reporting taxonomies, apart from the own chart. RGS first. */
+    taxonomy?: {
+        rgs?: string;
+    };
+    /** Accounts with detail (bank, loan, current account) require a `subAccountId` on every line. */
+    requiresSubAccount?: boolean;
+    /** Where it sits in the reports: `"revenue.net"`, `"costs.office"`. The reports are not hard-coded. */
+    reportGroup?: string;
+    order?: number;
+    /** What a control account is for, so a posting rule can find it: debtors, creditors, VAT. */
+    role?: LedgerAccountRole;
+    /** Never deleted: a posted line points at it. */
+    archived?: boolean;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export type LedgerAccountRole = "debtors" | "creditors" | "vat_payable" | "vat_receivable" | "revenue_default" | "expense_default" | "suspense" | "result";
+export type JournalKind = "sales" | "purchase" | "bank" | "cash" | "memorial" | "opening";
+export interface Journal {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    /** `"VK"`, `"IK"`, `"MEM"`: also the number prefix. */
+    code: string;
+    name: string;
+    kind: JournalKind;
+    /** A bank or cash journal belongs to one sub-account (the bank account). */
+    subAccountId?: string;
+    archived?: boolean;
+}
+export interface FiscalPeriod {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    /** `"2026"`, or `"2026/2027"` for a year that does not start in January. */
+    fiscalYear: string;
+    /** 1..12 (or 13). */
+    index: number;
+    from: string;
+    to: string;
+    /** open: post freely. closed: accountant only. locked: nobody (after a VAT return or year end). */
+    status: "open" | "closed" | "locked";
+}
+/**
+ * A closed fiscal year: the closing entry that moved its result to equity, the loans' short-term
+ * reclassification (and its reversal on the first day after), and who closed it. One per year;
+ * its periods are locked after.
+ */
+export interface YearEnd {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    fiscalYear: string;
+    from: string;
+    to: string;
+    closingEntryId?: string;
+    reclassEntryIds: string[];
+    /** Credit positive: a profit. */
+    resultCents: Cents;
+    closedAt: number;
+    closedBy: string;
+}
+/** A line as it sits in `JournalEntry.lines`. Debit positive, credit negative; the sum is zero. */
+export interface JournalLineData {
+    accountId: string;
+    amountCents: Cents;
+    currency: string;
+    fxRate?: string;
+    functionalCents: Cents;
+    /** `TaxCode.key`, the VAT of this line, and when it counts. */
+    taxCode?: string;
+    taxCents?: Cents;
+    taxPointDate?: string;
+    subAccountId?: string;
+    costCenter?: string;
+    /** A work project as cost carrier. */
+    projectId?: string;
+    counterpartyCompanyId?: string;
+    dimensions?: Record<string, string>;
+    description?: string;
+}
+export interface JournalEntry {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    journalId: string;
+    /** `"MEM-2026-0042"`: journal code, fiscal year, `journalSeq`. Set in the same insert. */
+    number: string;
+    /** The per-journal, per-year sequence behind `number`. Unique with journal and year. */
+    journalSeq: number;
+    fiscalYear: string;
+    /** Position in this administration's hash chain: 1, 2, 3 … without gaps. Unique. */
+    chainSeq: number;
+    date: string;
+    periodId: string;
+    description: string;
+    /**
+     * Where it came from, flat and never empty, unique: `sales:<id>`, `finance:<id>`,
+     * `manual:<uuid>`. The same source cannot be posted twice.
+     */
+    sourceKey: string;
+    /** `number`: the source document's own number, so a bank line can be matched on it. */
+    source: {
+        app: string;
+        documentId?: string;
+        kind?: string;
+        number?: string;
+        dueOn?: string;
+    };
+    lines: JournalLineData[];
+    /** The entry this one reverses. The reversed entry itself is never changed. */
+    reversesEntryId?: string;
+    attachment?: {
+        mountId: string;
+        fileId: string;
+    };
+    /** sha256(prevHash + canonical JSON of the entry). */
+    hash: string;
+    /** `"genesis"` at chainSeq 1. */
+    prevHash: string;
+    postedAt: number;
+    postedBy: string;
+    createdAt?: number;
+}
+/** The derived line table: one row per line, for reports and the account card. Never written by hand. */
+export interface JournalLine extends JournalLineData {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    entryId: string;
+    /** Unique with `entryId`: a repeated projection makes no twin. */
+    lineIndex: number;
+    date: string;
+    periodId: string;
+    journalId: string;
+}
+/** How a `BookingDocument` becomes an entry. First match wins, in the order of the mapping. */
+export interface PostingRule {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    appliesTo: {
+        direction: "sale" | "purchase";
+        kind?: BookingDocument["kind"];
+    };
+    match: {
+        productId?: string;
+        ledgerCategoryKey?: string;
+        taxRateKey?: string;
+    };
+    /** Revenue or expense account for the net line. */
+    accountId: string;
+    order: number;
+}
+/** Which account the VAT of a key lands on. Missing = the account with the VAT role. */
+export interface TaxAccountMapping {
+    id: string;
+    organizationId: string;
+    businessEntityId: string;
+    taxKey: string;
+    payableAccountId?: string;
+    receivableAccountId?: string;
+}

package/dist/entities/ledger/xaf.d.ts

@@ -0,0 +1,82 @@
+import { Cents } from '../money/money';
+import { FiscalPeriod, Journal, JournalEntry, LedgerAccount } from './types';
+/**
+ * The XML Auditfile Financieel 4.0 (Belastingdienst, XAF v4.0.3): one fiscal year of the books
+ * as the tax authority and the accountant read it. A projection, built with string concatenation
+ * (it may run on the QuickJS server), and a scanner that reads a package's XAF (3.x or 4.0) back
+ * for the opening balance.
+ */
+export declare const XAF_NAMESPACE = "http://www.odb.belastingdienst.nl/Belastingdienst/BCPP/1.1/structures/XmlauditfileXAF_4.0";
+export interface XafInput {
+    fiscalYear: string;
+    startDate: string;
+    endDate: string;
+    currency: string;
+    createdOn: string;
+    software: {
+        desc: string;
+        version: string;
+    };
+    rgsVersion?: string;
+    company: {
+        name: string;
+        commerceNr?: string;
+        country: string;
+        vatNumber?: string;
+        address?: {
+            street?: string;
+            number?: string;
+            city?: string;
+            postalCode?: string;
+        };
+    };
+    relations: {
+        id: string;
+        name: string;
+        commerceNr?: string;
+        vatNumber?: string;
+        country?: string;
+        type?: "C" | "S" | "B";
+    }[];
+    accounts: readonly LedgerAccount[];
+    taxCodes: {
+        key: string;
+        label: string;
+        payableAccountId?: string;
+        receivableAccountId?: string;
+    }[];
+    periods: readonly Pick<FiscalPeriod, "id" | "index" | "from" | "to">[];
+    /** Balance positions at the start of the year, debit positive. */
+    opening: {
+        accountId: string;
+        cents: Cents;
+    }[];
+    journals: readonly Journal[];
+    entries: readonly JournalEntry[];
+    /** The VAT percentage of a code on a day, when known; a line without it carries no vat block. */
+    vatPercent?: (taxCode: string, day: string) => string | undefined;
+}
+export declare function xafAuditfile(input: XafInput): string;
+export interface XafOpening {
+    fiscalYear?: string;
+    endDate?: string;
+    accounts: {
+        code: string;
+        name: string;
+        kind: "B" | "P";
+        rgs?: string;
+    }[];
+    /** Per account code, where it stood at the end of the file's year: debit positive. */
+    closing: Record<string, Cents>;
+}
+/**
+ * What a moving administration needs from its old package: the chart and where every account
+ * stood at the end of the year. Opening balance plus every transaction line; XAF 3.2 (`leadCode`)
+ * and 4.0 (`RGScode`) both read.
+ */
+export declare function parseXafOpening(xml: string): XafOpening;
+/** An account's type from its RGS code, else from the side it stands on. */
+export declare function accountTypeOf(account: {
+    kind: "B" | "P";
+    rgs?: string;
+}, cents: Cents): LedgerAccount["type"];

package/dist/entities/money/tax.d.ts

@@ -40,3 +40,65 @@ export declare const NL_TAX_RATES: readonly TaxRate[];
  * can open.
  */
 export declare function taxRateFor(key: string, rates: readonly TaxRate[]): TaxRate;
+/**
+ * A VAT code with its rate over time: the table `apps/organization` owns (plan 039 §2.5).
+ *
+ * The key is the same key a line carries (`taxRateKey`), so every existing line stays valid. A
+ * rate change adds a period instead of overwriting the percent — a December invoice keeps 9% when
+ * January brings 21%.
+ */
+export interface TaxCode {
+    key: string;
+    /** Empty = every administration; an administration's own row shadows the shared one. */
+    businessEntityId?: string;
+    /** i18n key, not text. */
+    label: string;
+    kind: TaxRateKind;
+    /** Purchase-only codes (input VAT) never show up in a sales select. */
+    direction: "sales" | "purchase" | "both";
+    /** Non-overlapping, ascending. `validTo` is inclusive and absent on the current period. */
+    rates: TaxCodeRate[];
+    /** Return boxes per taxonomy and side: `{ "nl-ob": { sales: { base: "1a", tax: "1a" } } }`. */
+    boxes: Record<string, {
+        sales?: TaxBoxes;
+        purchase?: TaxBoxes;
+    }>;
+    /** Reverse charge on purchase: the VAT is both owed and deductible. */
+    selfAssessed?: boolean;
+    /** Counts in the EC sales list (ICP). */
+    icp?: boolean;
+    /** Deductible share of input VAT, mixed use. Absent = 100. */
+    deductiblePercent?: number;
+    archived?: boolean;
+    order?: number;
+}
+export interface TaxCodeRate {
+    /** `"2019-01-01"`. Days, compared as strings. */
+    validFrom: string;
+    validTo?: string;
+    /** Whole percent as written on the invoice. */
+    percent: number;
+}
+export interface TaxBoxes {
+    base?: string;
+    tax?: string;
+}
+/**
+ * The Dutch codes an organisation starts with. Rubrieken per the aangifte omzetbelasting:
+ * zero-rated and reverse-charged supplies report their base in 1e; exempt supplies are not reported.
+ */
+export declare const NL_TAX_CODES: readonly TaxCode[];
+/** The percent that applied on `date`. No period covering it → 0, the safe direction as in {@link taxRateFor}. */
+export declare function taxPercentOn(code: TaxCode, date: string): number;
+/**
+ * The codes as flat rates on one day — the shape totals and paper already compute with. A
+ * {@link TaxRate} is "a code resolved on a date", so nothing downstream needs to know about periods.
+ */
+export declare function taxRatesOn(codes: readonly TaxCode[], date: string, direction?: "sales" | "purchase"): TaxRate[];
+/** Today as a VAT date, `"2026-09-26"`. The caller passes the tax point when it has one. */
+export declare function taxDateOf(epochMs: number): string;
+/**
+ * What is wrong with a code about to be saved, as an error code (`error_<code>` in the app's
+ * translations), or `null`. Periods must be valid days, 0–100%, ascending and not overlapping.
+ */
+export declare function taxCodeProblem(code: Partial<TaxCode>): string | null;

package/dist/entities/money/tax.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/entities/reports/index.d.ts

@@ -0,0 +1,2 @@
+export * from './reports';
+export * from './vat';