@managemint-solutions/sdk 0.55.0 → 0.64.0

package/README.md

@@ -22,7 +22,9 @@ are peer dependencies - the request DTOs (`AddStatusDto`, `UpdateStatusDto`, `St
 decorators so consumers validate against
 the same rules the SDK's input types describe. `@nestjs/common` (^11) is an optional peer
 dependency, needed only for the `@managemint-solutions/sdk/nest` subpath, and `@upstash/redis`
-(^1.38) is an optional peer needed only for the `@managemint-solutions/sdk/cache` subpath.
+(^1.38) is an optional peer needed only for the `@managemint-solutions/sdk/cache` subpath. The
+`@managemint-solutions/sdk/documents` subpath (the document renderer) needs no peer at all and
+runs in a browser - see "Rendering" under Documents.
 
 ## Usage
 
@@ -219,7 +221,7 @@ escape hatch for queries not yet covered by a resource.
 
 Every write a resource makes is logged to `audit_logs` by the SDK itself - there are no database
 triggers and no audit code in any feature. A write records one row carrying the action
-(`INSERT` / `UPDATE` / `ARCHIVE` / `UNARCHIVE` / `DELETE` / `RESTORE`), the entity type and id, who
+(`INSERT` / `UPDATE` / `ARCHIVE` / `UNARCHIVE` / `DELETE` / `RESTORE`; `SEND` is the one event that is not a row change - `documents.recordSend`), the entity type and id, who
 did it, and a `changes` diff of the flat table row as real JSON (`{ field: { old, new } }`).
 Inserts and hard deletes record a whole-row snapshot instead, so the trail survives the row.
 Bookkeeping columns are never diffed (`id`, `mms_id`, `organization_id`, `created_at/by`,
@@ -236,7 +238,7 @@ The trail is read one record at a time. Each resource with a record page exposes
 ```ts
 const history = await supabase.clients.audit.list(clientId, { page: 1, page_size: 10 });
 // → MmsList<AuditTrailEntity>. Also on leads, projects, tasks, users, organizations,
-//   timesheets, leaveRequests and leaveEntitlements.
+//   timesheets, leaveRequests, leaveEntitlements, documentTemplates and documents.
 
 const names = await supabase.audit.names({ statuses: [statusId], users: [userId] });
 // → { [mms_id]: 'In Progress', ... } - readable names for the ids a page of history holds.
@@ -292,7 +294,8 @@ organization with a Paystack customer, every organization whose leave year start
 up. The scope also carries `leaveTypes`, `leaveEntitlements` and `leaveRequests` for the leave-year
 rollover, whose writes are attributed to the system.
 
-`update` / `transition` / `remove` pre-read the flat row (by `mms_id`, and by `organization_id`
+`update` / `transition` / `remove` (and the guarded `updateWhere` / `removeWhere`, which resolve to
+`null` when their guard matched nothing and then audit nothing) pre-read the flat row (by `mms_id`, and by `organization_id`
 unless `scopeByOrganization: false` - the `organizations` table is its own tenant), so a missing
 row surfaces as the usual 406. The write itself still throws `SupabaseClientError` on failure;
 only the audit insert is swallowed.
@@ -349,14 +352,15 @@ export class AuthController {
 
 ManageMint Solutions employees sign in to the admin api with a token whose role is `staff`. Their
 client is a `SupabaseStaffClient`, which carries only what the admin api reads: `clients`, `leads`,
-`projects`, `tasks`, `users`, `organizations`, `staff`, `staffPermissions` and
-`userApiCredentials`. A resource not on it is not available to staff.
+`projects`, `tasks`, `documentTemplates`, `documents`, `users`, `organizations`, `staff`,
+`staffPermissions` and `userApiCredentials`. A resource not on it is not available to staff.
 
 - **Reads span every organization.** The shared resources drop their organization filter and the
   `staff` role's policies decide what comes back. The `clients`, `leads`, `projects`, `tasks` and
   `users` lists embed each row's `organization` (`{ mms_id, name }`) and take an `organization_id`
   filter through the staff query DTOs (`StaffGetClientsDto`, ...); a tenant's request and response
-  are unchanged. `organizations.list` pages every organization (`search` over name, trading
+  are unchanged. The `documentTemplates` and `documents` lists do the same, though entities has
+  no staff query DTO for them yet. `organizations.list` pages every organization (`search` over name, trading
   name, email).
 - **Every write is refused** with a `403 Permission Error` before any statement runs, as is the
   tenant-only `organizations.get()`.
@@ -616,6 +620,204 @@ const year = await supabase.publicHolidays.list({ year: 2026 });
 const off = await supabase.publicHolidays.datesBetween('2026-09-21', '2026-09-25'); // Set of religion-neutral dates
 ```
 
+## Documents
+
+Generic, block-based documents in the CRM module - invoices, quotes, contracts, letters:
+`document_templates` and `documents`, one org-scoped audited resource each on the caller's client.
+A template is an ordered list of typed blocks plus the variables they use; a document is a copy of
+a template's blocks and variables plus the values filled in, so a later template edit never
+changes it. Both are read and saved whole. Issuing and numbering are the api's; the sdk stores
+rows, checks content and signs image uploads, and its `./documents` subpath (below) holds the
+renderer, the totals and the system values that the api prints with and the portal previews with.
+
+```ts
+import { DocumentStatus } from '@managemint-solutions/entities/documents/enum';
+import { documentProblem } from '@managemint-solutions/sdk';
+
+const page = await supabase.documentTemplates.list({ page: 1, page_size: 10, archive: false, category: 'Invoice' }); // search: name, category
+const template = await supabase.documentTemplates.create({ name, category, number_prefix: 'INV-', variables, blocks });
+await supabase.documentTemplates.update(template.mms_id, body); // replaces the whole template
+await supabase.documentTemplates.archive(template.mms_id);      // unarchive clears archived_at/by - no unarchive columns
+await supabase.documentTemplates.remove(template.mms_id);       // hard delete; its documents keep, template_id -> null
+
+const documents = await supabase.documents.list({ page: 1, page_size: 10, status: DocumentStatus.DRAFT, client_id, template_id, category, search }); // search: title, number
+const draft = await supabase.documents.create(row);              // CreateDocumentRow: the draft the api composed, totals included
+const saved = await supabase.documents.update(id, DocumentStatus.DRAFT, { ...body, ...totals }); // null = no longer a draft
+const sequence = await supabase.documents.nextSequence('INV-');  // the organization's highest for the prefix + 1
+const issued = await supabase.documents.update(id, DocumentStatus.DRAFT, {
+  status: DocumentStatus.ISSUED, number_sequence: sequence, number, variable_values: frozen, issued_at, issued_by, ...totals,
+});                                                               // 409 with code 23505: the number was taken - retry
+const voided = await supabase.documents.update(id, DocumentStatus.ISSUED, { status: DocumentStatus.VOID, voided_at, voided_by, void_reason });
+const removed = await supabase.documents.remove(id);             // false = no longer a draft; nothing deleted
+await supabase.documents.audit.list(id, query);                   // documentTemplates.audit too
+
+const { path, url } = await supabase.documents.createImageUploadUrl('logo.png'); // PUT the bytes to url; the block stores path
+const urls = await supabase.documents.imageUrls(paths);           // { [path]: signed URL, one hour } for the renderer
+```
+
+`update` is the one write after create: a compare-and-set (`updateWhere`) on the status the api
+read and decided on, resolving to `null` when the document has moved on - a draft save and an
+issue expect `draft`, a void expects `issued`. `remove` is the same on `draft` (`removeWhere`), so
+an issue that lands first keeps its document and `remove` answers `false`. The history never copies
+the whole `blocks` / `variables` JSON (saved whole each time): an update records what changed inside
+them, and in the filled-in values - block by block, variable by variable, value by value
+(`documentContent` on the audited table) - and a create or delete records only that `blocks` and
+`variables` were set; the title, status, number and totals stay readable. The client and template embeds go through the
+composite same-organization keys (`clients!documents_client_fkey`,
+`document_templates!documents_template_fkey`), so a document pointing at another organization's
+client or template is refused by the database with a 409.
+
+**Content rules.** Blocks and variables are JSON with no SQL checks, so the DTOs
+(`CreateDocumentTemplateDto`, `UpdateDocumentTemplateDto`, `UpdateDocumentDto`) are the gate, all through one set of checks in `src/documents/content.ts`.
+Each refusal names where it is: `Block 2 (line items): Line 1: Quantity must be greater than 0`.
+
+- Variables: `{ key, label, type, required, default_value }` exactly; keys lower snake_case, 1 to
+  40 characters, unique, never a `DocumentSystemVariable`; a default that fits the type, or `null`.
+- Blocks: each type's properties and nothing else; block ids unique. Quantity above 0, unit price
+  whole cents 0 or more, discount and tax 0 to 100. Lists may be empty, so a block saves before it
+  is filled in; a table needs a column, and every row one cell per column.
+- Rich text: `doc`, `paragraph`, `heading` (1 to 3), `bulletList`, `orderedList`, `listItem`, `text`,
+  `hardBreak`, `variable`; marks `bold`, `italic`, `underline`, `link` (http, https or mailto). Each
+  node only where the editor puts it, lists at most four deep. Other attributes the editor writes
+  are stored and never rendered.
+- References: every variable used - `{{key}}` in any plain-text string of a block, a variable node,
+  a line's `{ variable }` - is declared or a system variable. A quantity points at a number
+  variable, a unit price at a money variable.
+- Header and footer: `{ id, type, left, right }`, plain text, either side may be empty. They
+  repeat on every PDF page, so a document has at most one of each, anywhere in the list (the
+  renderer takes them out of the flow). `{{page_number}}` and `{{page_count}}` work only there:
+  anywhere else - plain text, a variable node, a line's `{ variable }` - is refused with "Page number
+  and page count only work in a header or footer", and as values they are the system's.
+- Values: declared keys only (system values are the api's to fill), each fitting its type - text,
+  a number, whole cents 0 or more, a `YYYY-MM-DD` date. A variable with no value is left out.
+- Currency: three capitals. Required by `UpdateDocumentDto` when a line items block exists; on
+  `CreateDocumentDto` it is optional and only its format is checked.
+- Images: an image block's `path` is `''` or one `createImageUploadUrl` handed out.
+
+`CreateDocumentDto` cannot run the rules - with a template, the variables its values fill are the
+template's - so the api runs `documentProblem(draft)` on the draft it composes, which returns the
+same message the DTO would, or null. The checks find `{{key}}`s, and accept links, with the
+renderer's own pattern and href rule, so what is checked is exactly what prints.
+
+**Images** live in the supporting-files bucket at `<organization>/documents/images/<uuid>.<ext>`
+(png, jpg, jpeg, gif), named afresh on every upload and never replaced, so an issued document's
+images cannot change. The block stores the path inside the organization's folder; `imageUrls`
+signs it back under the caller's organization.
+
+### Sending and payments
+
+```ts
+await supabase.documents.recordSend(id, { recipients, cc, subject, pay_now }); // a SEND audit event - there is no sends table
+await supabase.documents.sends(id);                          // DocumentSend[], newest first, read from those events
+await supabase.payments.list(PaymentEntityType.DOCUMENTS, id); // Payment[], oldest first - read only for members
+
+const scope = service.forOrganization(organizationId);       // no caller: the webhook, the public pay page, the daily cap
+await scope.payments.create(row);                            // 409 code 23505: the Paystack reference is recorded already
+await scope.documents.countSendsSince(startOfDay);           // every document of the organization, private ones too
+await scope.documents.getById(id);                           // the pay page's read, on the system actor
+await service.findDocumentOrganization(id);                  // string | null - unscoped, for a pay link the api has verified
+await scope.paymentMethod.set({ paystack_subaccount_code, payout_business_name, payout_bank_name, payout_account_last4 });
+```
+
+Recurring and scheduled documents: `documents.list({ recurring: true })` lists the parents alone
+(every other list leaves them out), `list({ repeat_from })` one parent's drafts, `countCopies(id)` how
+many it made; `repeat_from` reads as `{ mms_id, title }`, fetched beside the rows (PostgREST embeds a
+self-relationship only through a SQL function). The cron's scans are
+`service.documentsDueForDraft(date)` / `documentsDueToIssue(date)`; `service.notifications.existsFor(type,
+recipientId, variables)` tells it whether a failure was already reported. The schedule fields
+(`repeat`, `repeat_next_at`, `repeat_until`, `repeat_paused`, `issue_at`, `email`) ride on
+`CreateDocumentDto` / `UpdateDocumentDto`; `email` is checked with `SendDocumentDto`'s rules.
+Payments: `list` is paid rows only, `paidCounts(type, ids)` for a list page, `paidEntityIds(type)`
+for the list's payment filter, `findOpen` / `findByReference` / `settle` / `removeOpen` for the one
+open checkout per record, and `removeManual` for a payment marked by hand (EFT).
+
+`payments` is one generic table of money received, keyed by `entity_type` + `entity_id` like
+`visibility` (`PaymentDirection`, `PaymentEntityType`, `PaymentMethod` are entities enums). A
+member reads a payment while its record is readable; only the service role writes. Each insert is
+audited and filed under its record through those two columns. A send has no table: it is a
+`SEND` event in the document's history (`AuditTrailAction.SEND`), which `sends` reads back and the
+api's daily cap counts. `SendDocumentDto` takes 1 to 5 `to`, up to 5 `cc`, a subject (1 to 200
+characters) and a message (up to 5000); `DocumentPayTokenDto` checks only the shape of a pay link's
+token (`<document mms_id>.<43-character signature>`) - the api checks the signature.
+
+### Rendering - `@managemint-solutions/sdk/documents`
+
+One renderer for the api's PDF and the portal's live preview, as pure functions: no Node built-in,
+no Nest, no supabase-js, no DOM - only the shared entities - so it runs as well in a browser as in
+the api. The caller loads the organization and client and signs the image URLs; nothing here does
+I/O.
+
+```ts
+import {
+  johannesburgDate, printsMoney, renderBand, renderDocument, startingValues, systemValues,
+  DOCUMENT_PAGE_MARGINS,
+} from '@managemint-solutions/sdk/documents';
+
+const values = {
+  ...draft.variable_values,                                // or startingValues(template.variables, sample) for a template
+  ...systemValues({
+    organization: { name, trading_name, address: [line1, line2, city, state, postCode, country] },
+    client,                                                // { name, email, phone } or null
+    number: null,                                          // until issued
+    issueDate: johannesburgDate(new Date()),               // YYYY-MM-DD in Africa/Johannesburg
+  }),
+};
+const { html, header, footer } = renderDocument(
+  { title, number, status, currency, variables, values, blocks }, // status null = a template ("Template")
+  imageUrls,                                              // { [block path]: signed URL }
+);
+// api:    renderPdf(html, { headerTemplate: header && renderBand(header, 'top'), footerTemplate: renderBand(footer, 'bottom'), ... })
+// portal: lay html out in pages (Paged.js); place the renderBand output on each page, writing the page counters in
+```
+
+- `renderDocument(document: PrintableDocument, imageUrls: Record<string, string>): RenderedDocument`
+  - `html`: a self-contained page (its own `<style>`): the first page's letterhead, then the blocks.
+    Every text and value escaped; the rich-text whitelist only; money in the document currency,
+    dates as `1 November 2026`; a missing value as `[Label]` on a draft or template (`status` draft
+    or null), blank once issued; an image path missing from `imageUrls` as `[Image]` likewise.
+  - `header`: `{ left, right }` HTML from the header block, or null without one.
+  - `footer`: the footer block's, or the default (organization, title and number, "Page X of Y").
+    `{{page_number}}` / `{{page_count}}` are `<span class="pageNumber">` / `<span class="totalPages">`.
+- `renderBand(band, 'top' | 'bottom'): string` - the band as an inline-styled block, for Chromium's
+  header/footer template or a page of the portal's preview.
+- `fillText(text, document): string` - `{{key}}`s filled as plain text, for a stored email's
+  subject and message.
+- `DOCUMENT_PAGE_MARGINS` - `{ top: 0.62, topWithHeader: 0.95, bottom: 0.7, side: 0.7 }` inches.
+- `systemValues(inputs: SystemValueInputs): DocumentVariableValues`, `johannesburgDate(now: Date): string`.
+- `documentTotals(blocks, values): DocumentTotals`, `printsMoney(blocks, variables): boolean`,
+  `startingValues(variables, given?)`.
+- `escapeHtml`, `money(minor, currency)`, `formatDocumentDate('2026-11-01')`, `MONO_FONT`,
+  `SYSTEM_VARIABLES` (labels and types).
+
+## Visibility
+
+Templates and documents carry a `visibility` (`DocumentVisibility`): `organization` is everyone in
+it, `private` is the creator plus the people it is shared with - never the organization's owners
+or admins, never staff. Who it is shared with lives in one generic table, `public.visibility`
+(one row per person per record, keyed by `VisibilityEntityType` + record id, with a
+`VisibilityRole` of read, write or admin), so another kind of record can be shared without a new
+table. The database enforces what each role can see and change; members read only their own
+rows, so the user client needs nothing new. The rows are written on the service client's
+organization scope, after the api has checked the caller may manage the record and that it is in
+the organization (`entity_id` has no foreign key):
+
+```ts
+const record = { entityType: VisibilityEntityType.DOCUMENTS, entityId: documentId };
+const shares = await scope.visibility.list(record);            // [{ user: UserIdentity, role }] - GET .../visibility
+await scope.visibility.setVisibility(record, body.visibility); // the record's own column - PUT .../visibility
+await scope.visibility.replace(record, body.shares);           // exactly these people - PUT .../visibility (UpdateVisibilityDto)
+await scope.visibility.copy({ entityType: VisibilityEntityType.DOCUMENT_TEMPLATES, entityId: templateId }, record); // a draft from a private template
+await scope.visibility.removeAll(record);                      // after the record is deleted - nothing else removes them
+const moved = await scope.visibility.reassign(VisibilityEntityType.DOCUMENTS, fromUserId, toUserId); // the owner's reassign, per kind
+```
+
+`replace` and `copy` are audited against the record (`related_entity_*`), so share changes show in
+its history. `visibility` is set at create (`CreateDocumentTemplateDto`, `CreateDocumentDto`)
+and is not part of a save: members hold no UPDATE grant on it or on `created_by`, so only the
+visibility and reassign routes change them, on the service role (`setVisibility`, `reassign`). The reads return
+`DocumentTemplateRecord` / `DocumentRecord` - the entities without `my_role`, which the api works
+out from the caller's row and permissions.
+
 ## Errors
 
 Every error the SDK throws is a `SupabaseClientError` carrying the HTTP `status` to respond

package/dist/audit/document-changes.d.ts

@@ -0,0 +1,39 @@
+import type { DocumentBlockChange, DocumentValueChange, DocumentVariableChange } from '@managemint-solutions/entities/documents';
+import { type Json } from '../documents/render/values';
+/** A text block's rich text as plain text: one line per paragraph, heading or list item, `{{key}}` per variable. */
+export declare const richTextToPlain: (doc: unknown) => string;
+/**
+ * Each block a save added, removed, moved or edited, in the order they now stand (a removed one
+ * where it stood). Blocks are matched by id. A block counts as moved only when it left the
+ * order the others kept - adding or removing one above it does not move it. A block whose JSON
+ * changed with no printable part changing (bold added to a word) is CHANGED with no parts.
+ */
+export declare const blockChanges: (before: unknown[], after: unknown[]) => DocumentBlockChange[];
+/** Each variable definition a save added, removed or edited, by key, in the order they now stand. */
+export declare const variableChanges: (before: unknown[], after: unknown[]) => DocumentVariableChange[];
+/**
+ * Each filled-in value a save changed, by key, labelled and typed by the definitions as they
+ * now stand (as they stood, for a variable since removed). A key no definition names - a system
+ * variable frozen at issue - has a null label and type.
+ */
+export declare const valueChanges: (before: Json, after: Json, variablesBefore: unknown, variablesAfter: unknown) => DocumentValueChange[];
+/** The columns of `document_templates` and `documents` recorded as what changed inside them. */
+export declare const DOCUMENT_CONTENT_COLUMNS: readonly string[];
+type Changes = Record<string, {
+    old: unknown;
+    new: unknown;
+    diff?: unknown[];
+}>;
+/**
+ * A template's or document's changes as they are stored. Its `blocks` and `variables` arrive
+ * whole on both sides of an update and leave as `'[redacted]'` with a `diff` of what moved inside
+ * them; a created or deleted row keeps the plain markers (the whole JSON is not copied). Its
+ * `variable_values` leave the same way with a values `diff`, labelled by `variables` (the row's
+ * definitions before and after the event). Its `email` keeps only the keys that changed. A column
+ * whose JSON changed with nothing printable changing (variables reordered) is dropped.
+ */
+export declare const compactDocumentChanges: (changes: Changes, variables: {
+    old: unknown;
+    new: unknown;
+}) => Changes;
+export {};

package/dist/audit/document-changes.js

@@ -0,0 +1,332 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compactDocumentChanges = exports.DOCUMENT_CONTENT_COLUMNS = exports.valueChanges = exports.variableChanges = exports.blockChanges = exports.richTextToPlain = void 0;
+const enum_1 = require("@managemint-solutions/entities/documents/enum");
+const values_1 = require("../documents/render/values");
+// What a template's or document's save changed inside its JSON columns, worked out from the
+// whole values before and after: one entry per block, per variable definition and per filled-in
+// value that moved, everything else left out. Text is kept whole, however long - the portal
+// clips it. Pure functions of the two sides; `AuditResource.write` calls them as it writes the
+// entry.
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+// ------------------------------------------------------------
+// Rich text
+// ------------------------------------------------------------
+const textLines = (node) => {
+    if (!(0, values_1.isObject)(node))
+        return [];
+    const children = Array.isArray(node.content) ? node.content : [];
+    switch (node.type) {
+        case 'paragraph':
+        case 'heading':
+            return [children
+                    .map((inline) => {
+                    if (!(0, values_1.isObject)(inline))
+                        return '';
+                    if (inline.type === 'text')
+                        return typeof inline.text === 'string' ? inline.text : '';
+                    if (inline.type === 'variable')
+                        return `{{${(0, values_1.isObject)(inline.attrs) ? String(inline.attrs.key) : ''}}}`;
+                    if (inline.type === 'hardBreak')
+                        return '\n';
+                    return '';
+                })
+                    .join('')];
+        case 'bulletList':
+        case 'orderedList': {
+            const start = (0, values_1.isObject)(node.attrs) && typeof node.attrs.start === 'number' ? node.attrs.start : 1;
+            return children.flatMap((item, index) => {
+                const marker = node.type === 'bulletList' ? '- ' : `${start + index}. `;
+                const lines = (0, values_1.isObject)(item) && Array.isArray(item.content) ? item.content.flatMap(textLines) : [];
+                return lines.map((line, at) => (at === 0 ? marker : '  ') + line);
+            });
+        }
+        default:
+            return children.flatMap(textLines);
+    }
+};
+/** A text block's rich text as plain text: one line per paragraph, heading or list item, `{{key}}` per variable. */
+const richTextToPlain = (doc) => textLines(doc).join('\n');
+exports.richTextToPlain = richTextToPlain;
+// ------------------------------------------------------------
+// Blocks
+// ------------------------------------------------------------
+/** A stored value as one side of a change: a line's variable amount reads as `{{key}}`. */
+const leaf = (value) => {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+        return value;
+    if ((0, values_1.isObject)(value) && typeof value.variable === 'string')
+        return `{{${value.variable}}}`;
+    return JSON.stringify(value);
+};
+/** A list entry's printable leaves, by where they sit inside it: a row's cells, a field's label and value. */
+const entryLeaves = (entry) => {
+    if (Array.isArray(entry))
+        return entry.map((value, column) => ({ at: [column], value: leaf(value) }));
+    if ((0, values_1.isObject)(entry) && typeof entry.variable !== 'string') {
+        return Object.entries(entry).map(([key, value]) => ({ at: [key], value: leaf(value) }));
+    }
+    return [{ at: [], value: leaf(entry) }];
+};
+/** A block's printable properties: everything but its id and type, rich text as plain text. */
+const propertiesOf = (block) => Object.entries(block)
+    .filter(([key]) => key !== 'id' && key !== 'type')
+    .map(([key, value]) => [key, key === 'content' && (0, values_1.isObject)(value) ? (0, exports.richTextToPlain)(value) : value]);
+/** Every non-empty part a block holds, as one side of an added or removed block. */
+const allParts = (block, side) => propertiesOf(block).flatMap(([key, value]) => {
+    const leaves = Array.isArray(value)
+        ? value.flatMap((entry, index) => entryLeaves(entry).map(({ at, value: part }) => ({ path: [key, index, ...at], value: part })))
+        : [{ path: [key], value: leaf(value) }];
+    return leaves
+        .filter(({ value: part }) => part !== null && part !== '')
+        .map(({ path, value: part }) => (side === 'new' ? { path, old: null, new: part } : { path, old: part, new: null }));
+});
+/**
+ * The index pairs of the longest common subsequence of two lists, compared by `key` - the
+ * entries that kept their relative order. Lists are capped (200 blocks, 500 rows), so the
+ * quadratic table stays small.
+ */
+const commonOrder = (before, after, key) => {
+    const a = before.map(key);
+    const b = after.map(key);
+    const lengths = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = a.length - 1; i >= 0; i--) {
+        for (let j = b.length - 1; j >= 0; j--) {
+            lengths[i][j] = a[i] === b[j] ? lengths[i + 1][j + 1] + 1 : Math.max(lengths[i + 1][j], lengths[i][j + 1]);
+        }
+    }
+    const pairs = [];
+    for (let i = 0, j = 0; i < a.length && j < b.length;) {
+        if (a[i] === b[j]) {
+            pairs.push([i, j]);
+            i++;
+            j++;
+        }
+        else if (lengths[i + 1][j] >= lengths[i][j + 1]) {
+            i++;
+        }
+        else {
+            j++;
+        }
+    }
+    return pairs;
+};
+/**
+ * What changed in one list property (fields, items, rows, signers, columns): entries that stayed
+ * put are matched first, so a row added in the middle reads as one added row rather than every
+ * row below it changing; the unmatched entries between two matches pair up in order as edits,
+ * and what is left over was added or removed.
+ */
+const listParts = (key, before, after) => {
+    const parts = [];
+    const anchors = [...commonOrder(before, after, (entry) => JSON.stringify(entry)), [before.length, after.length]];
+    let i = 0;
+    let j = 0;
+    for (const [nextI, nextJ] of anchors) {
+        const paired = Math.min(nextI - i, nextJ - j);
+        for (let k = 0; k < paired; k++) {
+            const old = new Map(entryLeaves(before[i + k]).map(({ at, value }) => [JSON.stringify(at), { at, value }]));
+            const next = new Map(entryLeaves(after[j + k]).map(({ at, value }) => [JSON.stringify(at), { at, value }]));
+            for (const at of new Set([...old.keys(), ...next.keys()])) {
+                const was = old.get(at)?.value ?? null;
+                const now = next.get(at)?.value ?? null;
+                if (was === now)
+                    continue;
+                parts.push({ path: [key, j + k, ...(old.get(at) ?? next.get(at)).at], old: was, new: now });
+            }
+        }
+        for (let k = i + paired; k < nextI; k++) {
+            for (const { at, value } of entryLeaves(before[k])) {
+                if (value !== null && value !== '')
+                    parts.push({ path: [key, k, ...at], old: value, new: null });
+            }
+        }
+        for (let k = j + paired; k < nextJ; k++) {
+            for (const { at, value } of entryLeaves(after[k])) {
+                if (value !== null && value !== '')
+                    parts.push({ path: [key, k, ...at], old: null, new: value });
+            }
+        }
+        i = nextI + 1;
+        j = nextJ + 1;
+    }
+    return parts;
+};
+const blockId = (block) => ((0, values_1.isObject)(block) ? String(block.id) : '');
+/**
+ * Each block a save added, removed, moved or edited, in the order they now stand (a removed one
+ * where it stood). Blocks are matched by id. A block counts as moved only when it left the
+ * order the others kept - adding or removing one above it does not move it. A block whose JSON
+ * changed with no printable part changing (bold added to a word) is CHANGED with no parts.
+ */
+const blockChanges = (before, after) => {
+    const blocksBefore = before.filter(values_1.isObject);
+    const blocksAfter = after.filter(values_1.isObject);
+    const at = new Map(blocksBefore.map((block, index) => [blockId(block), index]));
+    const atAfter = new Map(blocksAfter.map((block, index) => [blockId(block), index]));
+    const keptBefore = blocksBefore.filter((block) => atAfter.has(blockId(block)));
+    const keptAfter = blocksAfter.filter((block) => at.has(blockId(block)));
+    const stayed = new Set(commonOrder(keptBefore, keptAfter, blockId).map(([index]) => blockId(keptBefore[index])));
+    const changes = [];
+    for (const block of blocksBefore) {
+        if (atAfter.has(blockId(block)))
+            continue;
+        changes.push({
+            id: blockId(block),
+            type: block.type,
+            kind: enum_1.DocumentChangeKind.REMOVED,
+            from: at.get(blockId(block)) + 1,
+            to: null,
+            parts: allParts(block, 'old'),
+        });
+    }
+    for (const block of blocksAfter) {
+        const id = blockId(block);
+        const to = atAfter.get(id) + 1;
+        const index = at.get(id);
+        if (index === undefined) {
+            changes.push({ id, type: block.type, kind: enum_1.DocumentChangeKind.ADDED, from: null, to, parts: allParts(block, 'new') });
+            continue;
+        }
+        const earlier = blocksBefore[index];
+        const moved = !stayed.has(id);
+        if (!moved && same(earlier, block))
+            continue;
+        // The parts that differ between the two saves of the block; none when it only moved.
+        const old = new Map(propertiesOf(earlier));
+        const next = new Map(propertiesOf(block));
+        const parts = [...new Set([...old.keys(), ...next.keys()])].flatMap((key) => {
+            const was = old.get(key);
+            const now = next.get(key);
+            if (same(was ?? null, now ?? null))
+                return [];
+            if (Array.isArray(was) || Array.isArray(now)) {
+                return listParts(key, Array.isArray(was) ? was : [], Array.isArray(now) ? now : []);
+            }
+            return [{ path: [key], old: leaf(was), new: leaf(now) }];
+        });
+        changes.push({
+            id,
+            type: block.type,
+            kind: same(earlier, block) ? enum_1.DocumentChangeKind.MOVED : enum_1.DocumentChangeKind.CHANGED,
+            from: index + 1,
+            to,
+            parts,
+        });
+    }
+    return changes.sort((a, b) => (a.to ?? a.from ?? 0) - (b.to ?? b.from ?? 0));
+};
+exports.blockChanges = blockChanges;
+// ------------------------------------------------------------
+// Variables and values
+// ------------------------------------------------------------
+const VARIABLE_FIELDS = ['label', 'type', 'required', 'default_value'];
+const byKey = (variables) => new Map(variables.filter(values_1.isObject).map((variable) => [String(variable.key), variable]));
+/** Each variable definition a save added, removed or edited, by key, in the order they now stand. */
+const variableChanges = (before, after) => {
+    const old = byKey(before);
+    const next = byKey(after);
+    const changes = [];
+    for (const key of new Set([...next.keys(), ...old.keys()])) {
+        const was = old.get(key);
+        const now = next.get(key);
+        const parts = VARIABLE_FIELDS.map((field) => ({ field, old: was ? leaf(was[field]) : null, new: now ? leaf(now[field]) : null }))
+            .filter((part) => part.old !== part.new);
+        if (parts.length === 0)
+            continue;
+        changes.push({
+            key,
+            label: String((now ?? was).label ?? key),
+            kind: !was ? enum_1.DocumentChangeKind.ADDED : !now ? enum_1.DocumentChangeKind.REMOVED : enum_1.DocumentChangeKind.CHANGED,
+            parts,
+        });
+    }
+    return changes;
+};
+exports.variableChanges = variableChanges;
+const valueOf = (value) => typeof value === 'string' || typeof value === 'number' ? value : null;
+/**
+ * Each filled-in value a save changed, by key, labelled and typed by the definitions as they
+ * now stand (as they stood, for a variable since removed). A key no definition names - a system
+ * variable frozen at issue - has a null label and type.
+ */
+const valueChanges = (before, after, variablesBefore, variablesAfter) => {
+    const definitions = new Map([
+        ...byKey(Array.isArray(variablesBefore) ? variablesBefore : []),
+        ...byKey(Array.isArray(variablesAfter) ? variablesAfter : []),
+    ]);
+    return [...new Set([...Object.keys(after), ...Object.keys(before)])].flatMap((key) => {
+        const old = valueOf(before[key]);
+        const next = valueOf(after[key]);
+        if (old === next)
+            return [];
+        const definition = definitions.get(key);
+        return [{
+                key,
+                label: definition ? String(definition.label) : null,
+                type: definition ? definition.type : null,
+                old,
+                new: next,
+            }];
+    });
+};
+exports.valueChanges = valueChanges;
+// ------------------------------------------------------------
+// The entry
+// ------------------------------------------------------------
+/** The columns of `document_templates` and `documents` recorded as what changed inside them. */
+exports.DOCUMENT_CONTENT_COLUMNS = ['blocks', 'variables', 'variable_values', 'email'];
+const REDACTED = '[redacted]';
+/** The marker for one side of a bulk column, keeping which side was empty. */
+const marker = (value) => (value === null || value === undefined ? null : REDACTED);
+/**
+ * A template's or document's changes as they are stored. Its `blocks` and `variables` arrive
+ * whole on both sides of an update and leave as `'[redacted]'` with a `diff` of what moved inside
+ * them; a created or deleted row keeps the plain markers (the whole JSON is not copied). Its
+ * `variable_values` leave the same way with a values `diff`, labelled by `variables` (the row's
+ * definitions before and after the event). Its `email` keeps only the keys that changed. A column
+ * whose JSON changed with nothing printable changing (variables reordered) is dropped.
+ */
+const compactDocumentChanges = (changes, variables) => {
+    const out = { ...changes };
+    for (const column of ['blocks', 'variables']) {
+        const change = out[column];
+        if (!change)
+            continue;
+        if (!Array.isArray(change.old) || !Array.isArray(change.new)) {
+            out[column] = { old: marker(change.old), new: marker(change.new) };
+            continue;
+        }
+        const diff = column === 'blocks' ? (0, exports.blockChanges)(change.old, change.new) : (0, exports.variableChanges)(change.old, change.new);
+        if (diff.length === 0)
+            delete out[column];
+        else
+            out[column] = { old: REDACTED, new: REDACTED, diff };
+    }
+    const values = out.variable_values;
+    if (values && ((0, values_1.isObject)(values.old) || (0, values_1.isObject)(values.new))) {
+        const diff = (0, exports.valueChanges)((0, values_1.isObject)(values.old) ? values.old : {}, (0, values_1.isObject)(values.new) ? values.new : {}, variables.old, variables.new);
+        if (diff.length === 0)
+            delete out.variable_values;
+        else
+            out.variable_values = { old: marker(values.old), new: marker(values.new), diff };
+    }
+    const email = out.email;
+    if (email && (0, values_1.isObject)(email.old) && (0, values_1.isObject)(email.new)) {
+        const was = email.old;
+        const now = email.new;
+        const moved = [...new Set([...Object.keys(was), ...Object.keys(now)])].filter((key) => !same(was[key] ?? null, now[key] ?? null));
+        if (moved.length === 0)
+            delete out.email;
+        else {
+            out.email = {
+                old: Object.fromEntries(moved.map((key) => [key, was[key] ?? null])),
+                new: Object.fromEntries(moved.map((key) => [key, now[key] ?? null])),
+            };
+        }
+    }
+    return out;
+};
+exports.compactDocumentChanges = compactDocumentChanges;