@managemint-solutions/sdk 0.56.0 → 0.65.0

package/dist/documents/content.js

@@ -0,0 +1,443 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IsDocumentNumberPrefix = exports.IsDocumentCategory = exports.IsDocumentCurrency = exports.IsDocumentVariableValues = exports.IsDocumentBlocks = exports.IsDocumentVariables = exports.documentProblem = exports.currencyProblem = exports.variableValuesProblem = exports.blocksProblem = exports.variablesProblem = exports.IMAGE_PATH = exports.IMAGE_EXTENSIONS = void 0;
+const enum_1 = require("@managemint-solutions/entities/documents/enum");
+const enum_2 = require("@managemint-solutions/entities/supporting-files/enum");
+const validators_1 = require("../validators");
+const values_1 = require("./render/values");
+// The rules a template's and a document's content is held to - its variables, its blocks, the
+// values filled in and the currency - written once and used by every DTO that carries them.
+// Each check returns the first problem it finds as the message the caller sees, or null, so a
+// 400 always says exactly what is wrong and where ("Block 2 (line items): Line 1: ...").
+// Blocks and variables are stored as JSON with no SQL checks, so these are the only gate.
+/** The image types an image block may show - the image types supporting files accept. */
+exports.IMAGE_EXTENSIONS = new Set([
+    enum_2.SupportingFilesExtensions.PNG,
+    enum_2.SupportingFilesExtensions.JPG,
+    enum_2.SupportingFilesExtensions.JPEG,
+    enum_2.SupportingFilesExtensions.GIF,
+]);
+/** The path `documents.createImageUploadUrl` hands out, relative to the organization's folder. */
+exports.IMAGE_PATH = new RegExp(`^documents/images/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\\.(${[...exports.IMAGE_EXTENSIONS].join('|')})$`);
+const KEY = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$/;
+const CURRENCY = /^[A-Z]{3}$/;
+const NUMBER_PREFIX = /^[A-Za-z0-9/_.-]*$/;
+const MAX_KEY_LENGTH = 40;
+const MAX_VARIABLES = 100;
+const MAX_BLOCKS = 200;
+/** Variable labels, field labels, column headers, signer labels, image alt text, each side of a header or footer. */
+const MAX_LABEL_LENGTH = 200;
+/** Field values, table cells, line descriptions. */
+const MAX_TEXT_LENGTH = 2000;
+/** A text variable's value, and one run of rich text. */
+const MAX_LONG_TEXT_LENGTH = 10000;
+const MAX_LINK_LENGTH = 2000;
+/** Rich text levels: doc, list, item, list, item ... - deep enough for lists four levels in. */
+const MAX_RICH_TEXT_DEPTH = 10;
+/** A columns block's columns: "Bill from" and "Bill to", with room for a third. */
+const MIN_SIDE_COLUMNS = 2;
+const MAX_SIDE_COLUMNS = 3;
+const MAX_CATEGORY_LENGTH = 50;
+const MAX_NUMBER_PREFIX_LENGTH = 10;
+const SYSTEM_VARIABLES = new Set(Object.values(enum_1.DocumentSystemVariable));
+/** Printed per PDF page, so they mean something only in the header and footer. */
+const PAGE_VARIABLES = new Set([enum_1.DocumentSystemVariable.PAGE_NUMBER, enum_1.DocumentSystemVariable.PAGE_COUNT]);
+const PAGE_VARIABLES_ONLY = 'Page number and page count only work in a header or footer';
+const VARIABLE_TYPES = new Set(Object.values(enum_1.DocumentVariableType));
+const BLOCK_LABELS = {
+    [enum_1.DocumentBlockType.TEXT]: 'text',
+    [enum_1.DocumentBlockType.FIELDS]: 'fields',
+    [enum_1.DocumentBlockType.LINE_ITEMS]: 'line items',
+    [enum_1.DocumentBlockType.TABLE]: 'table',
+    [enum_1.DocumentBlockType.SIGNATURE]: 'signature',
+    [enum_1.DocumentBlockType.IMAGE]: 'image',
+    [enum_1.DocumentBlockType.PAGE_BREAK]: 'page break',
+    [enum_1.DocumentBlockType.HEADER]: 'header',
+    [enum_1.DocumentBlockType.FOOTER]: 'footer',
+    [enum_1.DocumentBlockType.COLUMNS]: 'columns',
+};
+/** The properties each block carries beside `id` and `type` - nothing else is stored. */
+const BLOCK_PROPERTIES = {
+    [enum_1.DocumentBlockType.TEXT]: ['content'],
+    [enum_1.DocumentBlockType.FIELDS]: ['fields'],
+    [enum_1.DocumentBlockType.LINE_ITEMS]: ['items'],
+    [enum_1.DocumentBlockType.TABLE]: ['columns', 'rows'],
+    [enum_1.DocumentBlockType.SIGNATURE]: ['signers'],
+    [enum_1.DocumentBlockType.IMAGE]: ['path', 'alt'],
+    [enum_1.DocumentBlockType.PAGE_BREAK]: [],
+    [enum_1.DocumentBlockType.HEADER]: ['left', 'right'],
+    [enum_1.DocumentBlockType.FOOTER]: ['left', 'right'],
+    [enum_1.DocumentBlockType.COLUMNS]: ['columns'],
+};
+/** How many of each a block may hold. */
+const MAX_FIELDS = 100;
+const MAX_LINES = 200;
+const MAX_COLUMNS = 12;
+const MAX_ROWS = 500;
+const MAX_SIGNERS = 10;
+// Rich text: the editor's ProseMirror JSON, limited to what the api's renderer prints. Each node
+// may hold only its listed properties and only the listed children. Attributes are checked where
+// they matter (a heading's level, a variable's key, a link's href); any other attribute the
+// editor writes is stored and never rendered.
+const BLOCK_NODES = new Set(['paragraph', 'heading', 'bulletList', 'orderedList']);
+const INLINE_NODES = new Set(['text', 'hardBreak', 'variable']);
+const LIST_ITEMS = new Set(['listItem']);
+const DOC = new Set(['doc']);
+const RICH_TEXT_NODES = new Map([
+    ['doc', { properties: ['content'], children: BLOCK_NODES }],
+    ['paragraph', { properties: ['content', 'attrs'], children: INLINE_NODES }],
+    ['heading', { properties: ['content', 'attrs'], children: INLINE_NODES }],
+    ['bulletList', { properties: ['content', 'attrs'], children: LIST_ITEMS }],
+    ['orderedList', { properties: ['content', 'attrs'], children: LIST_ITEMS }],
+    ['listItem', { properties: ['content', 'attrs'], children: BLOCK_NODES }],
+    ['text', { properties: ['text', 'marks'] }],
+    ['hardBreak', { properties: ['marks'] }],
+    ['variable', { properties: ['attrs', 'marks'] }],
+]);
+const MARKS = new Set(['bold', 'italic', 'underline', 'link']);
+/** A property of `value` that is not one of `allowed`, as the message naming it. */
+const unexpected = (value, allowed) => {
+    const extra = Object.keys(value).find((key) => !allowed.includes(key));
+    return extra === undefined ? null : `Unexpected property "${extra}"`;
+};
+/** The declared variables' types by key - what references are resolved against. */
+const declaredTypes = (variables) => new Map((Array.isArray(variables) ? variables : [])
+    .filter((variable) => (0, values_1.isObject)(variable) && typeof variable.key === 'string')
+    .map((variable) => [variable.key, variable.type]));
+/** Whether a value fits its variable's type, as the rest of a sentence ("must be a number"). */
+const valueProblem = (type, value) => {
+    switch (type) {
+        case enum_1.DocumentVariableType.TEXT:
+            if (typeof value !== 'string')
+                return 'must be text';
+            return value.length > MAX_LONG_TEXT_LENGTH ? `cannot exceed ${MAX_LONG_TEXT_LENGTH} characters` : null;
+        case enum_1.DocumentVariableType.NUMBER:
+            return typeof value === 'number' && Number.isFinite(value) ? null : 'must be a number';
+        case enum_1.DocumentVariableType.MONEY:
+            return Number.isSafeInteger(value) && value >= 0 ? null : 'must be a whole number of cents, 0 or more';
+        default:
+            return (0, validators_1.isCalendarDate)(value) ? null : 'must be a date (YYYY-MM-DD)';
+    }
+};
+/** Plain text in a block: a string of at most `max` characters whose `{{key}}`s all resolve. */
+const textProblem = (value, what, max, known) => {
+    if (typeof value !== 'string')
+        return `${what} must be text`;
+    if (value.length > max)
+        return `${what} cannot exceed ${max} characters`;
+    for (const [, key] of value.matchAll(values_1.DOCUMENT_VARIABLE_PATTERN)) {
+        if (!known(key))
+            return PAGE_VARIABLES.has(key) ? PAGE_VARIABLES_ONLY : `${what} uses an unknown variable {{${key}}}`;
+    }
+    return null;
+};
+/** A list of up to `max` entries, each checked by `check` and named by its position. */
+const listProblem = (value, plural, singular, max, check) => {
+    if (!Array.isArray(value))
+        return `Expected a list of ${plural}`;
+    if (value.length > max)
+        return `Cannot have more than ${max} ${plural}`;
+    for (const [index, entry] of value.entries()) {
+        const problem = check(entry);
+        if (problem)
+            return `${singular} ${index + 1}: ${problem}`;
+    }
+    return null;
+};
+/** An object holding exactly `properties`, each checked in turn. */
+const entryProblem = (entry, properties, ...checks) => {
+    if (!(0, values_1.isObject)(entry))
+        return 'Must be an object';
+    const extra = unexpected(entry, properties);
+    if (extra)
+        return extra;
+    for (const check of checks) {
+        const problem = check();
+        if (problem)
+            return problem;
+    }
+    return null;
+};
+const percentProblem = (value, what) => typeof value === 'number' && value >= 0 && value <= 100 ? null : `${what} must be a percentage from 0 to 100`;
+/**
+ * A line's quantity or unit price: a number written in, or `{ variable }` naming a declared
+ * variable of `type` (a number for the quantity, money for the price).
+ */
+const amountProblem = (value, what, type, declared, rule) => {
+    if (typeof value === 'number')
+        return rule.holds(value) ? null : `${what} ${rule.message}`;
+    if (!(0, values_1.isObject)(value) || typeof value.variable !== 'string' || Object.keys(value).length !== 1) {
+        return `${what} must be a number or a variable`;
+    }
+    if (declared.get(value.variable) === type)
+        return null;
+    if (PAGE_VARIABLES.has(value.variable))
+        return PAGE_VARIABLES_ONLY;
+    return declared.has(value.variable) || SYSTEM_VARIABLES.has(value.variable)
+        ? `${what} can only use a ${type} variable`
+        : `${what} uses an unknown variable "${value.variable}"`;
+};
+/** One rich text node and everything under it, placed where only `allowed` may go. */
+const nodeProblem = (node, allowed, depth, known) => {
+    if (!(0, values_1.isObject)(node) || typeof node.type !== 'string')
+        return 'Text holds something that is not text';
+    const rule = RICH_TEXT_NODES.get(node.type);
+    if (!rule)
+        return `Unsupported content "${node.type}"`;
+    if (!allowed.has(node.type))
+        return `"${node.type}" cannot be placed there`;
+    const extra = unexpected(node, ['type', ...rule.properties]);
+    if (extra)
+        return `${extra} on "${node.type}"`;
+    const attrs = node.attrs === undefined ? {} : node.attrs;
+    if (!(0, values_1.isObject)(attrs))
+        return `Attributes of "${node.type}" must be an object`;
+    if (node.type === 'heading' && ![1, 2, 3].includes(attrs.level)) {
+        return 'Heading level must be 1, 2 or 3';
+    }
+    if (node.type === 'variable') {
+        if (typeof attrs.key !== 'string')
+            return 'A variable must name its key';
+        if (!known(attrs.key))
+            return PAGE_VARIABLES.has(attrs.key) ? PAGE_VARIABLES_ONLY : `Unknown variable "${attrs.key}"`;
+    }
+    if (node.type === 'text') {
+        if (typeof node.text !== 'string' || node.text === '')
+            return 'A text run must hold text';
+        if (node.text.length > MAX_LONG_TEXT_LENGTH)
+            return `A text run cannot exceed ${MAX_LONG_TEXT_LENGTH} characters`;
+    }
+    if (node.marks !== undefined) {
+        if (!Array.isArray(node.marks))
+            return 'Formatting must be a list';
+        for (const mark of node.marks) {
+            if (!(0, values_1.isObject)(mark) || typeof mark.type !== 'string' || !MARKS.has(mark.type)) {
+                return `Unsupported formatting "${(0, values_1.isObject)(mark) ? String(mark.type) : mark}"`;
+            }
+            const markExtra = unexpected(mark, ['type', 'attrs']);
+            if (markExtra)
+                return `${markExtra} on "${mark.type}"`;
+            if (mark.type === 'link') {
+                const href = (0, values_1.isObject)(mark.attrs) ? mark.attrs.href : undefined;
+                if (typeof href !== 'string' || href.length > MAX_LINK_LENGTH || (0, values_1.safeHref)(href) === null) {
+                    return 'Links must start with http://, https:// or mailto:';
+                }
+            }
+        }
+    }
+    if (!rule.children || node.content === undefined)
+        return null;
+    if (!Array.isArray(node.content))
+        return `Content of "${node.type}" must be a list`;
+    if (depth >= MAX_RICH_TEXT_DEPTH)
+        return 'Text is nested too deeply';
+    for (const child of node.content) {
+        const problem = nodeProblem(child, rule.children, depth + 1, known);
+        if (problem)
+            return problem;
+    }
+    return null;
+};
+/**
+ * A template's or document's variables: each `{ key, label, type, required, default_value }`,
+ * keys lower snake_case (1 to 40 characters), unique, never a system variable's, and a default
+ * that fits the type or null.
+ */
+const variablesProblem = (variables) => {
+    if (!Array.isArray(variables))
+        return 'Variables must be a list';
+    if (variables.length > MAX_VARIABLES)
+        return `Cannot have more than ${MAX_VARIABLES} variables`;
+    const keys = new Set();
+    for (const [index, variable] of variables.entries()) {
+        const at = `Variable ${index + 1}`;
+        if (!(0, values_1.isObject)(variable))
+            return `${at} must be an object`;
+        const extra = unexpected(variable, ['key', 'label', 'type', 'required', 'default_value']);
+        if (extra)
+            return `${at}: ${extra}`;
+        const { key, label, type, required } = variable;
+        if (typeof key !== 'string' || key.length > MAX_KEY_LENGTH || !KEY.test(key)) {
+            return `${at}: Key must be lower snake_case, 1 to ${MAX_KEY_LENGTH} characters, such as client_reference`;
+        }
+        if (SYSTEM_VARIABLES.has(key))
+            return `${at}: "${key}" is a system variable and cannot be declared`;
+        if (keys.has(key))
+            return `${at}: Key "${key}" is already used`;
+        keys.add(key);
+        if (typeof label !== 'string' || label.trim() === '' || label.length > MAX_LABEL_LENGTH) {
+            return `${at}: Label must be 1 to ${MAX_LABEL_LENGTH} characters`;
+        }
+        if (typeof type !== 'string' || !VARIABLE_TYPES.has(type)) {
+            return `${at}: Type must be one of ${[...VARIABLE_TYPES].join(', ')}`;
+        }
+        if (typeof required !== 'boolean')
+            return `${at}: Required must be true or false`;
+        if (variable.default_value === undefined)
+            return `${at}: Default value is required (null for none)`;
+        const problem = variable.default_value === null ? null : valueProblem(type, variable.default_value);
+        if (problem)
+            return `${at}: Default value ${problem}`;
+    }
+    return null;
+};
+exports.variablesProblem = variablesProblem;
+/**
+ * A template's or document's blocks: each block's shape for its type, numbers in range, and every
+ * variable it uses - `{{key}}` in plain text, a variable node in rich text, a line's quantity or
+ * price - declared in `variables` or a system variable; `{{page_number}}` and `{{page_count}}` only
+ * in the header and footer, of which a document has at most one each, anywhere in the list.
+ */
+const blocksProblem = (blocks, variables) => {
+    if (!Array.isArray(blocks))
+        return 'Blocks must be a list';
+    if (blocks.length > MAX_BLOCKS)
+        return `Cannot have more than ${MAX_BLOCKS} blocks`;
+    const declared = declaredTypes(variables);
+    const known = (key) => declared.has(key) || (SYSTEM_VARIABLES.has(key) && !PAGE_VARIABLES.has(key));
+    const knownOnEveryPage = (key) => known(key) || PAGE_VARIABLES.has(key);
+    const ids = new Set();
+    const types = new Set();
+    for (const [index, block] of blocks.entries()) {
+        const at = `Block ${index + 1}`;
+        if (!(0, values_1.isObject)(block))
+            return `${at} must be an object`;
+        if (typeof block.type !== 'string' || !Object.hasOwn(BLOCK_LABELS, block.type)) {
+            return `${at}: Type must be one of ${Object.values(enum_1.DocumentBlockType).join(', ')}`;
+        }
+        const type = block.type;
+        const where = `${at} (${BLOCK_LABELS[type]})`;
+        const extra = unexpected(block, ['id', 'type', ...BLOCK_PROPERTIES[type]]);
+        if (extra)
+            return `${where}: ${extra}`;
+        if (typeof block.id !== 'string' || block.id === '' || block.id.length > 64) {
+            return `${where}: Id must be 1 to 64 characters`;
+        }
+        if (ids.has(block.id))
+            return `${where}: Id "${block.id}" is used by another block`;
+        ids.add(block.id);
+        // A header and a footer print on every page, so a second of either has nowhere to go.
+        if ((type === enum_1.DocumentBlockType.HEADER || type === enum_1.DocumentBlockType.FOOTER) && types.has(type)) {
+            return `${where}: A document can have only one ${BLOCK_LABELS[type]}`;
+        }
+        types.add(type);
+        // A page break holds nothing more to check.
+        let problem = null;
+        switch (type) {
+            case enum_1.DocumentBlockType.TEXT:
+                problem =
+                    (0, values_1.isObject)(block.content) && block.content.type === 'doc'
+                        ? nodeProblem(block.content, DOC, 0, known)
+                        : 'Content must be a rich text document';
+                break;
+            case enum_1.DocumentBlockType.FIELDS:
+                problem = listProblem(block.fields, 'fields', 'Field', MAX_FIELDS, (field) => entryProblem(field, ['label', 'value'], () => textProblem(field.label, 'Label', MAX_LABEL_LENGTH, known), () => textProblem(field.value, 'Value', MAX_TEXT_LENGTH, known)));
+                break;
+            case enum_1.DocumentBlockType.LINE_ITEMS:
+                problem = listProblem(block.items, 'lines', 'Line', MAX_LINES, (line) => entryProblem(line, ['description', 'quantity', 'unit_price_minor', 'discount_percent', 'tax_rate'], () => textProblem(line.description, 'Description', MAX_TEXT_LENGTH, known), () => amountProblem(line.quantity, 'Quantity', enum_1.DocumentVariableType.NUMBER, declared, {
+                    holds: (amount) => Number.isFinite(amount) && amount > 0,
+                    message: 'must be greater than 0',
+                }), () => amountProblem(line.unit_price_minor, 'Unit price', enum_1.DocumentVariableType.MONEY, declared, {
+                    holds: (amount) => Number.isSafeInteger(amount) && amount >= 0,
+                    message: 'must be a whole number of cents, 0 or more',
+                }), () => percentProblem(line.discount_percent, 'Discount'), () => percentProblem(line.tax_rate, 'Tax rate')));
+                break;
+            case enum_1.DocumentBlockType.TABLE: {
+                const columns = block.columns;
+                problem =
+                    Array.isArray(columns) && columns.length === 0
+                        ? 'A table needs at least one column'
+                        : (listProblem(columns, 'columns', 'Column', MAX_COLUMNS, (column) => textProblem(column, 'Heading', MAX_LABEL_LENGTH, known)) ??
+                            listProblem(block.rows, 'rows', 'Row', MAX_ROWS, (row) => Array.isArray(row) && row.length === columns.length
+                                ? listProblem(row, 'cells', 'Cell', MAX_COLUMNS, (cell) => textProblem(cell, 'Text', MAX_TEXT_LENGTH, known))
+                                : `Must have one cell per column (${columns.length})`));
+                break;
+            }
+            case enum_1.DocumentBlockType.COLUMNS: {
+                const columns = block.columns;
+                problem =
+                    Array.isArray(columns) && (columns.length < MIN_SIDE_COLUMNS || columns.length > MAX_SIDE_COLUMNS)
+                        ? `A columns block has ${MIN_SIDE_COLUMNS} or ${MAX_SIDE_COLUMNS} columns`
+                        : listProblem(columns, 'columns', 'Column', MAX_SIDE_COLUMNS, (column) => entryProblem(column, ['heading', 'text'], () => textProblem(column.heading, 'Heading', MAX_LABEL_LENGTH, known), () => textProblem(column.text, 'Text', MAX_TEXT_LENGTH, known)));
+                break;
+            }
+            case enum_1.DocumentBlockType.SIGNATURE:
+                problem = listProblem(block.signers, 'signers', 'Signer', MAX_SIGNERS, (signer) => entryProblem(signer, ['label'], () => textProblem(signer.label, 'Label', MAX_LABEL_LENGTH, known)));
+                break;
+            case enum_1.DocumentBlockType.IMAGE:
+                problem =
+                    typeof block.path !== 'string' || (block.path !== '' && !exports.IMAGE_PATH.test(block.path))
+                        ? 'Image must be one uploaded for documents'
+                        : textProblem(block.alt, 'Alt text', MAX_LABEL_LENGTH, known);
+                break;
+            case enum_1.DocumentBlockType.HEADER:
+            case enum_1.DocumentBlockType.FOOTER:
+                problem =
+                    textProblem(block.left, 'Left', MAX_LABEL_LENGTH, knownOnEveryPage) ??
+                        textProblem(block.right, 'Right', MAX_LABEL_LENGTH, knownOnEveryPage);
+                break;
+        }
+        if (problem)
+            return `${where}: ${problem}`;
+    }
+    return null;
+};
+exports.blocksProblem = blocksProblem;
+/**
+ * Filled-in values by variable key: each key a declared variable (system values are the api's to
+ * fill) and each value fitting its type - text, a number, whole cents 0 or more, a YYYY-MM-DD
+ * date. A variable with no value is simply left out.
+ */
+const variableValuesProblem = (values, variables) => {
+    if (!(0, values_1.isObject)(values))
+        return 'Variable values must be an object';
+    const declared = declaredTypes(variables);
+    for (const [key, value] of Object.entries(values)) {
+        const type = declared.get(key);
+        if (type === undefined) {
+            return SYSTEM_VARIABLES.has(key) ? `"${key}" is filled in by the system` : `Unknown variable "${key}"`;
+        }
+        const problem = valueProblem(type, value);
+        if (problem)
+            return `Value of "${key}" ${problem}`;
+    }
+    return null;
+};
+exports.variableValuesProblem = variableValuesProblem;
+/** Three capital letters (ZAR), or nothing - unless a line items block needs one to print in. */
+const currencyProblem = (currency, blocks) => {
+    if (currency === null || currency === undefined) {
+        const hasLineItems = Array.isArray(blocks) && blocks.some((block) => (0, values_1.isObject)(block) && block.type === enum_1.DocumentBlockType.LINE_ITEMS);
+        return hasLineItems ? 'Currency is required when the document has line items' : null;
+    }
+    return typeof currency === 'string' && CURRENCY.test(currency) ? null : 'Currency must be a three-letter code, such as ZAR';
+};
+exports.currencyProblem = currencyProblem;
+/**
+ * Everything `UpdateDocumentDto` checks about a document's content, as one call - for a draft the
+ * api composes itself: `POST /documents` copies a template's variables and blocks and overlays the
+ * caller's values, which no DTO saw together. Null when the draft is sound.
+ */
+const documentProblem = (document) => (0, exports.variablesProblem)(document.variables) ??
+    (0, exports.blocksProblem)(document.blocks, document.variables) ??
+    (0, exports.variableValuesProblem)(document.variable_values, document.variables) ??
+    (0, exports.currencyProblem)(document.currency, document.blocks);
+exports.documentProblem = documentProblem;
+// The checks above as decorators; blocks, values and currency read the DTO's sibling fields.
+exports.IsDocumentVariables = (0, validators_1.fromProblem)('isDocumentVariables', exports.variablesProblem);
+exports.IsDocumentBlocks = (0, validators_1.fromProblem)('isDocumentBlocks', (value, object) => (0, exports.blocksProblem)(value, object.variables));
+exports.IsDocumentVariableValues = (0, validators_1.fromProblem)('isDocumentVariableValues', (value, object) => (0, exports.variableValuesProblem)(value, object.variables));
+/** On a DTO with `blocks`, also required when they hold line items; `@IsOptional()` makes it a format check only. */
+exports.IsDocumentCurrency = (0, validators_1.fromProblem)('isDocumentCurrency', (value, object) => (0, exports.currencyProblem)(value, object.blocks));
+exports.IsDocumentCategory = (0, validators_1.fromProblem)('isDocumentCategory', (value) => {
+    if (typeof value !== 'string')
+        return 'Category must be text';
+    return value.length > MAX_CATEGORY_LENGTH ? `Category cannot exceed ${MAX_CATEGORY_LENGTH} characters` : null;
+});
+exports.IsDocumentNumberPrefix = (0, validators_1.fromProblem)('isDocumentNumberPrefix', (value) => {
+    if (typeof value !== 'string')
+        return 'Number prefix must be text';
+    if (value.length > MAX_NUMBER_PREFIX_LENGTH)
+        return `Number prefix cannot exceed ${MAX_NUMBER_PREFIX_LENGTH} characters`;
+    return NUMBER_PREFIX.test(value) ? null : 'Number prefix can only hold letters, digits and - / _ .';
+});

