@managemint-solutions/sdk 0.52.0 → 0.53.0

package/README.md

@@ -223,20 +223,27 @@ did it, and a `changes` diff of the flat table row as real JSON (`{ field: { old
 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`,
 `user_id`, `updated_at`, `last_updated_by`, `archived_*`, `unarchived_*`, `deleted_*`,
-`restored_*`, `entity_type`, `entity_id`); for the tables that hang off another entity (notes,
-additional details, supporting files) the `entity_type`/`entity_id` pair becomes the audit row's
-`related_entity_*` instead.
+`restored_*`, `entity_type`, `entity_id`); for the tables that hang off another entity the owner
+becomes the audit row's `related_entity_*` instead - the `entity_type`/`entity_id` pair of notes,
+additional details and supporting files, or the foreign key a table declares with `related`
+(timesheet entries to their timesheet, leave adjustments to their entitlement, permissions to
+their user).
+
+The trail is read one record at a time. Each resource with a record page exposes its history as
+`audit`: the record's own rows plus every row related to it, newest first.
 
 ```ts
-const trail = await supabase.audit.list({
-  page: 1,
-  page_size: 10,
-  entity_type: AuditTrailEntityType.CLIENTS,
-});
-// → MmsList<AuditTrailEntity>, newest first; filter by created_after/before, created_by,
-//   action, entity_type and entity_id.
+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.
+
+const names = await supabase.audit.names({ statuses: [statusId], users: [userId] });
+// → { [mms_id]: 'In Progress', ... } - readable names for the ids a page of history holds.
 ```
 
+Rows older than a year are deleted by the api's daily retention cron, through the service
+client's `purgeAuditLogsBefore(cutoff)`.
+
 An audit insert **never fails a business write**: if it fails, the error goes to `onAuditError`
 (default `console.error`) and the write still returns normally.
 

package/dist/audit/dto.d.ts

@@ -1,13 +1,8 @@
-import { AuditTrailAction, AuditTrailEntityType } from '@managemint-solutions/entities/audit-trail/enum';
+import { AuditTrailEntityType } from '@managemint-solutions/entities/audit-trail/enum';
 import type { GetAuditTrailDto as GetAuditTrailDtoType } from '@managemint-solutions/entities/audit-trail/dto';
 export declare class GetAuditTrailDto implements GetAuditTrailDtoType {
-    readonly search?: string | null;
     readonly page: number;
     readonly page_size: number;
-    readonly created_after?: string | null;
-    readonly created_before?: string | null;
-    readonly created_by: string | null;
-    readonly action: AuditTrailAction | null;
-    readonly entity_type: AuditTrailEntityType | null;
-    readonly entity_id: string | null;
+    readonly search?: string | null;
+    readonly entity_type?: AuditTrailEntityType | null;
 }

package/dist/audit/dto.js

@@ -15,27 +15,15 @@ const class_transformer_1 = require("class-transformer");
 const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
 const validators_1 = require("../validators");
 // class-validator version of the shared GetAuditTrailDto type from
-// @managemint-solutions/entities, so the wire contract cannot drift.
+// @managemint-solutions/entities, so the wire contract cannot drift. The record itself is the
+// filter; these page, search and narrow its history.
 class GetAuditTrailDto {
-    search;
     page = 1;
     page_size = 10;
-    created_after;
-    created_before;
-    created_by;
-    action;
+    search;
     entity_type;
-    entity_id;
 }
 exports.GetAuditTrailDto = GetAuditTrailDto;
