@opencxh/domain 1.240.0 → 1.242.0

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

@@ -0,0 +1,126 @@
+import { Cents } from '../money/money';
+import { OwnerScope } from '../scope/types';
+/**
+ * The engine: a quote, an order, an invoice, a credit note.
+ *
+ * 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 {
+    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;
+    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;
+    status: TransactionStatus;
+    /**
+     * The lines, as a column and not a table.
+     *
+     * A transaction is always read whole and never written half — and freezing has to be
+     * 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[];
+    /** 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;
+    introText?: string;
+    termsText?: string;
+    /** Epoch ms. `issuedAt` set = frozen. */
+    issuedAt?: number;
+    expiresAt?: number;
+    /** Only on a numbered kind, and only at the moment of issuing. */
+    number?: string;
+    /** 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. This is the whole debtor state; there is no table. */
+    dunning?: {
+        level: number;
+        sentAt: number;
+    }[];
+    /**
+     * 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;
+}
+/**
+ * The statuses, all kinds together. Which kind offers which is {@link TransactionKind.statuses}.
+ *
+ * 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 interface TransactionLine {
+    /** Stable within the transaction, so a version diff can follow a line. */
+    id: string;
+    /** `product` counts; `text` is a heading or a paragraph and carries no amount. */
+    kind: "product" | "text";
+    productId?: string;
+    /** Copied on adding: a quote from last year must stay readable when the product is renamed. */
+    name: string;
+    description?: string;
+    unitKey: string;
+    quantity: number;
+    unitPriceCents: Cents;
+    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 cost price as it stood when the line was added. Shielded by `sales.product.cost`. */
+    costPriceCents?: Cents;
+    /** The mapping axis onto a chart of accounts, copied from the product's category. */
+    ledgerCategoryKey?: string;
+}
+export interface TransactionTotals {
+    netCents: Cents;
+    taxCents: Cents;
+    grossCents: Cents;
+    /** Sum of the copied cost prices. Shielded — strip it with the line's `costPriceCents`. */
+    costCents?: Cents;
+    /** Per rate, because that is what the invoice and the bookkeeping both need. */
+    byRate: {
+        taxRateKey: string;
+        netCents: Cents;
+        taxCents: Cents;
+    }[];
+}