package/dist/documents/document-templates.d.ts

@@ -0,0 +1,37 @@
+import type { MmsList } from '@managemint-solutions/entities/common';
+import type { DocumentTemplateEntity, DocumentTemplateSummary } from '@managemint-solutions/entities/documents';
+import type { ClientContext } from '../auth';
+import { EntityAuditTrail, type AuditResource } from '../audit';
+import type { TypedSupabaseClient } from '../client';
+import type { CreateDocumentTemplateDto, GetDocumentTemplatesDto, UpdateDocumentTemplateDto } from './dto';
+/**
+ * A template as the sdk reads it. `my_role` - what the caller may do with it - is the api's to
+ * add, from the caller's visibility row and permissions.
+ */
+export type DocumentTemplateRecord = Omit<DocumentTemplateEntity, 'my_role'>;
+/**
+ * Document templates: an ordered list of blocks plus the variables they use. A template is
+ * always read and saved whole. Deleting one keeps the documents made from it - the foreign key
+ * forgets their `template_id`.
+ */
+export declare class DocumentTemplatesResource {
+    private readonly supabase;
+    private readonly auth;
+    private readonly table;
+    /** This record's history - its own rows. */
+    readonly audit: EntityAuditTrail;
+    constructor(supabase: TypedSupabaseClient, auth: ClientContext, audit: AuditResource);
+    /** Newest first; `search` matches the name and the category. */
+    list(query: GetDocumentTemplatesDto & {
+        organization_id?: string | null;
+    }): Promise<MmsList<DocumentTemplateSummary>>;
+    getById(templateId: string): Promise<DocumentTemplateRecord>;
+    create(input: CreateDocumentTemplateDto): Promise<DocumentTemplateRecord>;
+    /** Replaces the whole template. Documents already made from it keep their own copy. */
+    update(templateId: string, input: UpdateDocumentTemplateDto): Promise<DocumentTemplateRecord>;
+    archive(templateId: string): Promise<DocumentTemplateRecord>;
+    /** The table keeps no unarchive stamps, so the archive ones are cleared; the history keeps both. */
+    unarchive(templateId: string): Promise<DocumentTemplateRecord>;
+    /** Hard delete. Its documents stay, with `template_id` set to null by the foreign key. */
+    remove(templateId: string): Promise<void>;
+}

