@managemint-solutions/sdk 0.52.0 → 0.54.0

package/README.md

@@ -210,9 +210,10 @@ A task's `task_id` (its per-organization number) is assigned by the database on
 task carries its embedded `status`, `assigned_to`, `project` and `client`. The detail read also carries its `parent`,
 `subtasks` and `related` tasks, read from `task_links` in both directions.
 
-The client decodes `{ mms_id, organization_id }` from the JWT itself and scopes every query
-by `organization_id`. `supabase.supabase` is the raw `@supabase/supabase-js` client
-(`TypedSupabaseClient`) - the escape hatch for queries not yet covered by a resource.
+The client runs as the verified `{ mms_id, organization_id }` it is handed and scopes every
+query by `organization_id`. Staff have a client of their own (see Staff below).
+`supabase.supabase` is the raw `@supabase/supabase-js` client (`TypedSupabaseClient`) - the
+escape hatch for queries not yet covered by a resource.
 
 ## Audit
 
@@ -223,20 +224,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.
 
@@ -337,6 +345,77 @@ export class AuthController {
 }
 ```
 
+## Staff
+
+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.
+
+- **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
+  name, email).
+- **Every write is refused** with a `403 Permission Error` before any statement runs, as is the
+  tenant-only `organizations.get()`.
+
+```ts
+import { StaffGetClientsDto, type SupabaseStaffClient as StaffClient } from '@managemint-solutions/sdk';
+import { attachSupabaseStaffRequestContext, SupabaseStaffClient } from '@managemint-solutions/sdk/nest';
+
+// In the admin api's guard: verifies the token (role `staff`, an active `staff` row) and
+// stores the context under its own key, `request.supabaseStaff`.
+const { staff, client } = await attachSupabaseStaffRequestContext(request);
+const flags = await client.staffPermissions.flagsFor(staff.mms_id, 'read_clients'); // is_admin + the flag
+
+// In a controller:
+list(@SupabaseStaffClient() supabase: StaffClient, @Query() query: StaffGetClientsDto) {
+  return supabase.clients.list(query); // every organization's, each row with its organization
+}
+```
+
+`verifyAccessToken` refuses any token whose role is not `authenticated`, so a staff token never
+reaches a tenant route.
+
+Staff and their flags are written on the service client only - staff hold SELECT alone:
+
+```ts
+await service.staff.preRegister({ email, name, created_by: staffId }); // mms_id null until linked
+try {
+  await service.createStaffAuthUser({ email, password }); // role staff: the trigger links the row
+} catch (error) {
+  await service.staff.removePending(email);
+  throw error;
+}
+await service.staff.setActive(staffId, false, byStaffId); // stamps deactivated_at/by
+await service.setAuthUserBanned(staffId, true);           // and ends their sign-ins
+await service.staffPermissions.updateForStaff(staffId, patch, byStaffId); // UpdateStaffPermissionsDto
+```
+
+### User api credentials and emulation
+
+A credential is a client id and secret staff issue for one tenant user. Exchanging it mints that
+user's own token, which the custom access token hook marks `emulated: true` and gives a one-hour
+`exp`; `verifyAccessToken` returns it as `emulated: true` (`false` for a user's own session).
+
+The mint itself lives in the admin api. The SDK calls it is made of:
+
+- `service.userApiCredentials.findByClientId(clientId)` - the credential with its `secret_hash`,
+  or null.
+- `service.emulationHandshakes.open(userId, credentialId)` - a 30-second handshake; returns its id.
+- `service.mintMagicLink(email)`, then `auth.exchangeMagicLinkToken({ token_hash })` - the sign-in
+  the hook spends the handshake on.
+- `service.emulationHandshakes.close(id)` - in a `finally`, whatever happened above.
+- `auth.signOut(accessToken)` afterwards, so only the access token outlives the mint.
+- `service.userApiCredentials.markUsed(credentialId)` - stamps `last_used_at`, unaudited.
+
+`service.userApiCredentials.create` and `revoke` (null when already revoked) are audited against
+the credential's organization as the system and show in the user's history; `secret_hash` is a
+redacted column. Staff list a user's credentials on their own client
+(`supabase.userApiCredentials.listForUser`), through a column grant that never includes the hash.
+
 ## Billing and invoices
 
 Billing is split by who may write. On the caller's client, `supabase.billing` and

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

@@ -1,7 +1,7 @@
 import type { AdditionalDetailSummary, AdditionalDetailsEntity } from '@managemint-solutions/entities/additional-details';
 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 { ClientContext } from '../auth';
 import { type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 export * from './dto';
@@ -10,7 +10,7 @@ export declare class AdditionalDetailsResource {
     private readonly supabase;
     private readonly auth;
     private readonly table;
-    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
+    constructor(supabase: TypedSupabaseClient, auth: ClientContext, 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

@@ -19,6 +19,7 @@ const enum_1 = require("@managemint-solutions/entities/additional-details/enum")
 const enum_2 = require("@managemint-solutions/entities/audit-trail/enum");
 const audit_1 = require("../audit");
 const errors_1 = require("../errors");
+const tenancy_1 = require("../tenancy");
 const won_1 = require("../leads/won");
 const values_1 = require("./values");
 __exportStar(require("./dto"), exports);
@@ -47,10 +48,7 @@ class AdditionalDetailsResource {
         });
     }
     async getById(additionalDetailsId) {
-        const { data, error } = await this.supabase
-            .from('additional_details')
-            .select(ADDITIONAL_DETAILS_SELECT)
-            .eq('organization_id', this.auth.organization_id)
+        const { data, error } = await (0, tenancy_1.scopeToOrganization)(this.supabase.from('additional_details').select(ADDITIONAL_DETAILS_SELECT), this.auth)
             .eq('mms_id', additionalDetailsId)
             .single();
         if (error)
@@ -58,10 +56,7 @@ class AdditionalDetailsResource {
         return withCastValue(data);
     }
     async list(entity, entityId) {
-        const { data, error } = await this.supabase
-            .from('additional_details')
-            .select(ADDITIONAL_DETAILS_SUMMARY_SELECT)
-            .eq('organization_id', this.auth.organization_id)
+        const { data, error } = await (0, tenancy_1.scopeToOrganization)(this.supabase.from('additional_details').select(ADDITIONAL_DETAILS_SUMMARY_SELECT), this.auth)
             .eq('entity_type', entity)
             .eq('entity_id', entityId)
             .order('key', { ascending: false });
@@ -70,11 +65,12 @@ class AdditionalDetailsResource {
         return data.map(withCastValue);
     }
     async create(entity, entityId, input) {
+        const organizationId = (0, tenancy_1.requireOrganization)(this.auth);
         if (entity === enum_1.AdditionalDetailsEntityTypes.LEAD) {
-            await (0, won_1.refuseWonLead)(this.supabase, this.auth.organization_id, entityId);
+            await (0, won_1.refuseWonLead)(this.supabase, organizationId, entityId);
         }
         const row = await this.table.insert({
-            organization_id: this.auth.organization_id,
+            organization_id: organizationId,
             entity_type: entity,
             entity_id: entityId,
             key: input.key,

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

@@ -2,6 +2,7 @@ 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 { StaffContext } from '../auth';
 import type { GetAuditTrailDto } from './dto';
 export * from './dto';
 /**
@@ -12,6 +13,8 @@ export type AuditActor = {
     mms_id: string | null;
     organization_id: string;
 };
+/** Who a resource runs as: a write's actor, or staff, who read across organizations and write nothing. */
+export type ResourceActor = AuditActor | StaffContext;
 /** A flat database row - always `select('*')`, never an entity shape with embedded joins. */
 export type AuditRow = Record<string, unknown>;
 /**
@@ -45,8 +48,9 @@ export declare const AUDIT_EXCLUDED_COLUMNS: ReadonlySet<string>;
  * `read_logs`, so a value copied into `changes` is a value published to the whole organization -
  * and these are either provider credentials and identifiers (the `paystack_*` customer and
  * subscription codes, card metadata, tokens, an idempotency key that would let a replay be
- * forged) or content the base table deliberately withholds (`authenticated` has no grant on
- * `notifications.rendered_content`, so the rendered email must not arrive by the back door).
+ * forged, an api credential's secret hash) or content the base table deliberately withholds
+ * (`authenticated` has no grant on `notifications.rendered_content`, so the rendered email must
+ * not arrive by the back door).
  * The column still shows up in the trail - that it changed is the point - with both sides
  * replaced by `'[redacted]'`.
  */
@@ -66,22 +70,61 @@ 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;
     private readonly actor;
     private readonly onError?;
-    constructor(supabase: SupabaseJsClient, actor: AuditActor, onError?: AuditErrorHandler | undefined);
+    constructor(supabase: SupabaseJsClient, actor: ResourceActor, 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: ResourceActor, 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 +134,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);
@@ -117,9 +176,11 @@ export type AuditedTable = {
     /** Hard delete. Returns the row as it was, so the caller can still act on it. */
     remove(id: string): Promise<AuditRow>;
 };
+/** How a service-client resource reaches an audited table once it knows a row's organization. */
+export type OrganizationTableFactory = (organizationId: string) => AuditedTable;
 /**
  * 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;
+export declare const auditedTable: (supabase: SupabaseJsClient, actor: ResourceActor, audit: AuditResource, options: AuditedTableOptions) => AuditedTable;