@opencxh/domain 1.287.0 → 1.290.0

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

@@ -0,0 +1,90 @@
+import { LedgerAccount } from '../ledger/types';
+import { Cents } from '../money/money';
+/**
+ * The reports, from posted lines and the chart (plan 039 §3.7). One shape for our own books and
+ * for a connected package's (Jortt's `reports/*`), so a screen never knows which books it reads.
+ */
+/** One row of a report: a section, a group or an account, with the side its amount stands on. */
+export interface BooksReportRow {
+    key: string;
+    label: string;
+    /** 0 = section, 1 = group, 2 = account. */
+    level: number;
+    side: "debit" | "credit";
+    /** Never negative on its own side; a position on the other side is negative. */
+    amountCents: Cents;
+    accountId?: string;
+}
+export interface BooksReport {
+    kind: "profit_and_loss" | "balance";
+    from: string;
+    to: string;
+    rows: BooksReportRow[];
+    /** P&L: the result (credit = profit). Balance: total assets and total liabilities + equity. */
+    totals: {
+        resultCents?: Cents;
+        debitCents?: Cents;
+        creditCents?: Cents;
+    };
+    /** Where the figures come from: our books, or a connected package by name. */
+    source: string;
+}
+/** A posted line as the reports need it: account, day, signed amount (debit +). */
+export interface ReportLine {
+    accountId: string;
+    date: string;
+    functionalCents: Cents;
+}
+export interface AccountTotals {
+    accountId: string;
+    openingCents: Cents;
+    debitCents: Cents;
+    creditCents: Cents;
+    closingCents: Cents;
+}
+/** Per account: what stood before `from`, what moved up to `to`, and what stands after. */
+export declare function accountTotals(lines: readonly ReportLine[], from: string, to: string): Map<string, AccountTotals>;
+export declare const isResultAccount: (account: Pick<LedgerAccount, "type">) => boolean;
+/** Profit and loss over a window: what moved on the result accounts, revenue credit, costs debit. */
+export declare function profitAndLoss(accounts: readonly LedgerAccount[], totals: Map<string, AccountTotals>, window: {
+    from: string;
+    to: string;
+}, labelOf?: (key: string) => string): BooksReport;
+/**
+ * The balance at the end of a window: every balance account's closing position, and this year's
+ * result under equity until the year is closed.
+ */
+export declare function balanceSheet(accounts: readonly LedgerAccount[], totals: Map<string, AccountTotals>, window: {
+    from: string;
+    to: string;
+    yearFrom: string;
+}, yearResultCents: Cents, labelOf?: (key: string) => string): BooksReport;
+/** A column balance row: the trial balance, split into the balance and the result columns. */
+export interface ColumnRow extends AccountTotals {
+    code: string;
+    name: string;
+    /** Closing position in the balance columns, or movement in the result columns. */
+    balanceDebitCents: Cents;
+    balanceCreditCents: Cents;
+    resultDebitCents: Cents;
+    resultCreditCents: Cents;
+}
+export declare function columnBalance(accounts: readonly LedgerAccount[], totals: Map<string, AccountTotals>): ColumnRow[];
+/** Something expected to move cash: an open invoice, a receipt to pay, an instalment. */
+export interface CashEvent {
+    date: string;
+    /** + in, − out. */
+    cents: Cents;
+    kind: "receivable" | "payable" | "instalment";
+    label: string;
+}
+/**
+ * The cash forecast per week from today: what is on the bank now, plus what comes in and goes out
+ * as open items fall due. Overdue items land in the first week — that is when they are expected.
+ */
+export declare function cashForecast(startCents: Cents, events: readonly CashEvent[], today: string, weeks?: number): {
+    from: string;
+    inCents: number;
+    outCents: number;
+    closingCents: number;
+}[];

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

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

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

