@opencxh/domain 1.240.0 → 1.242.0

package/dist/entities/catalog/codes.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Three codes, three owners — and only one of them may be normalised.
+ *
+ * | Field | Whose | Shape |
+ * |---|---|---|
+ * | `sku` | ours | free, unique per organisation |
+ * | `gtin` | GS1's | 8, 12, 13 or 14 digits + check digit |
+ * | `barcodes` | mixed | as scanned |
+ *
+ * `gtin` and not `ean`: EAN-13 is one of four lengths, GTIN is the umbrella and the word GS1 uses
+ * itself. The screen says "EAN / barcode", because that is what people say.
+ */
+/**
+ * A GTIN as one key, or `undefined` when it is not one.
+ *
+ * The same box arrives as UPC-12 `012345678905` from an American feed and as EAN-13
+ * `0012345678905` from Shopify. Left-padding to 14 digits makes those one key; without it the
+ * second import creates a second product and the reporting axis is broken.
+ *
+ * **Refuses rather than quietly cleaning up.** The check digit costs ten lines and catches the
+ * typo that otherwise only shows in the webshop — and a product with an invented EAN is worse
+ * than a product without one.
+ */
+export declare function normalizeGtin(raw: string): string | undefined;
+/**
+ * A filter that finds a product by whatever was typed or scanned.
+ *
+ * One helper and not three queries in three screens, because of the trap in the middle:
+ * `barcodes` is a string **array**, and `{ barcodes: "x" }` matches nothing on it — it has to be
+ * `$in`. That mistake is silent; it returns an empty list, not an error.
+ */
+export declare function codeQuery(organizationId: string, code: string): Record<string, unknown>;

package/dist/entities/catalog/codes.test.d.ts

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

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

@@ -0,0 +1,3 @@
+export * from './codes';
+export * from './pricing';
+export * from './types';

package/dist/entities/catalog/pricing.d.ts

@@ -0,0 +1,40 @@
+import { Cents } from '../money/money';
+import { PriceRule, Product } from './types';
+/**
+ * The ladder: the most specific rule wins, whole. No sum, no stacking.
+ *
+ * | Rank | Rule | Source |
+ * |---|---|---|
+ * | 1 | contract + product | `contract` |
+ * | 2 | customer + product | `customer` |
+ * | 3 | customer + category | `customer_category` |
+ * | 4 | segment + product | `segment` |
+ * | 5 | segment + category | `segment_category` |
+ * | 6 | the product's list price | `list` |
+ *
+ * A tier (`minQuantity`) is not a rung of its own but a tie-break within one: of the rules that
+ * pass, the highest threshold that the quantity reaches wins, and the source then reads `tier`
+ * — because that is the answer the salesperson is looking for.
+ */
+export interface PriceContext {
+    companyId?: string;
+    segmentKey?: string;
+    contractId?: string;
+    quantity: number;
+    /** Epoch ms; the validity window is judged against this, not against "now". */
+    at: number;
+}
+export interface ResolvedPrice {
+    unitPriceCents: Cents;
+    /** Where this amount came from. Almost free, and the only question a salesperson asks. */
+    sourceKey: string;
+    ruleId?: string;
+}
+/**
+ * The price for this product, for this customer, at this quantity, on this date.
+ *
+ * Pure, so the screen can compute along while you type and land on the same cent the server
+ * stores. A rule that names neither the product nor its category does not apply, however
+ * specific its customer is: a discount on "everything" is a decision, not a price rule.
+ */
+export declare function resolvePrice(product: Product, ctx: PriceContext, rules: readonly PriceRule[]): ResolvedPrice;

package/dist/entities/catalog/pricing.test.d.ts

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

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

