@managemint-solutions/sdk 0.56.0 → 0.64.0

package/dist/visibility/index.d.ts

@@ -0,0 +1,59 @@
+import type { VisibilityShare } from '@managemint-solutions/entities/visibility';
+import { VisibilityEntityType, type VisibilityRole } from '@managemint-solutions/entities/visibility/enum';
+import { DocumentVisibility } from '@managemint-solutions/entities/documents/enum';
+import { type AuditActor, type AuditResource } from '../audit';
+import type { TypedSupabaseClient } from '../client';
+export * from './dto';
+/** One person and their role, as a write takes them. */
+export type VisibilityShareInput = {
+    user_id: string;
+    role: VisibilityRole;
+};
+/** A record a row is filed under: its kind (its table) and its id. */
+export type VisibilityRecord = {
+    entityType: VisibilityEntityType;
+    entityId: string;
+};
+/**
+ * Who each private record is shared with: `public.visibility`, one row per person per record,
+ * filed under the record's kind and id. On the service client's organization scope only -
+ * members read their own rows through the record policies and write none. entity_id has no
+ * foreign key (it points at several tables), so the caller first checks the record is in this
+ * organization; every query here is held to the scope's organization. Each write is audited
+ * against the record it is about, so it shows in that record's history.
+ */
+export declare class VisibilityResource {
+    private readonly supabase;
+    private readonly actor;
+    private readonly audit;
+    private readonly table;
+    constructor(supabase: TypedSupabaseClient, actor: AuditActor, audit: AuditResource);
+    /** A record's shares with each person, oldest first - `GET .../visibility`. */
+    list({ entityType, entityId }: VisibilityRecord): Promise<VisibilityShare[]>;
+    /**
+     * Makes a record's shares exactly `shares` - `PUT .../visibility`: people no longer listed lose
+     * their row, a changed role updates it, new people get one.
+     */
+    replace(record: VisibilityRecord, shares: VisibilityShareInput[]): Promise<void>;
+    /**
+     * Sets the record's own `visibility` column - `PUT .../visibility`. Members hold no UPDATE grant
+     * on it, so it is written here; audited as an update of the record itself.
+     */
+    setVisibility({ entityType, entityId }: VisibilityRecord, visibility: DocumentVisibility): Promise<void>;
+    /** Gives `to` the same shares as `from` - a document made from a private template. */
+    copy(from: VisibilityRecord, to: VisibilityRecord): Promise<void>;
+    /**
+     * Deletes a record's rows, after the record itself is deleted - nothing else would. One
+     * statement and unaudited: the record's own DELETE is its history's last word.
+     */
+    removeAll({ entityType, entityId }: VisibilityRecord): Promise<void>;
+    /**
+     * The owner's reassign: every record of `entityType` that `fromUserId` created and that is not
+     * shared with the organization becomes `toUserId`'s. Resolves to how many moved. One statement;
+     * `created_by` is a bookkeeping column, never in an audit diff.
+     */
+    reassign(entityType: VisibilityEntityType, fromUserId: string, toUserId: string): Promise<number>;
+    /** A record's rows, flat - what `replace` and `copy` work from. */
+    private rows;
+    private newRow;
+}

package/dist/visibility/index.js