@@ -0,0 +1,59 @@
+import { Cents } from '../money/money';
+import { TaxCode } from '../money/tax';
+/**
+ * The VAT return, computed from posted lines (plan 039 datamodel §7): every line with a VAT code
+ * and a tax point in the period adds its base and VAT to the boxes of that code. Pure; the server
+ * turns journal lines into `VatLine`s.
+ */
+export interface VatLine {
+    /** A line on a revenue account is a sale, anything else a purchase. */
+    side: "sales" | "purchase";
+    taxCode: string;
+    /** Positive for a sale or a purchase, negative for its credit note. */
+    baseCents: Cents;
+    taxCents: Cents;
+    taxPointDate: string;
+    counterpartyCompanyId?: string;
+}
+export declare const NL_VAT_BOXES: readonly ["1a", "1b", "1c", "1d", "1e", "2a", "3a", "3b", "3c", "4a", "4b", "5a", "5b", "5c", "5g"];
+export type VatBox = (typeof NL_VAT_BOXES)[number];
+export interface VatReturnFigures {
+    /** In cents, as the books hold them. */
+    boxes: Partial<Record<VatBox, {
+        baseCents?: Cents;
+        taxCents?: Cents;
+    }>>;
+    /** Whole euros as they go on the return: owed rounded down, input VAT rounded up, in your favour. */
+    euros: Partial<Record<VatBox, {
+        base?: number;
+        tax?: number;
+    }>>;
+    /** EC sales list: per customer, the base of the reverse-charged EU sales. */
+    icp: {
+        counterpartyCompanyId?: string;
+        baseCents: Cents;
+    }[];
+    /** Lines whose code is unknown: they are in no box, and the checklist says so. */
+    unknownCodes: string[];
+}
+/**
+ * The boxes for one period. Reverse charge on purchase (`selfAssessed`) is owed in its own box
+ * and deducted in 5b at the standard rate of its tax point; input VAT counts at the code's
+ * deductible share. 5a is what is owed (1a–4b), 5b what is deducted, 5c and 5g the balance.
+ */
+export declare function vatReturn(input: {
+    lines: readonly VatLine[];
+    codes: readonly TaxCode[];
+    from: string;
+    to: string;
+    taxonomy?: string;
+    /** The code a self-assessed purchase is taxed at: the standard rate. */
+    standardKey?: string;
+}): VatReturnFigures;
+/** The periods a return is filed over, and when it is due: the month after, at its end. */
+export declare function vatPeriods(year: number, cadence?: "quarter" | "month" | "year"): {
+    label: string;
+    from: string;
+    to: string;
+    dueOn: string;
+}[];

package/dist/entities/transaction/booking.d.ts

@@ -0,0 +1,14 @@
+import { BookingDocument } from '../../platform/bookkeeping';
+import { Company } from '../company/types';
+import { Transaction } from './types';
+/** The kinds that reach the books. A quote or an order books nothing. */
+export declare const BOOKABLE_KINDS: readonly ["invoice", "credit_note"];
+export declare function isBookable(tx: Pick<Transaction, "kindKey" | "issuedAt">): boolean;
+/**
+ * An issued invoice or credit note as the books need it (plan 039 datamodel §3.2). Pure: sales
+ * owns the document, and this is the only shape of it that leaves the app.
+ *
+ * Headings and options carry no amount, so they are not lines here. A reverse charge or
+ * exemption ticked on the document replaces every line's code, as it did when it was priced.
+ */
+export declare function bookingDocumentOf(tx: Transaction, company: Pick<Company, "id" | "name" | "vatNumber" | "kvkNumber" | "address"> | null, sourceApp?: string): BookingDocument;

package/dist/entities/transaction/booking.test.d.ts

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

package/dist/entities/transaction/convert.d.ts

@@ -13,6 +13,11 @@ export declare function isFrozen(transaction: Pick<Transaction, "issuedAt">): bo
  * Everything else is a `BadRequestError`. Whoever wants to change a sent quote gets v2.
  */
 export declare const FROZEN_WRITABLE_FIELDS: readonly (keyof Transaction)[];
+/**
+ * Issued, numbered kind, no number yet: the books number it and have not answered ("wordt
+ * uitgegeven"). It cannot be sent to the customer until the number is on the paper.
+ */
+export declare function awaitsNumber(tx: Pick<Transaction, "issuedAt" | "kindKey" | "number">): boolean;
 /**
  * What a save may set on a draft. `status` is not here: it moves through `issue` and the status
  * route, which check the transition and announce it.

package/dist/entities/transaction/dunning.d.ts

@@ -0,0 +1,37 @@
+import { Cents } from '../money/money';
+import { ReceivableRow } from './receivable';
+/** One step of the schedule. Level 1 counts from the due day, every later one from the last sent. */
+export interface DunningStep {
+    level: number;
+    afterDays: number;
+    /** The message template it sends (comms `message-template` key). */
+    templateKey: string;
+    /** ponytail: e-mail only; a letter or text message when someone asks for one. */
+    channel: "email";
+}
+/** Per administration, or shared when `businessEntityId` is empty. */
+export interface DunningPolicy {
+    id?: string;
+    organizationId?: string;
+    businessEntityId?: string;
+    steps: DunningStep[];
+    /** Below this open amount nothing is chased. */
+    minOpenCents?: Cents;
+}
+export declare const DEFAULT_DUNNING_POLICY: DunningPolicy;
+export interface DunningDue {
+    row: ReceivableRow;
+    step: DunningStep;
+    /** The day this step falls due. */
+    dueOn: string;
+}
+/**
+ * What the schedule says about one open invoice on `today`: the step that is due, `"done"` when
+ * every step went out (a person takes over), or `null` when nothing is due yet.
+ */
+export declare function dunningStateOf(row: ReceivableRow, policy: DunningPolicy, today: string): DunningDue | "done" | null;
+/** The whole run: what is due now per step, and what waits for a person. */
+export declare function dunningRunOf(rows: readonly ReceivableRow[], policy: DunningPolicy, today: string): {
+    due: DunningDue[];
+    waiting: ReceivableRow[];
+};

