@opencxh/domain 1.235.0 → 1.238.0

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

@@ -39,6 +39,8 @@ export interface Company {
     phone?: string;
     website?: string;
     notes?: string;
+    /** The language to write to this company in. The rung under {@link Contact.locale}. */
+    locale?: string;
 }
 /** What a resolve returns: which company, and how we got there. */
 export interface CompanyMatch {

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

@@ -47,6 +47,14 @@ export interface Contact {
     keys?: string[];
     /** Namespaced source references (`ms:AAMk…`, `google:people/c123`, `hubspot:42`). */
     externalIds?: string[];
+    /**
+     * The language to write to this person in (`nl`, `en`).
+     *
+     * On the contact and not only on the company, because a Dutch company has a German buyer often
+     * enough to matter. Absent means "no answer here" and the reader falls to the next rung — see
+     * `recipientLocale`.
+     */
+    locale?: string;
     origin?: ContactOrigin;
     /** When a shadow row last saw its source. There is no refresh job; touching refreshes. */
     syncedAt?: number;

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

@@ -0,0 +1,3 @@
+export * from './locale';
+export * from './tokens';
+export * from './types';

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

@@ -0,0 +1,38 @@
+/**
+ * Which language to write to somebody in, and which template row that means.
+ *
+ * Three rungs, and the figure is the same one this platform uses everywhere: the most specific
+ * answer that exists wins, whole.
+ *
+ * | Rung | Says |
+ * |---|---|
+ * | the contact | this person reads German |
+ * | the company | this customer is Dutch |
+ * | the organisation | what we write by default |
+ *
+ * Without it somebody picks a language by hand on every letter, and sooner or later a Dutch
+ * final notice lands at a German customer.
+ */
+export interface RecipientLocaleSources {
+    /** `Contact.locale` — the person. */
+    contactLocale?: string;
+    /** `Company.locale` — the customer. */
+    companyLocale?: string;
+    /** The organisation's own language. The floor; there is nothing under it. */
+    organizationLocale?: string;
+}
+export declare function recipientLocale(sources: RecipientLocaleSources): string | undefined;
+/** The minimum a template row has to carry to be picked. */
+export interface LocalizedTemplate {
+    key: string;
+    locale?: string;
+    archived?: boolean;
+}
+/**
+ * The template for this key in this language, or the nearest thing that exists.
+ *
+ * A reminder written only in Dutch still has to go out to a German customer — in Dutch. Returning
+ * nothing there would mean no letter at all, which is worse than the wrong language. The order is
+ * therefore: the language asked for, the organisation's own, then whatever is there.
+ */
+export declare function pickTemplate<T extends LocalizedTemplate>(templates: readonly T[], key: string, locale?: string, organizationLocale?: string): T | undefined;

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

@@ -0,0 +1,39 @@
+import { DocumentBlock } from '../../platform/document-blocks';
+import { TemplateCondition } from './types';
+/** A flat or nested plain object. Arrays resolve by index: `regels.0.naam`. */
+export type TemplateContext = Record<string, unknown>;
+/** Walk a dotted path. Returns `undefined` for anything the path does not reach. */
+export declare function lookup(context: TemplateContext, path: string): unknown;
+export interface FillResult {
+    text: string;
+    /** Paths that resolved to nothing, in the order they appeared. Deduplicated. */
+    unresolved: string[];
+}
+/** One string, filled in. */
+export declare function fillText(text: string, context: TemplateContext): FillResult;
+/** Does this block appear? A block with no condition always does. */
+export declare function conditionHolds(condition: TemplateCondition | undefined, context: TemplateContext): boolean;
+export interface FillDocumentResult {
+    blocks: DocumentBlock[];
+    unresolved: string[];
+}
+/**
+ * Blocks the caller computes, keyed by the `block_id` of the template block they replace.
+ *
+ * The one thing a token cannot say: *"the lines go here"*. A quote's line table and its totals are
+ * derived from the document, not written by the template author — so the author places an empty
+ * `table` with `block_id: "lines"` and the caller hands over what belongs there.
+ *
+ * Deliberately a replacement and not a repetition primitive: a loop would need an expression
+ * language to say what it loops over, and the caller already holds the data.
+ */
+export type DocumentSlots = Record<string, readonly DocumentBlock[]>;
+/**
+ * A whole template, filled in: conditions applied, slots substituted, tokens replaced everywhere
+ * 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}`
+ * 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/tokens.test.d.ts

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

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

@@ -0,0 +1,87 @@
+import { DocumentBlock } from '../../platform/document-blocks';
+/**
+ * A document template: the blocks a generated document is built from.
+ *
+ * A work order, a quote, a first reminder, a final notice. What it is **not** is the letterhead
+ * and the footer — those are the organisation's house style, drawn around every document, so a
+ * change to the address does not mean editing six templates.
+ *
+ * See `plans/DOCUMENTS-2026-09-14.md` §7.
+ */
+export interface DocumentTemplate {
+    id: string;
+    organizationId: string;
+    /** `quote`, `invoice`, `reminder_1`, `reminder_final`, `work_order`… Unique per language. */
+    key: string;
+    name: string;
+    description?: string;
+    /**
+     * Which document kind may use it. Absent = free-standing (a letter, a work order).
+     *
+     * A string and not a union: the kinds live in `apps/sales` and this app must not need to know
+     * them to store one.
+     */
+    documentKindKey?: string;
+    /** The body. Plain document blocks — the same thing the editor and the renderer already speak. */
+    blocks: DocumentBlock[];
+    /**
+     * Which blocks only appear sometimes, keyed by `block_id`.
+     *
+     * **Beside the blocks, not wrapped around them.** A condition is part of the template, not of
+     * the document: keeping it out of the block means the editor, the renderer and the markdown
+     * export need to know nothing about it, and a template's body stays a thing any of them can
+     * open. A block with no entry here always appears.
+     */
+    conditions?: Record<string, TemplateCondition>;
+    /**
+     * The language this template is written in.
+     *
+     * A Dutch reminder and its English version are **two rows**, tied by
+     * {@link DocumentTemplate.translationGroupId} — exactly how `KbArticle` does it, and for the
+     * same reason: a per-key text map cannot carry a translated table, and a translated list is not
+     * a string. The price is that the structure can drift between languages; the alternative is a
+     * mechanism that cannot express half the documents.
+     */
+    locale?: string;
+    /** Ties the language versions together. Defaults to the template's own id. */
+    translationGroupId?: string;
+    isDefault?: boolean;
+    archived?: boolean;
+    createdBy: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * When a block appears.
+ *
+ * Three operators and no expression language. "Show the direct-debit paragraph when the customer
+ * pays by direct debit" is the whole job; anything past that is a rule, and a rule belongs in the
+ * app that decides it.
+ */
+export interface TemplateCondition {
+    /** A path into the same context the tokens read: `klant.incasso`. */
+    key: string;
+    /** Show when the value equals this. */
+    equals?: unknown;
+    /** Show when the value is present (`true`) or absent (`false`). */
+    exists?: boolean;
+}
+/**
+ * The organisation's paper: what is drawn around every document, whichever template made it.
+ *
+ * Three fields, and the shortness is the point. The logo, the address and the VAT/KvK numbers are
+ * **not** here — they are already on the organisation (`logo`, `address`, `billing`), and a second
+ * copy is the one that goes stale. What is left is what a document needs and nothing here had.
+ */
+export interface OrganizationHouseStyle {
+    /** Hex, for the rules and the heading accents. */
+    accentColor?: string;
+    /** The line under every document. */
+    footerText?: string;
+    /**
+     * The account to pay into. The one identifier a letter needs that this platform did not already
+     * have — the VAT and chamber-of-commerce numbers live on `Organization.billing`, and a second
+     * copy is the one that goes stale.
+     */
+    iban?: string;
+}

package/dist/entities/kb/locales.d.ts

@@ -1,35 +1,9 @@
-import { KbLocale } from './types';
 /**
- * Languages a knowledge base can be authored in.
+ * The language list under its knowledge-base names.
  *
- * Deliberately **not** the shell's UI locale list. That one is a hardcoded
- * `['nl','en']` in `LocalizationManager`, and a customer publishing a German
- * help centre has nothing to do with which language our own buttons are in.
- *
- * The labels are endonyms — a language names itself the same way whoever reads
- * the picker. So this is a fixed map on purpose, and not the "never freeze
- * labels at module load" case the design system warns about.
- *
- * In domain rather than in the kb app because both ends need the same answer:
- * the language picker in the editor, and the writing assistant's system prompt,
- * which has to name the language it must write in. Two copies would drift, and
- * the way you would find out is an article coming back in the wrong language.
- */
-export interface KbLocaleOption {
-    code: KbLocale;
-    /** The language's own name, for a picker. */
-    label: string;
-    /** Its English name, for telling a model which language to write in. */
-    english: string;
-}
-export declare const KB_LOCALES: KbLocaleOption[];
-/** The language's own name, or the bare code for one we do not list. */
-export declare function localeName(code: string): string;
-/**
- * How to name this language to a model.
- *
- * A bare BCP-47 tag is a weak instruction — `"nl"` inside an otherwise English
- * prompt is not enough to stop a model answering in English. Both names plus
- * the tag leaves nothing to infer.
+ * It moved to `platform/locales.ts` when a second caller appeared: a contact and a company now
+ * carry the language to write to them in, and `apps/crm` importing something called `KB_LOCALES`
+ * reads like a mistake. These aliases exist so the nineteen files in `apps/kb` that use the old
+ * names keep working unchanged.
  */
-export declare function localeInstruction(code: string): string;
+export { LOCALES as KB_LOCALES, type LocaleOption as KbLocaleOption, localeInstruction, localeName, } from '../../platform/locales';

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

@@ -1,3 +1,4 @@
+import { DocumentBlock } from '../../platform/document-blocks';
 /** A language a knowledge base publishes in, e.g. `nl`, `en`, `de`. */
 export type KbLocale = string;
 export interface KnowledgeBase {
@@ -62,7 +63,15 @@ export interface KbArticle {
     knowledgeBaseId: string;
     categoryId?: string;
     title: string;
+    /**
+     * The article as document blocks — the source of truth. Absent on a row written before the
+     * store moved to blocks; readers fall back to parsing {@link KbArticle.body}.
+     */
+    blocks?: DocumentBlock[];
+    /** The same article as markdown. Derived on write, never parsed back. */
     body: string;
+    /** The same article as plain text: what the embedding and the keyword score read. */
+    text?: string;
     status: "draft" | "published";
     authorId?: string;
     order: number;

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

@@ -1,3 +1,4 @@
+import { OrganizationHouseStyle } from '../document-template/types';
 import { OrganizationProfile } from './profile';
 export interface OrganizationAddress {
     street?: string;
@@ -40,6 +41,13 @@ export interface Organization {
      * which steps apply and what to propose. See `profile.ts`.
      */
     profile?: OrganizationProfile;
+    /**
+     * What is drawn around every generated document — accent, footer, KvK/VAT/IBAN.
+     *
+     * The logo and the address are not in here: they are fields of their own on this record, and a
+     * document reads them from there. See `OrganizationHouseStyle`.
+     */
+    houseStyle?: OrganizationHouseStyle;
     /** Small company logo stored inline as a base64 data-URI. */
     logo?: string;
     /**