package/dist/documents/document-templates.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DocumentTemplatesResource = void 0;
+const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
+const audit_1 = require("../audit");
+const errors_1 = require("../errors");
+const tenancy_1 = require("../tenancy");
+const transforms_1 = require("../transforms");
+// The public contract is the shared DocumentTemplateSummary / DocumentTemplateEntity from
+// @managemint-solutions/entities; the casts at the returns declare the shape the select strings
+// below produce (the columns are defined in the schemas repo's migrations).
+const TEMPLATE_LIST_SELECT = `
+        mms_id,
+        created_at,
+        name,
+        category,
+        number_prefix,
+        archived,
+        visibility
+      `;
+const TEMPLATE_DETAIL_SELECT = `
+        mms_id,
+        created_at,
+        created_by:user_profiles!created_by ${transforms_1.USER_PROFILE_EMBED},
+        updated_at,
+        last_updated_by:user_profiles!last_updated_by ${transforms_1.USER_PROFILE_EMBED},
+        name,
+        category,
+        number_prefix,
+        variables,
+        blocks,
+        blocks_version,
+        visibility,
+        archived,
+        archived_at,
+        archived_by:user_profiles!archived_by ${transforms_1.USER_PROFILE_EMBED}
+      `;
+/**
+ * What a save writes: the whole template, its two optional words stored as '' when left out.
+ * Never its visibility - members hold no grant on it after create.
+ */
+const templateRow = (input) => ({
+    name: input.name,
+    category: input.category ?? '',
+    number_prefix: input.number_prefix ?? '',
+    variables: input.variables,
+    blocks: input.blocks,
+});
+/**
+ * Document templates: an ordered list of blocks plus the variables they use. A template is
+ * always read and saved whole. Deleting one keeps the documents made from it - the foreign key
+ * forgets their `template_id`.
+ */
+class DocumentTemplatesResource {
+    supabase;
+    auth;
+    table;
+    /** This record's history - its own rows. */
+    audit;
+    constructor(supabase, auth, audit) {
+        this.supabase = supabase;
+        this.auth = auth;
+        this.table = (0, audit_1.auditedTable)(supabase, auth, audit, {
+            table: 'document_templates',
+            entityType: enum_1.AuditTrailEntityType.DOCUMENT_TEMPLATES,
+            documentContent: true,
+        });
+        this.audit = new audit_1.EntityAuditTrail(supabase, auth, enum_1.AuditTrailEntityType.DOCUMENT_TEMPLATES);
+    }
+    /** Newest first; `search` matches the name and the category. */
+    async list(query) {
+        const page = query.page;
+        const pageSize = query.page_size;
+        const offset = (page - 1) * pageSize;
+        const trimmedSearch = query.search?.trim();
+        // `order`/`range` return `this`, so the conditional filters below reassign onto the builder.
+        let templatesQuery = (0, tenancy_1.scopeToOrganization)(this.supabase
+            .from('document_templates')
+            .select((0, tenancy_1.withOrganization)(TEMPLATE_LIST_SELECT, this.auth), { count: 'estimated' }), this.auth)
+            .eq('archived', query.archive)
+            .order('created_at', { ascending: false })
+            .range(offset, offset + pageSize - 1);
+        if (query.organization_id) {
+            templatesQuery = templatesQuery.eq('organization_id', query.organization_id);
+        }
+        if (query.category) {
+            templatesQuery = templatesQuery.eq('category', query.category);
+        }
+        if (trimmedSearch) {
+            templatesQuery = templatesQuery.or((0, transforms_1.orIlike)(['name', 'category'], trimmedSearch));
+        }
+        const { data, error, count } = await templatesQuery;
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return (0, transforms_1.toMmsList)(data, page, pageSize, count);
+    }
+    async getById(templateId) {
+        const { data, error } = await (0, tenancy_1.scopeToOrganization)(this.supabase.from('document_templates').select((0, tenancy_1.withOrganization)(TEMPLATE_DETAIL_SELECT, this.auth)), this.auth)
+            .eq('mms_id', templateId)
+            .single();
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return data;
+    }
+    async create(input) {
+        const row = await this.table.insert({
+            ...templateRow(input),
+            // Omitted: the column's default, shared with the organization.
+            ...(input.visibility && { visibility: input.visibility }),
+            organization_id: (0, tenancy_1.requireOrganization)(this.auth),
+            created_by: this.auth.mms_id,
+            created_at: new Date().toISOString(),
+        });
+        return this.getById(row.mms_id);
+    }
+    /** Replaces the whole template. Documents already made from it keep their own copy. */
+    async update(templateId, input) {
+        await this.table.update(templateId, {
+            ...templateRow(input),
+            last_updated_by: this.auth.mms_id,
+            updated_at: new Date().toISOString(),
+        });
+        return this.getById(templateId);
+    }
+    async archive(templateId) {
+        await this.table.transition(templateId, enum_1.AuditTrailAction.ARCHIVE, (0, transforms_1.archivedPatch)(this.auth.mms_id));
+        return this.getById(templateId);
+    }
+    /** The table keeps no unarchive stamps, so the archive ones are cleared; the history keeps both. */
+    async unarchive(templateId) {
+        await this.table.transition(templateId, enum_1.AuditTrailAction.UNARCHIVE, {
+            archived: false,
+            archived_at: null,
+            archived_by: null,
+        });
+        return this.getById(templateId);
+    }
+    /** Hard delete. Its documents stay, with `template_id` set to null by the foreign key. */
+    async remove(templateId) {
+        await this.table.remove(templateId);
+    }
+}
+exports.DocumentTemplatesResource = DocumentTemplatesResource;