package/dist/entities/transaction/dunning.test.d.ts

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

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

@@ -1,7 +1,11 @@
+export * from './booking';
 export * from './convert';
 export * from './document';
+export * from './dunning';
 export * from './keys';
 export * from './kinds';
 export * from './number-series';
 export * from './payment-term';
+export * from './receivable';
+export * from './settlement';
 export * from './types';

package/dist/entities/transaction/keys.d.ts

@@ -9,6 +9,8 @@
  */
 export declare const TRANSACTION_SCOPE_KINDS: readonly string[];
 export declare const PRODUCT_SCOPE_KIND = "product";
+/** An agreement: what a customer takes every period. Puts it in the customer file. */
+export declare const AGREEMENT_SCOPE_KIND = "agreement";
 /** `invoice:412`. The kind of a transaction *is* its kind key — no mapping table. */
 export declare function transactionScopeKey(kindKey: string, id: string): string;
 export declare function productScopeKey(id: string): string;
@@ -27,6 +29,11 @@ export declare function productHref(row: {
     id: string;
     businessEntityId?: string;
 }, fallbackEntityId?: string): string | undefined;
+export declare function agreementScopeKey(id: string): string;
+export declare function agreementHref(row: {
+    id: string;
+    businessEntityId?: string;
+}, fallbackEntityId?: string): string | undefined;
 /** Is this scopeKey one of ours, and which id does it point at? */
 export declare function transactionIdFromScope(scopeKey: string): string | undefined;
 /**

package/dist/entities/transaction/receivable.d.ts

@@ -0,0 +1,47 @@
+import { SettlementState } from '../../platform/bookkeeping';
+import { Cents } from '../money/money';
+import { Transaction } from './types';
+/** One open invoice as "Openstaand" shows it. */
+export interface ReceivableRow {
+    id: string;
+    kindKey: string;
+    number?: string;
+    companyId: string;
+    businessEntityId?: string;
+    issuedAt?: number;
+    dueAt?: number;
+    /** Whole days past the due day on `today`; 0 when not yet due. */
+    overdueDays: number;
+    grossCents: Cents;
+    openCents: Cents;
+    paymentState: SettlementState;
+    /** The highest dunning step sent, 0 for none. */
+    dunningLevel: number;
+    lastDunningAt?: number;
+}
+export declare const AGING_BUCKETS: readonly ["current", "d1_30", "d31_60", "d61_90", "d90_plus"];
+export type AgingBucket = (typeof AGING_BUCKETS)[number];
+/** `null` for a row that is not open (a draft, cancelled, or paid). */
+export declare function receivableRowOf(tx: Transaction, today: string): ReceivableRow | null;
+export declare function agingBucketOf(overdueDays: number): AgingBucket;
+/** Open amount and count per bucket, every bucket present so the strip never jumps. */
+export declare function agingOf(rows: readonly ReceivableRow[]): Record<AgingBucket, {
+    openCents: Cents;
+    count: number;
+}>;
+/**
+ * "What does this customer still owe", across every administration, for a surface outside sales
+ * (the crm company rail). Over the service bus, so crm sees with `has()` whether sales is there.
+ */
+export declare const COMPANY_RECEIVABLES_SERVICE = "receivables.company";
+export interface CompanyReceivables {
+    count: number;
+    openCents: Cents;
+    overdueCount: number;
+    overdueCents: Cents;
+    /** Days past due of the oldest overdue invoice; 0 when nothing is overdue. */
+    oldestOverdueDays: number;
+    /** The highest dunning step sent on any open invoice, 0 for none. */
+    dunningLevel: number;
+}
+export declare function companyReceivablesOf(rows: ReceivableRow[]): CompanyReceivables;

package/dist/entities/transaction/receivable.test.d.ts

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

package/dist/entities/transaction/settlement.d.ts