-__decorate([
-    (0, class_validator_1.IsOptional)(),
-    (0, validators_1.IsNullable)(),
-    (0, class_validator_1.IsString)({ message: 'Search query must be a string' }),
-    (0, class_validator_1.MinLength)(1, { message: 'Search query cannot be empty' }),
-    (0, class_validator_1.MaxLength)(255, { message: 'Search query cannot exceed 255 characters' }),
-    __metadata("design:type", Object)
-], GetAuditTrailDto.prototype, "search", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
     (0, class_transformer_1.Transform)(({ value }) => value ? Number(value) : 1, { toClassOnly: true }),
@@ -54,43 +42,14 @@ __decorate([
 __decorate([
     (0, class_validator_1.IsOptional)(),
     (0, validators_1.IsNullable)(),
-    (0, class_validator_1.IsDateString)({}, { message: 'Start date must be a valid ISO 8601 date string' }),
-    __metadata("design:type", Object)
-], GetAuditTrailDto.prototype, "created_after", void 0);
-__decorate([
-    (0, class_validator_1.IsOptional)(),
-    (0, validators_1.IsNullable)(),
-    (0, class_validator_1.IsDateString)({}, { message: 'End date must be a valid ISO 8601 date string' }),
-    __metadata("design:type", Object)
-], GetAuditTrailDto.prototype, "created_before", void 0);
-__decorate([
-    (0, class_validator_1.IsOptional)(),
-    (0, validators_1.IsNullable)()
-    // Still v4: `audit_logs.created_by` is a `users.mms_id`, which is the GoTrue auth uid the
-    // signup trigger copies out of `auth.users.id` - the table's uuidv7 default never fires.
-    ,
-    (0, class_validator_1.IsUUID)('4', { message: 'Created by must be a valid UUID v4' }),
-    __metadata("design:type", Object)
-], GetAuditTrailDto.prototype, "created_by", void 0);
-__decorate([
-    (0, class_validator_1.IsOptional)(),
-    (0, validators_1.IsNullable)(),
-    (0, class_validator_1.IsEnum)(enum_1.AuditTrailAction, { message: `Action must be one of: ${Object.values(enum_1.AuditTrailAction).join(', ')}` }),
+    (0, class_validator_1.IsString)({ message: 'Search query must be a string' }),
+    (0, class_validator_1.MinLength)(1, { message: 'Search query cannot be empty' }),
+    (0, class_validator_1.MaxLength)(100, { message: 'Search query cannot exceed 100 characters' }),
     __metadata("design:type", Object)
-], GetAuditTrailDto.prototype, "action", void 0);
+], GetAuditTrailDto.prototype, "search", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
     (0, validators_1.IsNullable)(),
     (0, class_validator_1.IsEnum)(enum_1.AuditTrailEntityType, { message: `Entity type must be one of: ${Object.values(enum_1.AuditTrailEntityType).join(', ')}` }),
     __metadata("design:type", Object)
 ], GetAuditTrailDto.prototype, "entity_type", void 0);
-__decorate([
-    (0, class_validator_1.IsOptional)(),
-    (0, validators_1.IsNullable)()
-    // Both versions, deliberately: `entity_id` is polymorphic over `entity_type`, so it is a v7
-    // `mms_id` for every entity type except `users`, whose `mms_id` is the GoTrue auth uid (see
-    // UserIdDto). Pinning this to one version would make one of those two unfilterable.
-    ,
-    (0, class_validator_1.IsUUID)(['4', '7'], { message: 'Entity ID must be a valid UUID' }),
-    __metadata("design:type", Object)
-], GetAuditTrailDto.prototype, "entity_id", void 0);

package/dist/audit/index.d.ts

@@ -66,9 +66,18 @@ export declare const diffChanges: (before: AuditRow, after: AuditRow) => AuditCh
  * column that holds something is present, as `'[redacted]'`.
  */
 export declare const snapshotChanges: (row: AuditRow, side: "new" | "old") => AuditChanges;
