@managemint-solutions/sdk 0.8.0 → 0.9.0

package/README.md

@@ -15,7 +15,8 @@ are peer dependencies — the request DTOs (`AddStatusDto`, `UpdateStatusDto`, `
 `AdditionalDetailsIdDto`, `GetAdditionalDetailsDto`, `AddNoteDto`, `NoteIdDto`,
 `GetNotesDto`, `SupportingFileIdDto`, `GetSupportingFilesDto`, `GetClientsDto`, `ClientIdDto`,
 `CreateClientDto`, `UpdateClientDto`, `GetProjectsDto`, `ProjectIdDto`, `CreateProjectDto`,
-`UpdateProjectDto`, `GetTasksDto`, `TaskIdDto`, `CreateTaskDto`, `UpdateTaskDto`, `SignInDto`,
+`UpdateProjectDto`, `GetTasksDto`, `TaskIdDto`, `CreateTaskDto`, `UpdateTaskDto`,
+`GetAuditTrailDto`, `SignInDto`,
 `ExchangeRefreshTokenDto`, `SendPasswordResetEmailDto`, `ExchangeTokenHashDto`,
 `ResetPasswordDto`) ship with their class-validator
 decorators so consumers validate against
@@ -198,6 +199,77 @@ The client decodes `{ mms_id, organization_id }` from the JWT itself and scopes
 by `organization_id`. `supabase.supabase` is the raw `@supabase/supabase-js` client
 (`TypedSupabaseClient`) — the escape hatch for queries not yet covered by a resource.
 
+## Audit
+
+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
+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`,
+`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.
+
+```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.
+```
+
+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.
+
+```ts
+const supabase = createSupabaseClient({
+  url, key, accessToken,
+  onAuditError: (error, entries) => Sentry.captureException(error, { extra: { entries } }),
+});
+```
+
+With the Nest decorator there is nowhere to pass config per request, so the handler is registered
+once at startup — after Sentry is initialised, before the app listens:
+
+```ts
+import { configureSupabaseUserClient } from '@managemint-solutions/sdk/nest';
+
+configureSupabaseUserClient({ onAuditError: (error) => Sentry.captureException(error) });
+```
+
+Consumers writing tables the SDK has no resource for (the api's admin-client modules) use the same
+helper over their own client, so they carry no audit code either:
+
+```ts
+import { AuditResource, auditedTable } from '@managemint-solutions/sdk';
+import { AuditTrailAction, AuditTrailEntityType } from '@managemint-solutions/entities/audit-trail/enum';
+
+const actor = { mms_id: authUser.mms_id, organization_id: authUser.organization_id }; // mms_id: null for system jobs
+const audit = new AuditResource(adminClient, actor, onAuditError);
+const users = auditedTable(adminClient, actor, audit, {
+  table: 'users',
+  entityType: AuditTrailEntityType.USER,
+});
+
+const row = await users.insert({ ...payload, organization_id: actor.organization_id });
+await users.update(userId, { name: 'Ada' });                              // records UPDATE
+await users.update(userId, (before) => ({ active: !before.active }));     // payload from the pre-read
+await users.transition(userId, AuditTrailAction.DELETE, { deleted: true }); // records the given action
+const deleted = await users.remove(userId);                              // hard delete; returns the old row
+```
+
+`update` / `transition` / `remove` 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. `diffChanges(before, after)` and
+`snapshotChanges(row, 'new' | 'old')` are exported as pure functions if you need them directly.
+
+Only what goes through the SDK/API is logged — a raw PostgREST write or a dashboard edit is not.
+
 ## Auth
 
 `SupabaseClient` needs the caller's JWT, which the auth flows are there to produce — so sign-in,

package/dist/additional-details/index.d.ts

@@ -2,13 +2,15 @@ import type { AdditionalDetailSummary, AdditionalDetailsEntity } from '@managemi
 import type { AddAdditionalDetailsDto, UpdateAdditionalDetailsDto } from '@managemint-solutions/entities/additional-details/dto';
 import { AdditionalDetailsEntityTypes } from '@managemint-solutions/entities/additional-details/enum';
 import type { AuthContext } from '../auth';
+import { type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 export * from './dto';
 export * from './values';
 export declare class AdditionalDetailsResource {
     private readonly supabase;
     private readonly auth;
-    constructor(supabase: TypedSupabaseClient, auth: AuthContext);
+    private readonly table;
+    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
     getById(additionalDetailsId: string): Promise<AdditionalDetailsEntity>;
     list(entity: AdditionalDetailsEntityTypes, entityId: string): Promise<AdditionalDetailSummary[]>;
     create(entity: AdditionalDetailsEntityTypes, entityId: string, input: AddAdditionalDetailsDto): Promise<AdditionalDetailsEntity>;

package/dist/additional-details/index.js

@@ -15,6 +15,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AdditionalDetailsResource = void 0;
+const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
+const audit_1 = require("../audit");
 const errors_1 = require("../errors");
 const values_1 = require("./values");
 __exportStar(require("./dto"), exports);
@@ -33,9 +35,14 @@ const withCastValue = (detail) => ({
 class AdditionalDetailsResource {
     supabase;
     auth;
-    constructor(supabase, auth) {
+    table;
+    constructor(supabase, auth, audit) {
         this.supabase = supabase;
         this.auth = auth;
+        this.table = (0, audit_1.auditedTable)(supabase, auth, audit, {
+            table: 'additional_details',
+            entityType: enum_1.AuditTrailEntityType.ADDITIONAL_DETAILS,
+        });
     }
     async getById(additionalDetailsId) {
         const { data, error } = await this.supabase
@@ -61,9 +68,7 @@ class AdditionalDetailsResource {
         return data.map(withCastValue);
     }
     async create(entity, entityId, input) {
-        const { data, error } = await this.supabase
-            .from('additional_details')
-            .insert({
+        const row = await this.table.insert({
             organization_id: this.auth.organization_id,
             entity_type: entity,
             entity_id: entityId,
@@ -72,40 +77,22 @@ class AdditionalDetailsResource {
             type: input.type,
             copyable: input.copyable,
             created_by: this.auth.mms_id,
-        })
-            .select(ADDITIONAL_DETAILS_SELECT)
-            .single();
-        if (error)
-            throw (0, errors_1.mapPostgrestError)(error);
-        return withCastValue(data);
+        });
+        return this.getById(row.mms_id);
     }
     async update(additionalDetailsId, input) {
-        const { data, error } = await this.supabase
-            .from('additional_details')
-            .update({
+        await this.table.update(additionalDetailsId, {
             key: input.key,
             value: (0, values_1.serializeValue)(input.value),
             type: input.type,
             copyable: input.copyable,
             updated_at: new Date().toISOString(),
             last_updated_by: this.auth.mms_id,
-        })
-            .eq('mms_id', additionalDetailsId)
-            .eq('organization_id', this.auth.organization_id)
-            .select(ADDITIONAL_DETAILS_SELECT)
-            .single();
-        if (error)
-            throw (0, errors_1.mapPostgrestError)(error);
-        return withCastValue(data);
+        });
+        return this.getById(additionalDetailsId);
     }
     async remove(additionalDetailsId) {
-        const { error } = await this.supabase
-            .from('additional_details')
-            .delete()
-            .eq('mms_id', additionalDetailsId)
-            .eq('organization_id', this.auth.organization_id);
-        if (error)
-            throw (0, errors_1.mapPostgrestError)(error);
+        await this.table.remove(additionalDetailsId);
     }
 }
 exports.AdditionalDetailsResource = AdditionalDetailsResource;

package/dist/additional-details/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/additional-details/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/additional-details/index.ts"],"names":[],"mappings":"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"}

package/dist/audit/dto.d.ts

@@ -0,0 +1,13 @@
+import { AuditTrailAction, 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;
+}

package/dist/audit/dto.js

@@ -0,0 +1,90 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetAuditTrailDto = void 0;
+const class_validator_1 = require("class-validator");
+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.
+class GetAuditTrailDto {
+    search;
+    page = 1;
+    page_size = 10;
+    created_after;
+    created_before;
+    created_by;
+    action;
+    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 }),
+    (0, class_validator_1.IsNumber)({}, { message: 'Page must be a number' }),
+    (0, class_validator_1.Min)(1, { message: 'Page must be at least 1' }),
+    __metadata("design:type", Number)
+], GetAuditTrailDto.prototype, "page", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_transformer_1.Transform)(({ value }) => value ? Number(value) : 10, { toClassOnly: true }),
+    (0, class_validator_1.IsNumber)({}, { message: 'Page size must be a number' }),
+    (0, class_validator_1.Min)(1, { message: 'Page size must be at least 1' }),
+    (0, class_validator_1.Max)(100, { message: 'Page size cannot exceed 100' }),
+    __metadata("design:type", Number)
+], GetAuditTrailDto.prototype, "page_size", void 0);
+__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)(),
+    (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(', ')}` }),
+    __metadata("design:type", Object)
+], GetAuditTrailDto.prototype, "action", 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)(),
+    (0, class_validator_1.IsUUID)('4', { message: 'Entity ID must be a valid UUID v4' }),
+    __metadata("design:type", Object)
+], GetAuditTrailDto.prototype, "entity_id", void 0);
+//# sourceMappingURL=dto.js.map