@@ -0,0 +1,20 @@
+import { SettledNotice, SettlementState } from '../../platform/bookkeeping';
+import { Transaction } from './types';
+/**
+ * Payment and overdue as two axes beside the lifecycle (plan 039 datamodel §2.3): an invoice can
+ * be partly paid and overdue at once. Pure, so the list, the job and the notice agree.
+ */
+/** Unpaid until someone or something says otherwise. */
+export declare function paymentStateOf(tx: Pick<Transaction, "settlement">): SettlementState;
+export declare function isSettled(tx: Pick<Transaction, "settlement">): boolean;
+/** Open means: went out, is still live, and not paid. A draft or a cancelled document is not. */
+export declare function isOutstanding(tx: Pick<Transaction, "status" | "issuedAt" | "settlement">): boolean;
+/** Overdue on `today` (`"2026-09-26"`): outstanding and past its due day. */
+export declare function isOverdueOn(tx: Pick<Transaction, "status" | "issuedAt" | "settlement" | "dueAt">, today: string): boolean;
+/**
+ * What a notice from the books changes on the document, or `null` when it changes nothing. A
+ * notice older than what we hold is ignored; posting facts only ever fill in, never overwrite.
+ */
+export declare function settlementPatch(tx: Pick<Transaction, "settlement" | "postedAt" | "externalIds" | "number">, notice: SettledNotice): Partial<Transaction> | null;
+/** A person ticking it off by hand, when no books are connected. */
+export declare function manualSettlement(tx: Pick<Transaction, "totals">, state: "unpaid" | "paid", now: number): NonNullable<Transaction["settlement"]>;

package/dist/entities/transaction/settlement.test.d.ts

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

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

@@ -1,4 +1,6 @@
+import { SettlementState } from '../../platform/bookkeeping';
 import { DocumentBlock } from '../../platform/document-blocks';
+import { LineUsage } from '../agreement/types';
 import { DocumentSender } from '../document-template/types';
 import { Cents } from '../money/money';
 import { TaxRateKind } from '../money/tax';
@@ -111,11 +113,28 @@ export interface Transaction {
         mountId: string;
         fileId: string;
     };
-    /** Which dunning step went out when. This is the whole debtor state; there is no table. */
+    /** Which dunning step went out when. There is no dunning table. */
     dunning?: {
         level: number;
         sentAt: number;
     }[];
+    /**
+     * Payment, as a **derived view**: the last state the books reported (`bookable/settled`), or
+     * what a person ticked off when no books are connected (`source: "manual"`). The truth is the
+     * reconciliation in the books. A separate axis from `status`, and from `overdueSince`: an
+     * invoice can be partly paid and overdue at once (plan 039 datamodel §2.3).
+     */
+    settlement?: {
+        state: SettlementState;
+        paidCents: Cents;
+        openCents: Cents;
+        lastPaymentAt?: number;
+        source: "manual" | "books";
+        /** A notice older than this is ignored: whole state, never a delta. */
+        asOf: number;
+    };
+    /** The day it fell overdue, set by a daily job; cleared once paid. Days, not instants. */
+    overdueSince?: string;
     /**
      * This transaction in external systems (`moneybird:412`). The dedupe axis the ingest pipeline
      * upserts on — without it the second run of an order import creates every order again.
@@ -135,7 +154,7 @@ export interface Transaction {
  * A union and not a free string: kinds and their statuses are **ours**, not the organisation's.
  * Labels follow from the key as `status_<key>`.
  */
-export type TransactionStatus = "draft" | "sent" | "accepted" | "rejected" | "expired" | "confirmed" | "delivered" | "open" | "paid" | "overdue" | "settled" | "cancelled"
+export type TransactionStatus = "draft" | "sent" | "accepted" | "rejected" | "expired" | "confirmed" | "delivered" | "open" | "cancelled"
 /** A newer version of this document went out. Set by the server, never by a person. */
  | "superseded";
 export interface IssuedPaper {
@@ -182,6 +201,19 @@ export interface TransactionLine {
      * the line — not the entry — is the source of truth. Never copied to a new document.
      */
     timeEntryIds?: string[];
+    /** How a usage line was counted: from a meter or entered per period. Never re-priced. */
+    usage?: LineUsage;
+    /**
+     * The agreement line this bills, and the days it covers. Together with `correction` these are
+     * the whole "what was billed" state of an agreement — see `dueCharges`.
+     */
+    agreementLineId?: string;
+    servicePeriod?: {
+        from: number;
+        to: number;
+    };
+    /** Settles days of a window billed earlier, at the price it was billed at. */
+    correction?: boolean;
     /**
      * An option: priced and shown, but **not** in the total.
      *