@opencxh/domain 1.288.0 → 1.291.0

package/dist/platform/bookkeeping.d.ts

@@ -0,0 +1,276 @@
+import { LedgerMappingRule } from '../entities/bookkeeping/types';
+import { Cents } from '../entities/money/money';
+import { TaxRateKind } from '../entities/money/tax';
+export declare const BOOKABLE_SOURCE_PROVIDER_GROUP = "bookable-source";
+export declare const BOOKKEEPING_PROVIDER_GROUP = "bookkeeping";
+/** Routes under `/provider`. Constants, so caller and provider cannot drift apart. */
+export declare const BOOKABLE_ROUTES: {
+    readonly get: "/bookable/get";
+    readonly issued: "/bookable/issued";
+    readonly ledgerCategories: "/bookable/ledger-categories";
+    readonly settled: "/bookable/settled";
+};
+export declare const BOOKKEEPING_ROUTES: {
+    readonly describe: "/bookkeeping/describe";
+    readonly post: "/bookkeeping/post";
+    readonly lookup: "/bookkeeping/lookup";
+    readonly payments: "/bookkeeping/payments";
+    readonly paymentRegister: "/bookkeeping/payment-register";
+    readonly paymentUndo: "/bookkeeping/payment-undo";
+    readonly settle: "/bookkeeping/settle";
+    readonly reports: "/bookkeeping/reports";
+};
+/**
+ * What has to be booked, in EN 16931 terms so every e-invoice format is a serialisation of it.
+ * Carries no HTML and no type of the source app.
+ */
+export interface BookingDocument {
+    sourceApp: string;
+    documentId: string;
+    direction: "sale" | "purchase";
+    kind: "invoice" | "credit_note" | "receipt";
+    businessEntityId: string;
+    /** Empty for a receipt without a number, and for an invoice the books will number themselves. */
+    number?: string;
+    counterparty: {
+        companyId?: string;
+        name: string;
+        vatNumber?: string;
+        kvkNumber?: string;
+        /** As entered: `country` is free text here, the books map it onto their own code. */
+        address?: {
+            street?: string;
+            postalCode?: string;
+            city?: string;
+            country?: string;
+        };
+        country?: string;
+    };
+    /** `"2026-09-24"`. Dates are days, not instants. */
+    issueDate: string;
+    /** Delivery date or end of the service period: decides the VAT period. */
+    taxPointDate?: string;
+    dueDate?: string;
+    currency: string;
+    /** Decimal string, only when the currency differs from the administration's own. */
+    fxRate?: string;
+    lines: BookingLine[];
+    totals: {
+        netCents: Cents;
+        taxCents: Cents;
+        grossCents: Cents;
+    };
+    creditsDocumentId?: string;
+    attachment?: {
+        mountId: string;
+        fileId: string;
+    };
+    externalIds?: string[];
+}
+export interface BookingLine {
+    description: string;
+    netCents: Cents;
+    taxCents: Cents;
+    /** `TaxCode.key`. The books map it onto their own box and account. */
+    taxRateKey: string;
+    taxKind: TaxRateKind;
+    /** The percent the line was priced at (`21`). Absent on documents priced before it was stored. */
+    taxPercent?: number;
+    ledgerCategoryKey?: string;
+    /**
+     * The account in the target books a person chose for this line (a receipt: "Kiezen"). Beats
+     * every mapping rule: `LedgerOption.key` in external books, the account id in our own.
+     */
+    accountKey?: string;
+    productId?: string;
+    /** Open map: cost centre, project, and whatever a later country needs. */
+    dimensions?: Record<string, string>;
+}
+/** One row of the sweeper's safety net: an issued document the books may not have heard of. */
+export interface IssuedDocumentRef {
+    documentId: string;
+    businessEntityId: string;
+    kind: BookingDocument["kind"];
+    issuedAt: number;
+    number?: string;
+}
+/**
+ * "This was issued": what a source tells finance (`POST finance/booking/enqueue`). Best effort —
+ * the sweeper asks `bookable/issued` for anything this missed.
+ */
+export interface BookingAnnouncement {
+    sourceApp: string;
+    documentId: string;
+    /** Empty = the default administration; finance resolves it, a row never carries "". */
+    businessEntityId?: string;
+    documentKind: BookingDocument["kind"];
+    documentNumber?: string;
+    issuedAt: number;
+}
+/** A bucket a product or line is booked under. The mapping UIs pick from this list, never free text. */
+export interface LedgerCategory {
+    key: string;
+    label: string;
+}
+export type SettlementState = "unpaid" | "partially_paid" | "paid" | "overpaid";
+/**
+ * What the books know about one source document: that it arrived, and its whole payment state —
+ * never a delta, so a repeated or late notice can do no harm. The receiver ignores a notice whose
+ * `asOf` is older than what it holds. The payment fields are absent on a "posted" notice.
+ */
+export interface SettledNotice {
+    documentId: string;
+    asOf: number;
+    postedAt?: number;
+    externalId?: string;
+    /** The books' number, when they number the document themselves (Jortt). */
+    number?: string;
+    payment?: {
+        state: SettlementState;
+        paidCents: Cents;
+        openCents: Cents;
+        lastPaymentAt?: number;
+    };
+}
+export type BookkeepingCapability = "ledger" | "journal" | "invoice-push" | "expense-push" | "payment-register" | "payment-status" | "bank" | "reconcile" | "vat-report" | "reports" | "attachments";
+export interface LedgerOption {
+    key: string;
+    label: string;
+    kind: "revenue" | "expense" | "balance";
+}
+export interface BookkeepingDescribe {
+    app: string;
+    capabilities: BookkeepingCapability[];
+    /** Why a capability is missing, as an i18n key: the UI shows it beside the disabled control. */
+    missingReasons?: Partial<Record<BookkeepingCapability, string>>;
+    /** The target accounts a mapping UI offers, for books without separate connections. */
+    ledgerOptions?: LedgerOption[];
+    /**
+     * The connections a binding can pick (`BookkeepingBinding.accountId`), each with its own
+     * accounts: two Jortt administrations have two charts. Absent for our own books.
+     */
+    accounts?: {
+        id: string;
+        label: string;
+        ledgerOptions?: LedgerOption[];
+    }[];
+    /**
+     * Books whose chart is per administration of ours (our own books): the options for each,
+     * keyed by `businessEntityId`. A mapping UI picks from here when there is no connection.
+     */
+    administrationOptions?: Record<string, LedgerOption[]>;
+    /** Can a lost create response be recovered? `none` forbids an automatic retry. */
+    lookup: "correlation" | "number" | "none";
+    /** Who numbers an invoice: us at issue, or the books when it arrives there. */
+    numbering: "local" | "external";
+}
+/** What the binding says about the connection, handed along so the books need not ask back. */
+export interface BookingConnection {
+    /** `ManagedAccount.id` of the connection; empty for our own books. */
+    accountId?: string;
+    ledgerMapping?: LedgerMappingRule[];
+}
+export interface PostRequest {
+    sourceApp: string;
+    documentId: string;
+    businessEntityId: string;
+    /** Sent along to the books and searched on during recovery: `oc:<documentId>`. */
+    correlationKey: string;
+    connection: BookingConnection;
+}
+export interface PostResult {
+    externalId: string;
+    postedAt: number;
+    /** Set when the books numbered the document. */
+    number?: string;
+}
+export interface LookupRequest {
+    correlationKey: string;
+    connection: BookingConnection;
+    documentNumber?: string;
+    grossCents: Cents;
+    counterpartyName: string;
+    issueDate: string;
+}
+/** `unknown` means the search itself failed: do not create again. */
+export type LookupResult = {
+    found: true;
+    externalId: string;
+    number?: string;
+} | {
+    found: false;
+} | {
+    unknown: true;
+    reason: string;
+};
+/** A posted document in the books, and the connection to reach it by. */
+export interface BooksDocumentRef {
+    connection: BookingConnection;
+    /** `PostResult.externalId` as the books gave it. */
+    externalId: string;
+}
+/** One payment the books hold on a document. `id` is what undoing it takes. */
+export interface BooksPayment {
+    id: string;
+    /** Positive: money towards settling the document. */
+    amountCents: Cents;
+    date?: string;
+    /** The account it came from, by name. */
+    from?: string;
+    /** It came from another document (a credit note settling this one), not from an account. */
+    fromDocument?: boolean;
+    description?: string;
+}
+/**
+ * A document's payments in the books, the accounts a new one may come from, and its whole
+ * payment state after the call: every payment route answers with this, so the caller never
+ * waits for the next poll.
+ */
+export interface BooksPayments {
+    payment: NonNullable<SettledNotice["payment"]>;
+    payments: BooksPayment[];
+    fromOptions: {
+        key: string;
+        label: string;
+    }[];
+}
+export interface RegisterPaymentRequest extends BooksDocumentRef {
+    amountCents: Cents;
+    date: string;
+    /** `BooksPayments.fromOptions[].key`. */
+    fromKey: string;
+    description?: string;
+}
+export interface UndoPaymentRequest extends BooksDocumentRef {
+    paymentId: string;
+}
+/** A report the books compute themselves (Jortt), in the shape our own reports have. */
+export interface ReportRequest {
+    connection: BookingConnection;
+    kind: "profit_and_loss" | "balance";
+    from: string;
+    to: string;
+}
+/** Settle an invoice with its credit note: the note's open amount pays the invoice. */
+export interface SettleRequest extends BooksDocumentRef {
+    sourceExternalId: string;
+}
+/**
+ * Who numbers this administration's invoices. `external` means the source issues without a number
+ * and takes the books' number from the "posted" {@link SettledNotice}.
+ */
+export interface NumberingAnswer {
+    numbering: BookkeepingDescribe["numbering"];
+}
+/**
+ * A payment state the books saw on their own (Jortt is polled), reported to finance, which knows
+ * which source document the correlation key belongs to and forwards a {@link SettledNotice}.
+ */
+export interface PaymentReport {
+    targetApp: string;
+    correlationKey: string;
+    asOf: number;
+    payment: NonNullable<SettledNotice["payment"]>;
+}
+/** The deterministic key a retry reuses, so the books can recognise a second attempt. */
+export declare function correlationKeyFor(documentId: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.288.0",
+  "version": "1.291.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",