package/dist/audit/dto.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dto.js","sourceRoot":"","sources":["../../src/audit/dto.ts"],"names":[],"mappings":"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"}

package/dist/audit/index.d.ts

@@ -0,0 +1,89 @@
+import type { SupabaseClient as SupabaseJsClient } from '@supabase/supabase-js';
+import type { AuditTrailEntity } from '@managemint-solutions/entities/audit-trail';
+import { AuditTrailAction, type AuditTrailEntityType } from '@managemint-solutions/entities/audit-trail/enum';
+import type { MmsList } from '@managemint-solutions/entities/common';
+import type { GetAuditTrailDto } from './dto';
+export * from './dto';
+/**
+ * Who a write is attributed to. `AuthContext` is assignable to it; the api's admin-client
+ * modules build one by hand (system jobs pass `mms_id: null` — `created_by` is nullable).
+ */
+export type AuditActor = {
+    mms_id: string | null;
+    organization_id: string;
+};
+/** A flat database row — always `select('*')`, never an entity shape with embedded joins. */
+export type AuditRow = Record<string, unknown>;
+export type AuditChanges = Record<string, {
+    old: unknown;
+    new: unknown;
+}>;
+export type AuditEntry = {
+    action: AuditTrailAction;
+    entityType: AuditTrailEntityType;
+    entityId: string;
+    changes: AuditChanges;
+    relatedEntityType?: string | null;
+    relatedEntityId?: string | null;
+};
+/** Called when the audit insert itself fails. The business write has already succeeded. */
+export type AuditErrorHandler = (error: unknown, entries: AuditEntry[]) => void;
+/**
+ * Bookkeeping columns a diff never reports: identity, tenancy and the who/when stamps of the
+ * transition itself (the action already says what happened), plus the `entity_type`/`entity_id`
+ * pair, which becomes `related_entity_*` on the audit row instead.
+ */
+export declare const AUDIT_EXCLUDED_COLUMNS: ReadonlySet<string>;
+/**
+ * The fields that differ between two flat rows, as `{ field: { old, new } }`. Values stay real
+ * JSON (booleans stay booleans, jsonb stays an object) and are compared by serialized value, so
+ * arrays and objects are equal when their contents are.
+ */
+export declare const diffChanges: (before: AuditRow, after: AuditRow) => AuditChanges;
+/**
+ * A whole row as a change set — `'new'` for an insert, `'old'` for a hard delete — so the trail
+ * stays self-contained once the row is gone. Columns that hold nothing are left out.
+ */
+export declare const snapshotChanges: (row: AuditRow, side: "new" | "old") => AuditChanges;
+/**
+ * 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.
+ */
+export declare class AuditResource {
+    private readonly supabase;
+    private readonly actor;
+    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.
+     */
+    record(entry: AuditEntry | AuditEntry[]): Promise<void>;
+    list(query: GetAuditTrailDto): Promise<MmsList<AuditTrailEntity>>;
+}
+export type AuditedTableOptions = {
+    table: string;
+    entityType: AuditTrailEntityType;
+    /**
+     * Whether rows are scoped by `organization_id` (the default). `false` for the `organizations`
+     * table itself, whose own `mms_id` is the organization.
+     */
+    scopeByOrganization?: boolean;
+};
+/** The payload to write, or a function of the pre-read row (`togglePin`'s `!before.pinned`). */
+type AuditedPayload = AuditRow | ((before: AuditRow) => AuditRow);
+export type AuditedTable = {
+    insert(payload: AuditRow): Promise<AuditRow>;
+    insertMany(payloads: AuditRow[]): Promise<AuditRow[]>;
+    update(id: string, payload: AuditedPayload): Promise<AuditRow>;
+    transition(id: string, action: AuditTrailAction, payload: AuditedPayload): Promise<AuditRow>;
+    /** Hard delete. Returns the row as it was, so the caller can still act on it. */
+    remove(id: string): Promise<AuditRow>;
+};
+/**
+ * The audited write helper every resource writes through: it does the pre-read, the write, the
+ * diff and the `audit_logs` insert itself, so no feature carries audit code. The write fails
+ * loudly (`SupabaseClientError`); only the audit insert is swallowed.
+ */
+export declare const auditedTable: (supabase: SupabaseJsClient, actor: AuditActor, audit: AuditResource, options: AuditedTableOptions) => AuditedTable;