@@ -0,0 +1,165 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+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.VisibilityResource = void 0;
+const enum_1 = require("@managemint-solutions/entities/visibility/enum");
+const enum_2 = require("@managemint-solutions/entities/documents/enum");
+const enum_3 = require("@managemint-solutions/entities/audit-trail/enum");
+const audit_1 = require("../audit");
+const errors_1 = require("../errors");
+const transforms_1 = require("../transforms");
+__exportStar(require("./dto"), exports);
+// The person is embedded through the composite same-organization key, named: visibility points
+// at users three times (the person, created_by, last_updated_by).
+const SHARE_SELECT = `role, user:users!visibility_user_fkey ${transforms_1.USER_PROFILE_EMBED}`;
+/** Each kind of record's own history, which a change to its visibility setting is filed in. */
+const RECORD_AUDIT_TYPES = {
+    [enum_1.VisibilityEntityType.DOCUMENT_TEMPLATES]: enum_3.AuditTrailEntityType.DOCUMENT_TEMPLATES,
+    [enum_1.VisibilityEntityType.DOCUMENTS]: enum_3.AuditTrailEntityType.DOCUMENTS,
+};
+/**
+ * Who each private record is shared with: `public.visibility`, one row per person per record,
+ * filed under the record's kind and id. On the service client's organization scope only -
+ * members read their own rows through the record policies and write none. entity_id has no
+ * foreign key (it points at several tables), so the caller first checks the record is in this
+ * organization; every query here is held to the scope's organization. Each write is audited
+ * against the record it is about, so it shows in that record's history.
+ */
+class VisibilityResource {
+    supabase;
+    actor;
+    audit;
+    table;
+    constructor(supabase, actor, audit) {
+        this.supabase = supabase;
+        this.actor = actor;
+        this.audit = audit;
+        this.table = (0, audit_1.auditedTable)(supabase, actor, audit, {
+            table: 'visibility',
+            entityType: enum_3.AuditTrailEntityType.VISIBILITY,
+            // Every share entry names its person, so the record's history says whose access changed.
+            identity: ['user_id'],
+        });
+    }
+    /** A record's shares with each person, oldest first - `GET .../visibility`. */
+    async list({ entityType, entityId }) {
+        const { data, error } = await this.supabase
+            .from('visibility')
+            .select(SHARE_SELECT)
+            .eq('organization_id', this.actor.organization_id)
+            .eq('entity_type', entityType)
+            .eq('entity_id', entityId)
+            .order('created_at', { ascending: true });
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return data;
+    }
+    /**
+     * Makes a record's shares exactly `shares` - `PUT .../visibility`: people no longer listed lose
+     * their row, a changed role updates it, new people get one.
+     */
+    async replace(record, shares) {
+        const existing = await this.rows(record);
+        const wanted = new Map(shares.map((share) => [share.user_id, share.role]));
+        const now = new Date().toISOString();
+        for (const row of existing) {
+            const role = wanted.get(row.user_id);
+            if (role === undefined) {
+                await this.table.remove(row.mms_id);
+            }
+            else if (role !== row.role) {
+                await this.table.update(row.mms_id, { role, updated_at: now, last_updated_by: this.actor.mms_id });
+            }
+        }
+        const added = shares.filter((share) => !existing.some((row) => row.user_id === share.user_id));
+        await this.table.insertMany(added.map((share) => this.newRow(record, share, now)));
+    }
+    /**
+     * Sets the record's own `visibility` column - `PUT .../visibility`. Members hold no UPDATE grant
+     * on it, so it is written here; audited as an update of the record itself.
+     */
+    async setVisibility({ entityType, entityId }, visibility) {
+        const record = (0, audit_1.auditedTable)(this.supabase, this.actor, this.audit, {
+            table: entityType,
+            entityType: RECORD_AUDIT_TYPES[entityType],
+        });
+        await record.update(entityId, {
+            visibility,
+            updated_at: new Date().toISOString(),
+            last_updated_by: this.actor.mms_id,
+        });
+    }
+    /** Gives `to` the same shares as `from` - a document made from a private template. */
+    async copy(from, to) {
+        const now = new Date().toISOString();
+        const rows = await this.rows(from);
+        await this.table.insertMany(rows.map((row) => this.newRow(to, row, now)));
+    }
+    /**
+     * Deletes a record's rows, after the record itself is deleted - nothing else would. One
+     * statement and unaudited: the record's own DELETE is its history's last word.
+     */
+    async removeAll({ entityType, entityId }) {
+        const { error } = await this.supabase
+            .from('visibility')
+            .delete()
+            .eq('organization_id', this.actor.organization_id)
+            .eq('entity_type', entityType)
+            .eq('entity_id', entityId);
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+    }
+    /**
+     * The owner's reassign: every record of `entityType` that `fromUserId` created and that is not
+     * shared with the organization becomes `toUserId`'s. Resolves to how many moved. One statement;
+     * `created_by` is a bookkeeping column, never in an audit diff.
+     */
+    async reassign(entityType, fromUserId, toUserId) {
+        const { error, count } = await this.supabase
+            .from(entityType)
+            .update({ created_by: toUserId }, { count: 'exact' })
+            .eq('organization_id', this.actor.organization_id)
+            .eq('created_by', fromUserId)
+            .neq('visibility', enum_2.DocumentVisibility.ORGANIZATION);
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return count ?? 0;
+    }
+    /** A record's rows, flat - what `replace` and `copy` work from. */
+    async rows({ entityType, entityId }) {
+        const { data, error } = await this.supabase
+            .from('visibility')
+            .select('mms_id, user_id, role')
+            .eq('organization_id', this.actor.organization_id)
+            .eq('entity_type', entityType)
+            .eq('entity_id', entityId);
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return data;
+    }
+    newRow({ entityType, entityId }, share, now) {
+        return {
+            organization_id: this.actor.organization_id,
+            entity_type: entityType,
+            entity_id: entityId,
+            user_id: share.user_id,
+            role: share.role,
+            created_by: this.actor.mms_id,
+            created_at: now,
+        };
+    }
+}
+exports.VisibilityResource = VisibilityResource;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@managemint-solutions/sdk",
-  "version": "0.56.0",
+  "version": "0.64.0",
   "description": "Typed Supabase data-access SDK for ManageMint Solutions",
   "license": "UNLICENSED",
   "author": "Scott Bebington <scottbebington@gmail.com>",
@@ -24,6 +24,10 @@
     "./cache": {
       "types": "./dist/cache/index.d.ts",
       "default": "./dist/cache/index.js"
+    },
+    "./documents": {
+      "types": "./dist/documents/render/index.d.ts",
+      "default": "./dist/documents/render/index.js"
     }
   },
   "files": [
@@ -51,7 +55,7 @@
     "testEnvironment": "node"
   },
   "dependencies": {
-    "@managemint-solutions/entities": "^1.37.0"
+    "@managemint-solutions/entities": "^1.46.0"
   },
   "peerDependencies": {
     "@nestjs/common": "^11.0.0",