@opencxh/domain 1.302.0 → 1.303.0

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

@@ -1,6 +1,7 @@
 import { SettlementState } from '../../platform/bookkeeping';
 import { DocumentBlock } from '../../platform/document-blocks';
 import { LineUsage } from '../agreement/types';
+import { PartySnapshot } from '../company/role';
 import { DocumentSender } from '../document-template/types';
 import { Cents } from '../money/money';
 import { PricePer } from '../money/period-price';
@@ -9,43 +10,27 @@ import { PostalAddress } from '../organization/types';
 import { OwnerScope } from '../scope/types';
 import { TransactionPaymentTerm } from './payment-term';
 /**
- * The engine: a quote, an order, an invoice, a credit note.
+ * What every transaction shares, in either direction: the party, the money, the lines, the paper
+ * (plan 051). Sales adds its facet in {@link SalesTransaction}, purchase in `PurchaseOrder`.
  *
  * Deliberately **not** called a document. In this repo `Document*` means the sheet of paper —
  * blocks, templates, slots — and that layer renders a contract as readily as an invoice. A
  * transaction *has* a document; it is not one. See `plans/SALES-2026-09-14.md` §2.0.
  */
-export interface Transaction {
+export interface Transaction<L extends TransactionLine = TransactionLine, S extends string = string> {
     id: string;
     organizationId: string;
     /** Which kind. See {@link TRANSACTION_KINDS}. In v1 only `quote` is switched on. */
     kindKey: string;
-    /**
-     * The transaction this one came out of: quote -> order -> invoice.
-     *
-     * This one field *is* the conversion. `copyFrom()` carries over the lines, the customer, the
-     * currency and the price sources; there is no second code path per direction, and "which
-     * invoice belongs to this quote" is an indexed query instead of a hunt.
-     */
-    sourceTransactionId?: string;
-    /** The agreement that produced it, when it came from one. */
-    agreementId?: string;
-    /** Version within the same quote. A sent quote is revised, never edited. */
-    version: number;
-    previousVersionId?: string;
     /**
      * Which sending entity issues this — whose letterhead, whose books, whose number series.
      *
-     * Empty means the organisation's default. Frozen at issue: it is not in
+     * Always a real id (review 5a-4). Frozen at issue: it is not in
      * {@link FROZEN_WRITABLE_FIELDS}, so changing it on a sent document is already refused.
      */
-    businessEntityId?: string;
+    businessEntityId: string;
     companyId: string;
     contactId?: string;
-    /** The work item (the deal) this belongs to. Optional: not every quote has a deal. */
-    dealItemId?: string;
-    ownerScope: OwnerScope;
-    ownerUserId: string;
     title?: string;
     reference?: string;
     currency: string;
@@ -54,7 +39,7 @@ export interface Transaction {
      * its books in (the ECB rate of that day). Absent in the books' own currency.
      */
     fxRate?: string;
-    status: TransactionStatus;
+    status: S;
     /**
      * The lines, as a column and not a table.
      *
@@ -62,11 +47,9 @@ export interface Transaction {
      * indivisible, which two tables without a transaction cannot do. The price is that "revenue per
      * product" is not a query; that question is answered from the facts written at issue time.
      */
-    lines: TransactionLine[];
+    lines: L[];
     /** Recomputed on every save, stored so a list can sort and add up. */
     totals: TransactionTotals;
-    /** Reverse charge or exemption: ticked, never derived. Replaces every line's rate. */
-    taxOverrideKey?: string;
     /**
      * The remark above the lines, and the conditions under them.
      *
@@ -84,11 +67,63 @@ export interface Transaction {
      * ride along because the due date is computed at issue, and by then the row may be gone.
      */
     paymentTerm?: TransactionPaymentTerm;
+    /** Epoch ms. `issuedAt` set = frozen. */
+    issuedAt?: number;
+    /** Only on a numbered kind, and only at the moment of issuing. */
+    number?: string;
+    /**
+     * The paper as it went out: blocks and letterhead, filled at issue. A frozen document shows
+     * this and never re-renders — the customer's address, the sender's IBAN, a VAT rate and the
+     * template may all change afterwards, and an invoice must keep saying what it said.
+     */
+    issuedPaper?: IssuedPaper;
+    /** The rendered PDF in `apps/storage`. A reference, never the content. */
+    fileRef?: {
+        mountId: string;
+        fileId: 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.
+     */
+    externalIds?: string[];
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/** Who is invoiced and chased: the invoice recipient, else the customer. Revenue stays the customer's. */
+export declare const debtorOf: (tx: Pick<SalesTransaction, "companyId" | "invoiceTo">) => string;
+/** The sales facet: a quote, an order, an invoice, a credit note. */
+export interface SalesTransaction extends Transaction<SalesLine, SalesStatus> {
+    /**
+     * The transaction this one came out of: quote -> order -> invoice.
+     *
+     * This one field *is* the conversion. `copyFrom()` carries over the lines, the customer, the
+     * currency and the price sources; there is no second code path per direction, and "which
+     * invoice belongs to this quote" is an indexed query instead of a hunt.
+     */
+    sourceTransactionId?: string;
+    /** The agreement that produced it, when it came from one. */
+    agreementId?: string;
+    /** Version within the same quote. A sent quote is revised, never edited. */
+    version: number;
+    previousVersionId?: string;
+    /** The work item (the deal) this belongs to. Optional: not every quote has a deal. */
+    dealItemId?: string;
+    ownerScope: OwnerScope;
+    ownerUserId: string;
+    /** Reverse charge or exemption: ticked, never derived. Replaces every line's rate. */
+    taxOverrideKey?: string;
     /**
      * The customer's crm address this document goes to (plan 050); absent = its primary billing
      * address. Read while it is a draft, frozen as `issuedPaper.billingAddress` when it goes out.
      */
     billingAddressId?: string;
+    /**
+     * Where the goods go (Exact `DeliveryAddress`): a crm address of the customer; absent = its
+     * primary delivery address. Fulfilment delivers there.
+     */
+    deliveryAddressId?: string;
     /**
      * When it falls due. Computed at issue from the condition, and only for a numbered kind: a quote
      * does not fall due, it expires — that is `expiresAt`.
@@ -107,24 +142,9 @@ export interface Transaction {
      */
     periodFrom?: number;
     periodTo?: number;
-    /** Epoch ms. `issuedAt` set = frozen. */
-    issuedAt?: number;
     expiresAt?: number;
-    /** Only on a numbered kind, and only at the moment of issuing. */
-    number?: string;
-    /**
-     * The paper as it went out: blocks and letterhead, filled at issue. A frozen document shows
-     * this and never re-renders — the customer's address, the sender's IBAN, a VAT rate and the
-     * template may all change afterwards, and an invoice must keep saying what it said.
-     */
-    issuedPaper?: IssuedPaper;
     /** Posted — to whichever set of books. Set by the push, never by a person. */
     postedAt?: number;
-    /** The rendered PDF in `apps/storage`. A reference, never the content. */
-    fileRef?: {
-        mountId: string;
-        fileId: string;
-    };
     /** Which dunning step went out when. There is no dunning table. */
     dunning?: {
         level: number;
@@ -136,6 +156,11 @@ export interface Transaction {
      * 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).
      */
+    /**
+     * `isSettled(settlement)` as a flat, indexed column: "what is still open" is a query on it, not
+     * a scan of every open invoice. Written with `settlement`, `false` from issue on.
+     */
+    settled?: boolean;
     settlement?: {
         state: SettlementState;
         paidCents: Cents;
@@ -147,18 +172,18 @@ export interface Transaction {
     };
     /** 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.
-     */
-    externalIds?: string[];
     /** Which credential a change has to be written back with. Two connections, two answers. */
     source?: {
         connectionId?: string;
     };
-    createdBy: string;
-    createdAt?: number;
-    updatedAt?: number;
+    /**
+     * Who gets the invoice when that is not the customer: the holding that pays for its daughter
+     * (KETEN-STAND B2; Exact `InvoiceTo`). Its address is `billingAddressId`. Frozen at issue.
+     */
+    invoiceTo?: {
+        companyId: string;
+        contactId?: string;
+    };
 }
 /**
  * The statuses, all kinds together. Which kind offers which is {@link TransactionKind.statuses}.
@@ -166,9 +191,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"
-/** A purchase order whose every line came in. */
- | "received" | "open" | "cancelled"
+export type SalesStatus = "draft" | "sent" | "accepted" | "rejected" | "expired" | "confirmed" | "open" | "cancelled"
 /** A newer version of this document went out. Set by the server, never by a person. */
  | "superseded";
 export interface IssuedPaper {
@@ -178,6 +201,8 @@ export interface IssuedPaper {
     customerName?: string;
     /** The billing address as it went out (plan 050); the books take this one, not crm's today. */
     billingAddress?: PostalAddress;
+    /** The debtor as it went out: the invoice recipient when there is one, else the customer. */
+    counterparty?: PartySnapshot;
 }
 export interface TransactionLine {
     /** Stable within the transaction, so a version diff can follow a line. */
@@ -201,28 +226,46 @@ export interface TransactionLine {
     pricePer?: PricePer;
     discountPercent?: number;
     taxRateKey: string;
-    /** Which rung of the price ladder produced this amount. Purely to account for it. */
-    priceSourceKey?: string;
     /** Step 1 of the rounding order, stored so the client need not recompute. */
     netCents: Cents;
     /** This line's share of its rate group's VAT. Shielded, like the cost price. */
     taxCents: Cents;
+    /** The mapping axis onto a chart of accounts, copied from the product's category. */
+    ledgerCategoryKey?: string;
+    /** The days the line is for: a month of rental, a year of a licence bought (Exact: both sides). */
+    servicePeriod?: {
+        from: number;
+        to: number;
+    };
+    /**
+     * What the line is booked against (049 J, KETEN-STAND B1): the same shape on every line that
+     * reaches the books. Ids, never names. `costUnitId` is derived from `projectId` at booking.
+     */
+    dimensions?: LineDimensions;
+}
+/** Only the known dimensions, as non-empty strings; `undefined` when none is left. */
+export declare function cleanDimensions(raw: unknown): LineDimensions | undefined;
+/** KETEN-STAND B1: the four dimensions a booked line carries, defined once. */
+export declare const DIMENSION_KEYS: readonly ["costCenterId", "costUnitId", "projectId", "customerCompanyId"];
+export interface LineDimensions {
+    /** organization (plan 040): a department or branch. */
+    costCenterId?: string;
+    /** finance (plan 040): a cost unit — a project's, or a car, a building, a grant. */
+    costUnitId?: string;
+    /** work: a work item of type project. */
+    projectId?: string;
+    /** crm: for whom, when it is passed on or carries a margin per customer. */
+    customerCompanyId?: string;
+}
+/** A sales line: priced on the ladder, billed from hours, usage or an agreement. */
+export interface SalesLine extends TransactionLine {
+    /** Which rung of the price ladder produced this amount. Purely to account for it. */
+    priceSourceKey?: string;
     /**
      * The cost price as it stood when the line was added, per `unitKey`, **in the document's
      * currency** (converted on that day, plan 046 #16). Shielded by `catalog.product.cost`.
      */
     costPriceCents?: Cents;
-    /** The mapping axis onto a chart of accounts, copied from the product's category. */
-    ledgerCategoryKey?: string;
-    /**
-     * The work item this line is for. Same referent as {@link Transaction.dealItemId}, one level
-     * down: a quote may cover one deal while its lines belong to different items under it.
-     *
-     * An id and never a copied title — whoever owns the item renames it, and a name stored here
-     * would be stale the same afternoon. Not printed on the document; it is what the work is
-     * booked against, not what the customer reads.
-     */
-    dealItemId?: string;
     /**
      * The time entries this line bills. Sales stamps exactly this set onto them on every save, so
      * the line — not the entry — is the source of truth. Never copied to a new document.
@@ -235,10 +278,6 @@ export interface TransactionLine {
      * 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;
     /**
@@ -249,6 +288,22 @@ export interface TransactionLine {
      * version of the quote with the flag off, the same way every other change to a sent quote is.
      */
     optional?: boolean;
+    /**
+     * The line it came from when converted: an invoice line points at its order line (KETEN-STAND
+     * B3; Exact `SalesInvoiceLine.SalesOrderLine`). "How much of this order line is invoiced" is the
+     * sum of the lines pointing at it — derived, never a counter on the order.
+     */
+    sourceLine?: {
+        transactionId: string;
+        lineId: string;
+    };
+    /**
+     * The answers to what a provider asks before the promise (047 step 8), by param key; an address
+     * is a crm address id (`site: "<addressId>"`). Travel to the agreement and the request.
+     */
+    answers?: Record<string, string>;
+    /** The delivery check made with those answers (fulfilment's `Qualification`). */
+    qualificationId?: string;
 }
 export interface TransactionTotals {
     netCents: Cents;