@@ -0,0 +1,107 @@
+import { Cents } from '../money/money';
+/**
+ * What we sell, variants included.
+ *
+ * One self-referencing table instead of a product/variant pair: a variant has exactly the same
+ * fields as its parent and misses none of them. What it adds is {@link Product.options} — and that
+ * is a column, not an entity.
+ */
+export interface Product {
+    id: string;
+    organizationId: string;
+    /** The parent this is a variant of. Absent = a product in its own right. */
+    parentId?: string;
+    /** What makes this variant different: `[{ key: "colour", value: "black" }]`. A label, nothing more. */
+    options?: {
+        key: string;
+        value: string;
+    }[];
+    name: string;
+    description?: string;
+    /** Our own article number. Unique per organisation — see `codes.ts`. */
+    sku?: string;
+    /** The global code: EAN-13, UPC-12, GTIN-14. Stored normalised — see `normalizeGtin`. */
+    gtin?: string;
+    /** Whatever else is scannable (outer case, our own Code128), as scanned. */
+    barcodes?: string[];
+    /**
+     * The category this falls under — a key from a small table of its own, not free text.
+     *
+     * Having to be stable is the whole requirement: together with {@link Product.taxRateKey} this is
+     * the key the bookkeeping bridge picks a ledger account on. A free text field where one person
+     * types "Services" and another "services " cannot carry that.
+     */
+    categoryKey?: string;
+    /** References to this product elsewhere (`moneybird:412`). A reference, never a copy. */
+    externalIds?: string[];
+    /** See {@link FIXED_UNITS}. Drives the form and the word after the quantity. */
+    unitKey: string;
+    /** Key into the organisation's VAT table, never the percentage itself. */
+    taxRateKey: string;
+    listPriceCents: Cents;
+    currency: string;
+    /**
+     * What we normally pay for this. **Not** a cost price out of an inventory valuation.
+     *
+     * Copied onto the line when it is added, and shielded: margin is not for everyone holding
+     * `sales.product.read`. It never reaches a template context either — `{line.cost}` on a quote
+     * would be one typo away.
+     */
+    costPriceCents?: Cents;
+    /** Who we buy it from. A `Company` in crm, so free — and all a later purchase order needs. */
+    supplierCompanyId?: string;
+    archived?: boolean;
+    order?: number;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * Units follow work's `FIXED_TYPES` pattern: a fixed list plus a namespaced fallback, so an
+ * unknown key reads as itself instead of breaking.
+ */
+export declare const FIXED_UNITS: readonly ["piece", "hour", "day", "month", "km", "license"];
+export type FixedUnit = (typeof FIXED_UNITS)[number];
+/**
+ * A price for a customer, a segment or a contract.
+ *
+ * Deliberately no price expression language: no formulas, no conditions, no ordering field. The
+ * moment a price cannot be explained to the customer it is the wrong price.
+ */
+export interface PriceRule {
+    id: string;
+    organizationId: string;
+    /** Either a specific product or a whole category. One of the two, never both. */
+    productId?: string;
+    categoryKey?: string;
+    /** For whom. Absent = for everyone. */
+    companyId?: string;
+    /** A free label on the customer card ("reseller", "education"). An attribute in crm. */
+    segmentKey?: string;
+    /** From which quantity. Absent = from one. */
+    minQuantity?: number;
+    /** Exactly one of the two. A fixed price beats a discount when both would apply. */
+    unitPriceCents?: Cents;
+    discountPercent?: number;
+    currency: string;
+    validFrom?: number;
+    validTo?: number;
+    /**
+     * The contract that placed this rule. Declared now because it is the top rung of the ladder: a
+     * contract price is not a second pricing mechanism, it is a price rule with an owner and a term.
+     */
+    contractId?: string;
+    createdBy: string;
+    createdAt?: number;
+}
+/**
+ * What the product form sends. Everything optional but the name: the server fills defaults, and
+ * a form that has to send a complete product cannot add a variant with two fields.
+ */
+export interface SaveProductRequest extends Partial<Omit<Product, "id" | "organizationId" | "createdBy" | "createdAt" | "updatedAt">> {
+    id?: string;
+    name: string;
+}
+export interface SavePriceRuleRequest extends Partial<Omit<PriceRule, "id" | "organizationId" | "createdBy" | "createdAt">> {
+    id?: string;
+}

package/dist/entities/document-template/tokens.d.ts

@@ -33,7 +33,7 @@ export type DocumentSlots = Record<string, readonly DocumentBlock[]>;
  * text lives.
  *
  * Every text-bearing field is walked, not just `text` — a token in a table cell or a letterhead
- * value is the ordinary case for an invoice, and missing one would leave `{factuur.nummer}`
+ * value is the ordinary case for an invoice, and missing one would leave `{invoice.number}`
  * printed on a document that went out the door.
  */
 export declare function fillDocument(blocks: readonly DocumentBlock[], context: TemplateContext, conditions?: Record<string, TemplateCondition>, slots?: DocumentSlots): FillDocumentResult;

package/dist/entities/document-template/types.d.ts

@@ -59,7 +59,7 @@ export interface DocumentTemplate {
  * app that decides it.
  */
 export interface TemplateCondition {
-    /** A path into the same context the tokens read: `klant.incasso`. */
+    /** A path into the same context the tokens read: `customer.direct_debit`. */
     key: string;
     /** Show when the value equals this. */
     equals?: unknown;

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

@@ -0,0 +1,3 @@
+export * from './money';
+export * from './tax';
+export * from './totals';

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

@@ -0,0 +1,66 @@
+/**
+ * Money, as whole cents. There is no `number` in euros anywhere in this platform.
+ *
+ * Not caution but necessity: `0.1 + 0.2 !== 0.3`, and a quote of eleven lines adds up eleven
+ * times. One cent between the screen and the invoice is not a rounding error, it is a customer
+ * on the phone.
+ *
+ * The currency lives on the transaction, never on the line: adding lines in two currencies does
+ * not produce an amount.
+ */
+export type Cents = number;
+/**
+ * Half a cent goes up, below zero too.
+ *
+ * `Math.round(-0.5)` is `-0`, not `-1`: JS rounds towards +infinity. On a credit note — where
+ * every amount is negative — that is systematically one cent too little refunded per line, and it
+ * only shows when someone puts the credit note next to the invoice.
+ */
+export declare function roundHalfUp(value: number): Cents;
+/**
+ * Split `total` over `weights` so the parts sum to exactly `total`.
+ *
+ * VAT is computed per rate group and not per line (see `totals.ts`), but a journal entry books it
+ * per line. Dividing proportionally and rounding each part independently loses or gains cents;
+ * largest-remainder gives every part its floor and hands the leftover cents to the largest
+ * fractions. Works for negative totals — a credit note is the whole point.
+ *
+ * Weights that sum to zero cannot be divided proportionally, so the whole amount lands on the
+ * first part rather than disappearing.
+ */
+export declare function allocate(total: Cents, weights: readonly number[]): Cents[];
+/** Grouping and decimal marks. Defaults are Dutch, because the organisation is. */
+export interface AmountFormat {
+    decimal?: string;
+    group?: string;
+}
+/**
+ * Cents as a readable amount. Always two decimals, never a currency symbol.
+ *
+ * Hand-rolled instead of `Intl.NumberFormat`: this module is imported by `apps/*​/server`, which
+ * runs on QuickJS, and `Intl` is not something to bet an invoice on. The symbol is the caller's
+ * job — it belongs next to the amount in the UI, not inside the number.
+ */
+export declare function formatCents(cents: Cents, format?: AmountFormat): string;
+/**
+ * A typed amount to cents, or `undefined` when it is not an amount.
+ *
+ * Both "1.234,56" and "1,234.56" have to work, and they differ only in which separator came last.
+ * So: the **last** separator is the decimal mark when one or two digits follow it; anything else
+ * is grouping and gets dropped. "1.234" is therefore one thousand two hundred and thirty-four,
+ * not 1,234 — the reading a Dutch typist intends, and the one a three-digit group implies.
+ *
+ * `undefined` rather than `0` on junk: a silent zero is a line that quietly costs nothing.
+ */
+export declare function parseAmount(input: string): Cents | undefined;
+/**
+ * What a line earns: its net minus what the goods cost us.
+ *
+ * Derived, never stored — see the plan's §2.2c. A line without a cost price counts as zero margin
+ * and not as a loss; "unknown" and "free" are not the same thing, and the screen says which.
+ */
+export declare function marginCents(line: {
+    netCents: Cents;
+    quantity: number;
+    costPriceCents?: Cents;
+}): Cents;

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

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

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

@@ -0,0 +1,33 @@
+/**
+ * VAT rates: a table, not an engine.
+ *
+ * The rate lives on the organisation's settings and a line refers to it **by key**, never by
+ * percentage. A rate that changes (21 became 21 in 2019, 19 before that) must not rewrite history,
+ * and a percentage copied onto a thousand lines cannot be corrected.
+ */
+export interface TaxRate {
+    key: string;
+    /** i18n key, not text — the same rule as `FIXED_TYPES` in work. */
+    label: string;
+    /** Whole percent as written on the invoice: `21`, not `0.21`. */
+    percent: number;
+    kind: TaxRateKind;
+}
+/**
+ * Why a rate is what it is.
+ *
+ * `zero`, `reverse_charge` and `exempt` all compute to nothing and are still three different
+ * sentences on an invoice, which is the only reason they are separate: the template picks its
+ * line from this, and the bookkeeping connector maps it onto its own tax code.
+ */
+export type TaxRateKind = "standard" | "reduced" | "zero" | "reverse_charge" | "exempt";
+/** The Dutch defaults an organisation starts with. It may edit them; it may not compute them. */
+export declare const NL_TAX_RATES: readonly TaxRate[];
+/**
+ * The rate for a key, or a zero-percent stand-in.
+ *
+ * Never `undefined`: an unknown key on a saved line must not make a total uncomputable. Charging
+ * nothing is the safe direction — too little VAT is a correction, a crash is a document nobody
+ * can open.
+ */
+export declare function taxRateFor(key: string, rates: readonly TaxRate[]): TaxRate;

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

@@ -0,0 +1,34 @@
+import { TransactionLine, TransactionTotals } from '../transaction/types';
+import { Cents } from './money';
+import { TaxRate } from './tax';
+/**
+ * The rounding order. Fixed, and not a setting.
+ *
+ * 1. Line net = `roundHalfUp(quantity * unitPrice * (1 - discount))` — once, per line.
+ * 2. Net per rate = the sum of those line amounts. Exact, they are already integers.
+ * 3. VAT = `roundHalfUp(netPerRate * rate)` — **once per rate, not per line.**
+ * 4. Total = sum of nets + sum of VAT.
+ *
+ * Step 3 is where billing packages diverge. Rounding per line differs by up to ten cents on twenty
+ * lines from every bookkeeping system that rounds per rate group — which is what Moneybird, Exact
+ * and the tax office do.
+ *
+ * `quantity` may be fractional (3.5 hours); a *price* never is.
+ */
+export declare function lineNet(line: TransactionLine): Cents;
+export interface PricedTransaction {
+    /** The same lines with `netCents` and `taxCents` filled in. */
+    lines: TransactionLine[];
+    totals: TransactionTotals;
+}
+/**
+ * The four steps, plus the one thing they leave open: VAT per line.
+ *
+ * The group amount from step 3 is handed back to its own lines with {@link allocate}, so
+ * `sum(line.taxCents) === totals.taxCents` exactly. A journal entry books VAT per line, and a
+ * split that is off by a cent is a journal entry that does not balance.
+ *
+ * `overrideKey` is the "reverse charge / exempt" tick on the transaction: it replaces every line's
+ * rate, because that is a property of the sale and not of the product.
+ */
+export declare function transactionTotals(lines: readonly TransactionLine[], rates: readonly TaxRate[], overrideKey?: string): PricedTransaction;

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

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

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

@@ -0,0 +1,38 @@
+import { Transaction } from './types';
+/** A transaction with `issuedAt` is frozen. One question, one answer, one place. */
+export declare function isFrozen(transaction: Pick<Transaction, "issuedAt">): boolean;
+/**
+ * What a frozen transaction still accepts.
+ *
+ * `status`, `fileRef` and `dunning` are what happens *to* a document after it left. `number` and
+ * `externalIds` are there because Moneybird, Exact and AFAS issue the invoice number themselves
+ * and it arrives after issuing — a freeze rule that refuses that forces the bookkeeping bridge
+ * into a second column, and then the real invoice number is not on the invoice. `postedAt` is the
+ * push marking its own work done.
+ *
+ * Everything else is a `BadRequestError`. Whoever wants to change a sent quote gets v2.
+ */
+export declare const FROZEN_WRITABLE_FIELDS: readonly (keyof Transaction)[];
+/** The fields a draft carries over; the server owns id, organisation and author. */
+export type TransactionDraft = Omit<Transaction, "id" | "organizationId" | "createdBy" | "createdAt" | "updatedAt">;
+/**
+ * The conversion: quote -> order -> invoice -> credit note, as one function.
+ *
+ * Amounts are not copied but recomputed by the caller (`transactionTotals`), because the target
+ * kind may invert them. Inverting happens on **`quantity`** and not on the price, so the one
+ * formula in `lineNet` keeps holding and a negative amount stays the outcome of a calculation
+ * rather than a second code path.
+ *
+ * What is deliberately dropped: the number, the issue date, the file, the external ids and the
+ * dunning history. Those belong to the document that went out, and this is a new one.
+ */
+export declare function copyFrom(source: Transaction, kindKey: string): TransactionDraft;
+/**
+ * The next version of the same quote.
+ *
+ * Whoever wants to change a sent quote does not edit it: the previous one stays, read-only, and
+ * stays retrievable — because that is what the customer saw. Easy to build, painful to introduce
+ * afterwards: without this rule you have, a year from now, a quote that was changed after it was
+ * signed and no way left to see that.
+ */
+export declare function nextVersion(source: Transaction): TransactionDraft;

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

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

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

@@ -0,0 +1,71 @@
+import { DocumentBlock } from '../../platform/document-blocks';
+import { DocumentSlots, TemplateContext } from '../document-template/tokens';
+import { TaxRate } from '../money/tax';
+import { Transaction } from './types';
+/**
+ * The seam between a transaction and the paper it is printed on.
+ *
+ * Two functions and no renderer. The block order lives in a `DocumentTemplate` row, not in code:
+ * the moment it is hardcoded here, the template layer is decoration and every house-style change
+ * is a deploy. What a template *cannot* express is the line table and the totals — a token
+ * replaces text, it cannot build a table out of an array — so those arrive as slots.
+ *
+ * The consequence for a second consumer (a work order, a timesheet) is that it costs one context,
+ * one slot function and one seeded template row. No renderer, no screen, no export.
+ */
+/** What a template author addresses. */
+export interface TransactionContextSources {
+    companyName?: string;
+    /** `Company` carries no address today; the token exists so a template survives when it does. */
+    companyCity?: string;
+    contactName?: string;
+    organizationName?: string;
+    /** Who the recipient reads; drives which template row is picked. */
+    locale?: string;
+}
+/**
+ * The tokens: `{customer.name}`, `{quote.number}`, `{totals.gross}`.
+ *
+ * English, like every other identifier in this repo. A token is a **path into data**, not a
+ * sentence — the Dutch on a quote is the text a template author writes around it.
+ *
+ * **The cost price and the margin are not in here, and that is load-bearing.** A template author
+ * writes `{regel.bedrag}` by hand; if a cost ever landed in this object, `{regel.inkoop}` on a
+ * quote would be one typo away from the customer. The shield on the way out of the server
+ * (`transactionView`) is the second lock; this one is the first.
+ */
+export declare function transactionContext(transaction: Transaction, sources?: TransactionContextSources): TemplateContext;
+/**
+ * The blocks a template cannot write itself: the line table and the totals.
+ *
+ * Keyed by the `block_id` the template author puts on an empty placeholder — `lines` and `totals`.
+ * That pairing is a **convention**, not a contract: an author cannot invent a third slot and
+ * expect sales to fill it, because the consumer decides what it hands over.
+ *
+ * Amounts arrive already formatted. The blocks layer never computes; that is the whole reason a
+ * totals row carries a string.
+ */
+export declare function transactionSlots(transaction: Transaction, rates?: readonly TaxRate[], labels?: SlotLabels): DocumentSlots;
+export interface SlotLabels {
+    description: string;
+    quantity: string;
+    unitPrice: string;
+    net: string;
+    tax: string;
+    gross: string;
+}
+export declare const DUTCH_SLOT_LABELS: SlotLabels;
+/**
+ * The default quote template, as a **seed** — not a renderer.
+ *
+ * Note the split inside it: the token **paths** are English because they address data, the
+ * **text** around them is Dutch because a customer reads it.
+ *
+ * The distinction is the whole point of the template layer: this array is written into a
+ * `DocumentTemplate` row the first time an organisation needs one, and from then on the row is
+ * the truth. An administrator moves the terms above the lines and that sticks; nobody deploys.
+ *
+ * The two empty placeholders are the slots {@link transactionSlots} fills. Their `block_id` is
+ * the whole contract.
+ */
+export declare const DEFAULT_QUOTE_TEMPLATE_BLOCKS: DocumentBlock[];

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

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

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

@@ -0,0 +1,5 @@
+export * from './convert';
+export * from './document';
+export * from './keys';
+export * from './kinds';
+export * from './types';

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

@@ -0,0 +1,16 @@
+/**
+ * The scope kinds `apps/sales` owns — **the kinds, not the engine**.
+ *
+ * Every other app in this platform claims concrete nouns: `contact` + `company` (crm),
+ * `interaction` + `activity` (comms), `artifact` + `file` (storage). More importantly a scopeKey
+ * is *stored* — in relation edges, attributes, memory rows, pins. `invoice:412` stays
+ * `invoice:412` even if invoices ever move to a finance app; one branded `sales_document:412`
+ * would mean a backfill across four apps.
+ */
+export declare const TRANSACTION_SCOPE_KINDS: readonly string[];
+export declare const PRODUCT_SCOPE_KIND = "product";
+/** `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;
+/** 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/kinds.d.ts

@@ -0,0 +1,32 @@
+import { TransactionStatus } from './types';
+/**
+ * A kind is a row of flags, not a subclass.
+ *
+ * Switching on `order` and `invoice` later is a row here plus a number series — no second screen,
+ * no second line model, no second renderer. That is the whole reason to build the engine generic
+ * in one go.
+ *
+ * There is no `direction`: everything `apps/sales` issues goes outward. A purchase invoice is not
+ * a sale — no source quote, a different approval flow, a different user — and belongs in a finance
+ * app, on the same type and its own table. A flag that is always `out` in one app and always `in`
+ * in the other is an app boundary, not a flag.
+ */
+export interface TransactionKind {
+    key: string;
+    /** i18n key, not text. */
+    label: string;
+    /** Gets a number from a series when issued. */
+    numbered: boolean;
+    /** Invert amounts: a credit note is an invoice with a minus sign. */
+    signFlip: boolean;
+    statuses: readonly TransactionStatus[];
+}
+export declare const TRANSACTION_KINDS: readonly TransactionKind[];
+/**
+ * The kind for a key, or a safe stand-in.
+ *
+ * Never `undefined`: a stored row with a kind we no longer know must still open. The stand-in is
+ * the conservative one — unnumbered and unflipped, because handing out a number or inverting
+ * amounts on a guess is worse than showing a document with a strange label.
+ */
+export declare function transactionKind(key: string): TransactionKind;

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

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