+/** The tables a history's foreign-key values can be named from. */
+export type AuditNameTable = 'users' | 'statuses' | 'clients' | 'projects' | 'tasks' | 'leave_types';
 /**
- * The `audit_logs` table. Reads are the audit trail endpoint; writes go through `record`, which
- * every audited write calls for itself - no feature ever writes an audit line by hand.
+ * Runs `work` as one event: every audit entry recorded inside it - by any client or service
+ * scope - is held, then written once it settles (or throws, since its writes still happened)
+ * as **one row per record**. The api wraps each request in it, so a save that writes a task and
+ * its labels, or a webhook that moves an organization twice, logs one row, whatever code wrote it.
+ */
+export declare const withAuditBatch: <T>(work: () => Promise<T>) => Promise<T>;
+/**
+ * The `audit_logs` writer. Every audited write calls `record` for itself - no feature ever
+ * writes an audit line by hand. Reads are per record, through `EntityAuditTrail`.
  */
 export declare class AuditResource {
     private readonly supabase;
@@ -76,12 +85,42 @@ export declare class AuditResource {
     private readonly onError?;
     constructor(supabase: SupabaseJsClient, actor: AuditActor, onError?: AuditErrorHandler | undefined);
     /**
-     * Writes the audit row(s) - one insert, however many entries. **Never throws**: a logging
-     * problem must not fail the business write, so a failure goes to `onAuditError`
-     * (default `console.error`) instead.
+     * Records the entries: held by the current event's batch when there is one (`withAuditBatch`),
+     * written straight away when there is not.
      */
     record(entry: AuditEntry | AuditEntry[]): Promise<void>;
-    list(query: GetAuditTrailDto): Promise<MmsList<AuditTrailEntity>>;
+    /**
+     * Inserts the audit row(s) - one insert, however many entries. **Never throws**: a logging
+     * problem must not fail the business write, so a failure goes to `onAuditError`
+     * (default `console.error`) instead. Called by `record`, and by `withAuditBatch` when it
+     * writes what it held.
+     */
+    write(entries: AuditEntry[]): Promise<void>;
+    /**
+     * Readable names for the ids a page of history holds (`status_id`, `assigned_to_id`, ...),
+     * keyed by id: one query per table asked about. An id with no row - the record was hard
+     * deleted - is simply absent, and the caller says so.
+     */
+    names(ids: Partial<Record<AuditNameTable, string[]>>): Promise<Record<string, string>>;
+}
+/**
+ * One record's history: the rows about the record itself and every row that hangs off it (a
+ * note, a file, a timesheet entry, a user's permissions), newest first. Each resource with a
+ * record page exposes one as `audit`, so a client's history is `supabase.clients.audit.list(id)`.
+ */
+export declare class EntityAuditTrail {
+    private readonly supabase;
+    private readonly actor;
+    private readonly entityType;
+    constructor(supabase: SupabaseJsClient, actor: AuditActor, entityType: AuditTrailEntityType);
+    /**
+     * A page of the history. `entity_type` keeps the entries about one kind of record (the record
+     * itself, or its notes ...). `search` matches what a change recorded - the stored text, field
+     * names included - and, because a foreign key is stored as an id, also any change holding the
+     * id of a person, status, client, project, task or leave type whose name matches, and any
+     * change made by a person whose name matches.
+     */
+    list(entityId: string, query: GetAuditTrailDto): Promise<MmsList<AuditTrailEntity>>;
 }
 export type AuditedTableOptions = {
     table: string;
@@ -91,6 +130,22 @@ export type AuditedTableOptions = {
      * table itself, whose own `mms_id` is the organization.
      */
     scopeByOrganization?: boolean;
+    /**
+     * The record a row belongs to, for a table that hangs off one other table by a foreign key
+     * (`timesheet_entries.timesheet_id`). Its writes are recorded as related to that record, so
+     * they show in the record's history. The polymorphic tables need no option: their own
+     * `entity_type`/`entity_id` pair says whose they are.
+     */
+    related?: {
+        entityType: AuditTrailEntityType;
+        column: string;
+    };
+    /**
+     * Columns this table's trail never records - machinery whose history is kept elsewhere (an
+     * organization's subscription state lives in the billing ledger). A write that changes only
+     * these leaves nothing to record, so it writes no audit row at all.
+     */
+    untracked?: readonly string[];
 };
 /** The payload to write, or a function of the pre-read row (`togglePin`'s `!before.pinned`). */
 type AuditedPayload = AuditRow | ((before: AuditRow) => AuditRow);

package/dist/audit/index.js

@@ -14,7 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.auditedTable = exports.AuditResource = exports.snapshotChanges = exports.diffChanges = exports.isRedactedColumn = exports.AUDIT_REDACTED_COLUMNS = exports.AUDIT_EXCLUDED_COLUMNS = exports.withoutInternalId = void 0;
+exports.auditedTable = exports.EntityAuditTrail = exports.AuditResource = exports.withAuditBatch = exports.snapshotChanges = exports.diffChanges = exports.isRedactedColumn = exports.AUDIT_REDACTED_COLUMNS = exports.AUDIT_EXCLUDED_COLUMNS = exports.withoutInternalId = void 0;
+const node_async_hooks_1 = require("node:async_hooks");
 const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
 const errors_1 = require("../errors");
 const transforms_1 = require("../transforms");
@@ -121,6 +122,34 @@ const snapshotChanges = (row, side) => {
     return changes;
 };
 exports.snapshotChanges = snapshotChanges;
+/**
+ * Where each table's readable name comes from (`select`, `name`) and which columns a history
+ * search matches it by (`search`). People are read through `user_profiles`, which exposes
+ * nothing beyond the name; the view carries no `organization_id`, but it runs as the invoker,
+ * so the users RLS keeps it to the caller's tenant.
+ */
+const NAME_SOURCES = {
+    users: {
+        from: 'user_profiles',
+        select: 'mms_id, name, surname',
+        search: ['name', 'surname'],
+        scoped: false,
+        name: (row) => [row.name, row.surname].filter(Boolean).join(' '),
+    },
+    statuses: { from: 'statuses', select: 'mms_id, label', search: ['label'], scoped: true, name: (row) => String(row.label) },
+    clients: { from: 'clients', select: 'mms_id, name', search: ['name'], scoped: true, name: (row) => String(row.name) },
+    projects: { from: 'projects', select: 'mms_id, name', search: ['name'], scoped: true, name: (row) => String(row.name) },
+    tasks: {
+        from: 'tasks',
+        select: 'mms_id, task_id, name',
+        search: ['name'],
+        scoped: true,
+        name: (row) => `TASK-${row.task_id} ${row.name}`,
+    },
+    leave_types: { from: 'leave_types', select: 'mms_id, name', search: ['name'], scoped: true, name: (row) => String(row.name) },
+};
+// How many matching names per table a history search widens itself by.
+const SEARCH_NAME_LIMIT = 20;
 const AUDIT_TRAIL_SELECT = `
         mms_id,
         created_at,
@@ -132,9 +161,62 @@ const AUDIT_TRAIL_SELECT = `
         related_entity_id,
         changes
       `;
+/** The batch the current event records into, when there is one - see `withAuditBatch`. */
+const auditBatch = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * Runs `work` as one event: every audit entry recorded inside it - by any client or service
+ * scope - is held, then written once it settles (or throws, since its writes still happened)
+ * as **one row per record**. The api wraps each request in it, so a save that writes a task and
+ * its labels, or a webhook that moves an organization twice, logs one row, whatever code wrote it.
+ */
+const withAuditBatch = async (work) => {
+    const pending = [];
+    try {
+        return await auditBatch.run(pending, work);
+    }
+    finally {
+        // Entries about the same record fold together: each field keeps its first `old` and its
+        // last `new`. A record created in the event stays created; otherwise a lifecycle move
+        // (archive, delete, restore ...) says more than an update. The first writer writes the row.
+        const merged = new Map();
+        for (const { entry, writer } of pending) {
+            const key = `${entry.entityType}:${entry.entityId}`;
+            const earlier = merged.get(key);
+            if (!earlier) {
+                merged.set(key, { entry: { ...entry, changes: { ...entry.changes } }, writer });
+                continue;
+            }
+            for (const [field, change] of Object.entries(entry.changes)) {
+                const first = earlier.entry.changes[field];
+                earlier.entry.changes[field] = { old: first ? first.old : change.old, new: change.new };
+            }
+            if (earlier.entry.action !== enum_1.AuditTrailAction.INSERT && entry.action !== enum_1.AuditTrailAction.UPDATE) {
+                earlier.entry.action = entry.action;
+            }
+            earlier.entry.relatedEntityType ??= entry.relatedEntityType;
+            earlier.entry.relatedEntityId ??= entry.relatedEntityId;
+        }
+        const byWriter = new Map();
+        for (const { entry, writer } of merged.values()) {
+            // A field that ended where it started is no change (a redacted one reads the same on both
+            // sides by design, so it stays).
+            for (const [field, change] of Object.entries(entry.changes)) {
+                if (change.old !== REDACTED && JSON.stringify(change.old) === JSON.stringify(change.new)) {
+                    delete entry.changes[field];
+                }
+            }
+            // Updates that cancelled out changed nothing: no row.
+            if (entry.action === enum_1.AuditTrailAction.UPDATE && Object.keys(entry.changes).length === 0)
+                continue;
+            byWriter.set(writer, [...(byWriter.get(writer) ?? []), entry]);
+        }
+        await Promise.all([...byWriter].map(([writer, entries]) => writer.write(entries)));
+    }
+};
+exports.withAuditBatch = withAuditBatch;
 /**
- * The `audit_logs` table. Reads are the audit trail endpoint; writes go through `record`, which
- * every audited write calls for itself - no feature ever writes an audit line by hand.
+ * The `audit_logs` writer. Every audited write calls `record` for itself - no feature ever
+ * writes an audit line by hand. Reads are per record, through `EntityAuditTrail`.
  */
 class AuditResource {
     supabase;
@@ -146,14 +228,27 @@ class AuditResource {
         this.onError = onError;
     }
     /**
-     * Writes the audit row(s) - one insert, however many entries. **Never throws**: a logging
-     * problem must not fail the business write, so a failure goes to `onAuditError`
-     * (default `console.error`) instead.
+     * Records the entries: held by the current event's batch when there is one (`withAuditBatch`),
+     * written straight away when there is not.
      */
     async record(entry) {
         const entries = Array.isArray(entry) ? entry : [entry];
         if (entries.length === 0)
             return;
+        const batch = auditBatch.getStore();
+        if (batch) {
+            batch.push(...entries.map((item) => ({ entry: item, writer: this })));
+            return;
+        }
+        await this.write(entries);
+    }
+    /**
+     * Inserts the audit row(s) - one insert, however many entries. **Never throws**: a logging
+     * problem must not fail the business write, so a failure goes to `onAuditError`
+     * (default `console.error`) instead. Called by `record`, and by `withAuditBatch` when it
+     * writes what it held.
+     */
+    async write(entries) {
         try {
             const { error } = await this.supabase.from('audit_logs').insert(entries.map((item) => ({
                 created_by: this.actor.mms_id,
@@ -173,43 +268,104 @@ class AuditResource {
             handle(error, entries);
         }
     }
-    async list(query) {
+    /**
+     * Readable names for the ids a page of history holds (`status_id`, `assigned_to_id`, ...),
+     * keyed by id: one query per table asked about. An id with no row - the record was hard
+     * deleted - is simply absent, and the caller says so.
+     */
+    async names(ids) {
+        const lookups = Object.entries(ids).filter(([, list]) => list.length > 0);
+        const pages = await Promise.all(lookups.map(async ([table, list]) => {
+            const source = NAME_SOURCES[table];
+            // `eq`/`in` return `this`, so the org filter can be reassigned onto the builder.
+            let query = this.supabase.from(source.from).select(source.select).in('mms_id', [...new Set(list)]);
+            if (source.scoped)
+                query = query.eq('organization_id', this.actor.organization_id);
+            const { data, error } = await query;
+            if (error)
+                throw (0, errors_1.mapPostgrestError)(error);
+            return (data ?? []).map((row) => [String(row.mms_id), source.name(row)]);
+        }));
+        return Object.fromEntries(pages.flat());
+    }
+}
+exports.AuditResource = AuditResource;
+/**
+ * One record's history: the rows about the record itself and every row that hangs off it (a
+ * note, a file, a timesheet entry, a user's permissions), newest first. Each resource with a
+ * record page exposes one as `audit`, so a client's history is `supabase.clients.audit.list(id)`.
+ */
+class EntityAuditTrail {
+    supabase;
+    actor;
+    entityType;
+    constructor(supabase, actor, entityType) {
+        this.supabase = supabase;
+        this.actor = actor;
+        this.entityType = entityType;
+    }
+    /**
+     * A page of the history. `entity_type` keeps the entries about one kind of record (the record
+     * itself, or its notes ...). `search` matches what a change recorded - the stored text, field
+     * names included - and, because a foreign key is stored as an id, also any change holding the
+     * id of a person, status, client, project, task or leave type whose name matches, and any
+     * change made by a person whose name matches.
+     */
+    async list(entityId, query) {
         const page = query.page;
         const pageSize = query.page_size;
         const offset = (page - 1) * pageSize;
-        // `order`/`range` return `this`, so the builder stays a filter builder and the conditional
-        // filters below can be reassigned onto it without a cast.
-        let auditTrailQuery = this.supabase
+        // `entityId` is interpolated into the filter: callers pass a uuid their route DTO has
+        // already validated. The two halves are served by the by-entity and by-related indexes.
+        let filter = `or(and(entity_type.eq.${this.entityType},entity_id.eq.${entityId}),` +
+            `and(related_entity_type.eq.${this.entityType},related_entity_id.eq.${entityId}))`;
+        const search = query.search?.trim();
+        if (search) {
+            const named = await Promise.all(Object.entries(NAME_SOURCES).map(async ([table, source]) => {
+                // `or`/`eq` return `this`, so the org filter can be reassigned onto the builder.
+                let lookup = this.supabase
+                    .from(source.from)
+                    .select('mms_id')
+                    .or((0, transforms_1.orIlike)(source.search, search))
+                    .limit(SEARCH_NAME_LIMIT);
+                if (source.scoped)
+                    lookup = lookup.eq('organization_id', this.actor.organization_id);
+                const { data: rows, error: lookupError } = await lookup;
+                if (lookupError)
+                    throw (0, errors_1.mapPostgrestError)(lookupError);
+                return { table, ids: (rows ?? []).map((row) => row.mms_id) };
+            }));
+            const people = named.find((match) => match.table === 'users')?.ids ?? [];
+            const matches = [
+                `search_text.ilike.${(0, transforms_1.ilikeContains)(search)}`,
+                ...named.flatMap((match) => match.ids.map((id) => `search_text.ilike.${(0, transforms_1.ilikeContains)(id)}`)),
+                ...(people.length > 0 ? [`created_by.in.(${people.join(',')})`] : []),
+            ];
+            filter = `and(${filter},or(${matches.join(',')}))`;
+        }
+        // `eq` returns `this`, so the type filter can be reassigned onto the builder.
+        let historyQuery = this.supabase
             .from('audit_logs')
-            .select(AUDIT_TRAIL_SELECT, { count: 'estimated' })
+            // Exact, not estimated: one record's history is small and index-backed, and the pager
+            // must not offer a page that is not there.
+            .select(AUDIT_TRAIL_SELECT, { count: 'exact' })
             .eq('organization_id', this.actor.organization_id)
+            // One element, so the record and the search can nest as `and(or(...),or(...))`.
+            .or(filter);
+        if (query.entity_type)
+            historyQuery = historyQuery.eq('entity_type', query.entity_type);
+        const { data, error, count } = await historyQuery
             .order('created_at', { ascending: false })
+            // A multi-row insert stamps every row with the same `created_at`; the time-ordered v7
+            // `mms_id` keeps the pages stable.
+            .order('mms_id', { ascending: false })
             .range(offset, offset + pageSize - 1);
-        if (query.created_after) {
-            auditTrailQuery = auditTrailQuery.gte('created_at', query.created_after);
-        }
-        if (query.created_before) {
-            auditTrailQuery = auditTrailQuery.lte('created_at', query.created_before);
-        }
-        if (query.created_by) {
-            auditTrailQuery = auditTrailQuery.eq('created_by', query.created_by);
-        }
-        if (query.action) {
-            auditTrailQuery = auditTrailQuery.eq('action', query.action);
-        }
-        if (query.entity_type) {
-            auditTrailQuery = auditTrailQuery.eq('entity_type', query.entity_type);
-        }
-        if (query.entity_id) {
-            auditTrailQuery = auditTrailQuery.eq('entity_id', query.entity_id);
-        }
-        const { data, error, count } = await auditTrailQuery;
         if (error)
             throw (0, errors_1.mapPostgrestError)(error);
         return (0, transforms_1.toMmsList)(data, page, pageSize, count);
     }
 }
-exports.AuditResource = AuditResource;
+exports.EntityAuditTrail = EntityAuditTrail;
 /** The keyed update every audited write builds, before any caller-supplied guard. */
 const buildUpdate = (supabase, table, id, payload, organizationId) => {
     // `eq` returns `this`, so the org filter can be reassigned onto the builder without a cast.
@@ -225,12 +381,19 @@ const buildUpdate = (supabase, table, id, payload, organizationId) => {
  */
 const auditedTable = (supabase, actor, audit, options) => {
     const scoped = options.scopeByOrganization !== false;
-    // Tables that hang off another entity (notes, additional details, supporting files) carry the
-    // owner in `entity_type`/`entity_id`; the audit row records it as the related entity.
-    const relatedOf = (row) => ({
-        relatedEntityType: row.entity_type ?? null,
-        relatedEntityId: row.entity_id ?? null,
-    });
+    // The record a row belongs to: the declared foreign key, or the owner the polymorphic tables
+    // (notes, additional details, supporting files) carry in `entity_type`/`entity_id`. A row with
+    // a type and no id (statuses and labels name the kind of record they apply to) has no owner.
+    const relatedOf = (row) => {
+        const { related } = options;
+        const relatedEntityId = row[related?.column ?? 'entity_id'] ?? null;
+        if (!relatedEntityId)
+            return { relatedEntityType: null, relatedEntityId: null };
+        return {
+            relatedEntityType: related?.entityType ?? row.entity_type,
+            relatedEntityId,
+        };
+    };
     const read = async (id) => {
         // `eq` returns `this`, so the org filter can be reassigned onto the builder without a cast.
         let query = supabase.from(options.table).select('*').eq('mms_id', id);
@@ -243,13 +406,21 @@ const auditedTable = (supabase, actor, audit, options) => {
     };
     const organizationFilter = scoped ? actor.organization_id : null;
     const updateOf = (id, before, payload) => buildUpdate(supabase, options.table, id, typeof payload === 'function' ? payload(before) : payload, organizationFilter);
-    const recordWrite = (id, action, before, after) => audit.record({
-        action,
-        entityType: options.entityType,
-        entityId: id,
-        changes: (0, exports.diffChanges)(before, after),
-        ...relatedOf(before),
-    });
+    // The changes with the table's untracked columns taken out.
+    const tracked = (changes) => Object.fromEntries(Object.entries(changes).filter(([column]) => !options.untracked?.includes(column)));
+    // An update that changed nothing tracked is not an event: no row.
+    const recordWrite = async (id, action, before, after) => {
+        const changes = tracked((0, exports.diffChanges)(before, after));
+        if (action === enum_1.AuditTrailAction.UPDATE && Object.keys(changes).length === 0)
+            return;
+        await audit.record({
+            action,
+            entityType: options.entityType,
+            entityId: id,
+            changes,
+            ...relatedOf(before),
+        });
+    };
     const write = async (id, action, payload) => {
         const before = await read(id);
         const { data, error } = await updateOf(id, before, payload).select('*').single();
@@ -290,7 +461,7 @@ const auditedTable = (supabase, actor, audit, options) => {
                 action: enum_1.AuditTrailAction.INSERT,
                 entityType: options.entityType,
                 entityId: row.mms_id,
-                changes: (0, exports.snapshotChanges)(row, 'new'),
+                changes: tracked((0, exports.snapshotChanges)(row, 'new')),
                 ...relatedOf(row),
             });
             return (0, exports.withoutInternalId)(row);
@@ -306,7 +477,7 @@ const auditedTable = (supabase, actor, audit, options) => {
                 action: enum_1.AuditTrailAction.INSERT,
                 entityType: options.entityType,
                 entityId: row.mms_id,
-                changes: (0, exports.snapshotChanges)(row, 'new'),
+                changes: tracked((0, exports.snapshotChanges)(row, 'new')),
                 ...relatedOf(row),
             })));
             return rows.map(exports.withoutInternalId);
@@ -332,7 +503,7 @@ const auditedTable = (supabase, actor, audit, options) => {
                 action: enum_1.AuditTrailAction.DELETE,
                 entityType: options.entityType,
                 entityId: id,
-                changes: (0, exports.snapshotChanges)(before, 'old'),
+                changes: tracked((0, exports.snapshotChanges)(before, 'old')),
                 ...relatedOf(before),
             });
             return (0, exports.withoutInternalId)(before);

package/dist/clients/index.d.ts

@@ -1,7 +1,7 @@
 import type { ClientEntity, ClientSummary } from '@managemint-solutions/entities/clients';
 import type { MmsList } from '@managemint-solutions/entities/common';
 import type { AuthContext } from '../auth';
-import { type AuditResource } from '../audit';
+import { EntityAuditTrail, type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 import type { CreateClientDto, GetClientsDto, UpdateClientDto } from './dto';
 export * from './dto';
@@ -9,6 +9,8 @@ export declare class ClientsResource {
     private readonly supabase;
     private readonly auth;
     private readonly table;
+    /** This record's history - its own rows and the rows that hang off it. */
+    readonly audit: EntityAuditTrail;
     constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
     list(query: GetClientsDto): Promise<MmsList<ClientSummary>>;
     getById(clientId: string): Promise<ClientEntity>;

package/dist/clients/index.js

@@ -74,6 +74,8 @@ class ClientsResource {
     supabase;
     auth;
     table;
+    /** This record's history - its own rows and the rows that hang off it. */
+    audit;
     constructor(supabase, auth, audit) {
         this.supabase = supabase;
         this.auth = auth;
@@ -81,6 +83,7 @@ class ClientsResource {
             table: 'clients',
             entityType: enum_1.AuditTrailEntityType.CLIENTS,
         });
+        this.audit = new audit_1.EntityAuditTrail(supabase, auth, enum_1.AuditTrailEntityType.CLIENTS);
     }
     async list(query) {
         const page = query.page;

package/dist/index.d.ts

@@ -9,8 +9,8 @@ export type { SupabaseOrganizationScope, SupabaseServiceClientConfig } from './s
 export { SupabaseClientError } from './errors';
 export type { SupabaseClientErrorInit } from './errors';
 export { EmptyToNull, IsNullable } from './validators';
-export type { AuditActor, AuditChanges, AuditEntry, AuditErrorHandler, AuditGuard, AuditRow, AuditedTable, AuditedTableOptions, } from './audit';
-export { GetAuditTrailDto } from './audit';
+export type { AuditActor, AuditChanges, AuditEntry, AuditErrorHandler, AuditGuard, AuditNameTable, AuditRow, AuditedTable, AuditedTableOptions, EntityAuditTrail, } from './audit';
+export { GetAuditTrailDto, withAuditBatch } from './audit';
 export { CancelSubscriptionDto, GetPaymentsQueryDto, InitialPaymentDto, PaymentIdDto, PurchaseModuleDto, ReinstateSubscriptionDto, } from './billing';
 export { GetInvoicesQueryDto, InvoiceIdDto } from './billing/invoices';
 export type { CreateFeatureRequestRow, CreatedFeatureRequest } from './feature-requests';