@opencxh/domain 1.248.0 → 1.249.0

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

@@ -45,6 +45,14 @@ export interface Company {
      * recipient block is the first, and the issue gate refuses a document with a hole in it.
      */
     address?: PostalAddress;
+    /**
+     * This customer's default payment condition, as a code `apps/sales` owns.
+     *
+     * An opaque key, exactly like {@link Company.locale} is an opaque language: crm stores it and
+     * never interprets it. It is a default and not a rule — a document copies the condition when it
+     * is created and keeps it from then on, so changing this never rewrites what already went out.
+     */
+    paymentTermCode?: string;
     /** Raw, human-readable phone/website as entered, for display. */
     phone?: string;
     website?: string;

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

@@ -23,8 +23,8 @@ export type TransactionDraft = Omit<Transaction, "id" | "organizationId" | "crea
  * 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.
+ * What is deliberately dropped: the number, the issue date, the due 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;
 /**

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

@@ -1,5 +1,6 @@
 import { DocumentBlock } from '../../platform/document-blocks';
 import { DocumentSlots, TemplateContext } from '../document-template/tokens';
+import { TemplateCondition } from '../document-template/types';
 import { TaxRate } from '../money/tax';
 import { PostalAddress } from '../organization/types';
 import { Transaction } from './types';
@@ -59,7 +60,7 @@ export interface SlotLabels {
 }
 export declare const DUTCH_SLOT_LABELS: SlotLabels;
 /**
- * The default quote template, as a **seed** — not a renderer.
+ * The default template for one kind, 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.
@@ -68,7 +69,18 @@ export declare const DUTCH_SLOT_LABELS: SlotLabels;
  * `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.
  *
+ * Built per kind rather than one constant, because the tokens are namespaced by the kind key —
+ * an invoice seeded with `{quote.number}` renders a hole where its number should be. The
+ * head fields differ too: a quote is valid until, an invoice falls due.
+ *
  * The two empty placeholders are the slots {@link transactionSlots} fills. Their `block_id` is
  * the whole contract.
  */
+export declare function defaultTemplateBlocks(kindKey: string): DocumentBlock[];
+/** The conditions a seeded template ships with: a block that is empty does not appear. */
+export declare const DEFAULT_TEMPLATE_CONDITIONS: (kindKey: string) => Record<string, TemplateCondition>;
+/**
+ * The quote seed, kept as a constant because it is what every existing organisation was seeded
+ * with — and what the tests pin.
+ */
 export declare const DEFAULT_QUOTE_TEMPLATE_BLOCKS: DocumentBlock[];

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

@@ -2,4 +2,6 @@ export * from './convert';
 export * from './document';
 export * from './keys';
 export * from './kinds';
+export * from './number-series';
+export * from './payment-term';
 export * from './types';

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

@@ -20,8 +20,38 @@ export interface TransactionKind {
     /** Invert amounts: a credit note is an invoice with a minus sign. */
     signFlip: boolean;
     statuses: readonly TransactionStatus[];
+    /**
+     * The route segment this kind lives under: `quotes`, `orders`, `invoices`.
+     *
+     * A field and not `${key}s`: a credit note is filed with the invoices, and string arithmetic on
+     * a key is how you end up with `/credit_notes` that nobody registered.
+     */
+    path: string;
+    /**
+     * Where it lands when issued.
+     *
+     * A row rather than an `if` in the handler — and it fixes a bug that is live today: the issue
+     * handler writes `status: "sent"` for everything, and `sent` is not in the status list of an
+     * invoice or a credit note.
+     */
+    issuedStatus: TransactionStatus;
 }
 export declare const TRANSACTION_KINDS: readonly TransactionKind[];
+/**
+ * Which kinds the app actually offers today.
+ *
+ * Here and not in the server app, because both sides need the same answer and two lists drift:
+ * the save handler refuses what is not in here, and the navigation column draws a row for what is.
+ * A product decision, like the kinds themselves — §12.4: *"transactiesoorten zijn van ons, niet
+ * van de organisatie"*.
+ *
+ * `credit_note` is deliberately absent. Crediting an invoice is its own small feature — which
+ * lines, partial credits, the reference back — and a kind you can create but not fill correctly is
+ * worse than one you cannot create at all.
+ */
+export declare const ENABLED_TRANSACTION_KINDS: readonly string[];
+/** The kinds a reader can browse, one per route segment. A credit note files with the invoices. */
+export declare function listedTransactionKinds(): TransactionKind[];
 /**
  * The kind for a key, or a safe stand-in.
  *

package/dist/entities/transaction/number-series.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The running number behind an invoice.
+ *
+ * One row per (administration, kind), and that row **is** the counter — there is no kv mirror and
+ * no cold-start reseed. `apps/work/server/src/item/sequence.ts` needs both because its counter
+ * lives on a project row it does not want to write on every issue; this row exists for nothing
+ * else, so writing it every time is the cheap answer.
+ *
+ * What is copied from work verbatim, because it was learned the hard way there:
+ *
+ * - **The lock is the optimisation; the unique index is the guarantee.** `Bridge.kv` has no
+ *   compare-and-swap, so a serialised read-modify-write is a speed bump. The unique index on
+ *   `(organizationId, businessEntityId, number)` is what actually refuses a duplicate.
+ * - **Gaps are accepted.** A number drawn for a write that then fails is burned. Nothing in the
+ *   product may derive a count from the highest number.
+ */
+export interface NumberSeries {
+    id: string;
+    organizationId: string;
+    /**
+     * Which administration. A series never reaches across one — two administrations each have a
+     * right to invoice 0001, which is exactly what the unique index is scoped to.
+     */
+    businessEntityId: string;
+    /** `invoice`, `credit_note`. One per kind: a bookkeeper reads them as separate books. */
+    kindKey: string;
+    /** What comes in front: `F`, or nothing. The year is not a prefix — that is the period. */
+    prefix: string;
+    /** `year` starts again at 1 in January; `never` runs on. */
+    resetOn: NumberSeriesReset;
+    /** Digits the counter is padded to. `4` → `0001`. */
+    padding: number;
+    /** The period the counter is in: `"2027"`, or `""` when it never resets. */
+    period: string;
+    /** The number the next document gets. */
+    next: number;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+export type NumberSeriesReset = "year" | "never";
+/** Four digits and a yearly reset: the Dutch default, and what a seeded series starts on. */
+export declare const DEFAULT_NUMBER_PADDING = 4;
+/**
+ * `F2027-0001`.
+ *
+ * Pure, so a settings screen can show the format **before** the first invoice goes out — after
+ * that it is fixed, and a format nobody previewed is a format somebody finds out about from a
+ * customer.
+ *
+ * `padStart` never truncates, so a counter that outgrows its padding simply gets longer. Losing a
+ * digit would make two invoices share a number, which the index would then refuse — a numbering
+ * scheme has to bend rather than break.
+ */
+export declare function formatSeriesNumber(series: Pick<NumberSeries, "prefix" | "period" | "padding">, sequence: number): string;
+/** The period a series should be in right now. `""` when it never resets. */
+export declare function currentPeriod(resetOn: NumberSeriesReset, at?: number): string;

package/dist/entities/transaction/number-series.test.d.ts

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

package/dist/entities/transaction/payment-term.d.ts

@@ -0,0 +1,80 @@
+/**
+ * How and when a document is paid.
+ *
+ * A table, not an engine — the same shape as `TaxRate`, and for the same reason: a document refers
+ * to a condition **by code**, never by its wording, so renaming "Binnen 14 dagen" does not rewrite
+ * what a customer already received.
+ */
+export type PaymentTermMethod = "cash" | "credit" | "direct_debit" | "card" | "other";
+/**
+ * `PaymentTermMethod` and not `PaymentMethod`: that name is taken by
+ * `entities/organization/billing.ts` for the card or mandate **we** charge a customer's
+ * subscription on. Two different questions — how our customer pays us, and how their customer
+ * pays them — and one of them had the name first.
+ */
+export declare const PAYMENT_TERM_METHODS: readonly PaymentTermMethod[];
+export interface PaymentTerm {
+    id: string;
+    organizationId: string;
+    /**
+     * Empty = shared with every administration; an administration's own row shadows it on `code`.
+     * Exactly how `TaxRate` works, so there is one rule to learn instead of two.
+     */
+    businessEntityId?: string;
+    /** Stable and fixed once it exists — documents point at it. `14D`, `CONTANT`, `INCASSO`. */
+    code: string;
+    /** What the customer reads. Plain text, not an i18n key: an organisation writes its own. */
+    label: string;
+    method: PaymentTermMethod;
+    /** Days after issue until it falls due. `0` is payable immediately. */
+    dueDays: number;
+    /** The one a new document starts with when neither the request nor the customer says. */
+    isDefault?: boolean;
+    archived?: boolean;
+    order?: number;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * The due date of a document issued at `issuedAt` under a term of `dueDays`.
+ *
+ * Whole days on the clock, deliberately not calendar arithmetic: an invoice issued at 23:00 falls
+ * due 30×24 hours later and nobody has ever argued about the hour. Doing it in local calendar days
+ * would make the answer depend on which timezone the server happened to be in.
+ */
+export declare function dueDateFrom(issuedAt: number, dueDays: number): number;
+/**
+ * The term that applies, out of the shared table and one administration's own.
+ *
+ * Shared rows first, then the administration's over them, by code — the same `shadowByKey` the VAT
+ * table uses. Kept in domain rather than in the app because both the server and the screen have to
+ * land on the same answer.
+ */
+export declare function shadowTermsByCode(rows: readonly PaymentTerm[], businessEntityId?: string): PaymentTerm[];
+/**
+ * The condition as it was copied onto a document.
+ *
+ * One object and not four columns: it is one concept, `dueAt` needs `dueDays` at issue time, and
+ * a `Transaction` already keeps `lines`, `totals` and `source` this way. Nothing queries on a
+ * payment condition, which is the only thing a flat column would buy.
+ */
+export interface TransactionPaymentTerm {
+    code: string;
+    label: string;
+    method: PaymentTermMethod;
+    dueDays: number;
+}
+/** What a term looks like once it is on a document. */
+export declare function toTransactionTerm(term: PaymentTerm): TransactionPaymentTerm;
+/**
+ * The Dutch starting set, seeded on first read.
+ *
+ * Seeded and not hardcoded, exactly like `NL_TAX_RATES`: these three cover the practice and an
+ * organisation that needs a fourth may not have to wait for a deploy.
+ *
+ * The labels are **plain text and not i18n keys**, unlike the tax table. They are printed on the
+ * paper by the server, which has no `t()` in hand — and an organisation that writes to Germany
+ * edits three rows rather than waiting for a translation it cannot supply.
+ */
+export declare const NL_PAYMENT_TERMS: readonly Omit<PaymentTerm, "id" | "organizationId" | "createdBy">[];

package/dist/entities/transaction/payment-term.test.d.ts

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

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

@@ -1,5 +1,6 @@
 import { Cents } from '../money/money';
 import { OwnerScope } from '../scope/types';
+import { TransactionPaymentTerm } from './payment-term';
 /**
  * The engine: a quote, an order, an invoice, a credit note.
  *
@@ -54,8 +55,41 @@ export interface Transaction {
     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.
+     *
+     * Declared in phase 0 and dead until phase 5: nothing wrote them and the document layer did not
+     * read them. They are the "opmerking" a person types on a document, and they render through
+     * `{<kind>.note}` and `{<kind>.terms}`.
+     */
     introText?: string;
     termsText?: string;
+    /**
+     * Which payment condition applied, **copied** at save — code, wording, method and days.
+     *
+     * Copied and not looked up, for the same reason a line copies its product name: a condition that
+     * is renamed or retired next year must not rewrite an invoice that already went out. The days
+     * ride along because the due date is computed at issue, and by then the row may be gone.
+     */
+    paymentTerm?: TransactionPaymentTerm;
+    /**
+     * 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`.
+     */
+    dueAt?: number;
+    /** When it was delivered. Set by a person; we have no way of knowing. */
+    deliveredAt?: number;
+    /**
+     * The service period this document covers: *"Periode 01-01-2027 t/m 31-03-2027"*.
+     *
+     * Empty on a one-off sale, filled on anything periodic — which is what a subscription invoice
+     * is. The field is here now rather than with `Agreement` in phase 6 because it passes the test
+     * from the plan: it records a **moment** that a frozen invoice states and that cannot be
+     * reconstructed afterwards. Which quarter was billed is not derivable from a contract that has
+     * since been changed or ended.
+     */
+    periodFrom?: number;
+    periodTo?: number;
     /** Epoch ms. `issuedAt` set = frozen. */
     issuedAt?: number;
     expiresAt?: number;