@managemint-solutions/sdk 0.52.0 → 0.54.0

package/dist/nest/index.d.ts

@@ -1,9 +1,10 @@
 import { HttpException } from '@nestjs/common';
 import type { Request } from 'express';
 import type { AuditErrorHandler } from '../audit';
-import { type VerifiedAuth } from '../auth';
+import { type VerifiedAuth, type VerifiedStaff } from '../auth';
 import { type SupabaseClient } from '../client';
 import { SupabaseClientError } from '../errors';
+import { type SupabaseStaffClient as StaffClient } from '../staff-client';
 import { type SupabaseServiceClient } from '../service-client';
 /**
  * The HttpException Nest should send for an SDK error: same status, and the body is
@@ -42,6 +43,30 @@ export declare const attachSupabaseRequestContext: (request: Request) => Promise
 export declare const getSupabaseRequestContext: (request: Request) => SupabaseRequestContext;
 /** The caller's data client, from the context the auth guard attached. */
 export declare const SupabaseUserClient: (...dataOrPipes: unknown[]) => ParameterDecorator;
+/** What the admin api's staff guard leaves on the request for the decorator to pick up. */
+export type SupabaseStaffRequestContext = {
+    client: StaffClient;
+    staff: VerifiedStaff;
+};
+/**
+ * Where on the request the staff context is stored - `request[SUPABASE_STAFF_REQUEST_KEY]`. A key
+ * of its own, so a staff context is never found where a tenant one is expected.
+ */
+export declare const SUPABASE_STAFF_REQUEST_KEY = "supabaseStaff";
+/**
+ * `attachSupabaseRequestContext` for a staff session: verifies the token as a staff one and builds
+ * the staff member's `SupabaseStaffClient`.
+ *
+ * Idempotent: a second call hands back the context the first one attached.
+ */
+export declare const attachSupabaseStaffRequestContext: (request: Request) => Promise<SupabaseStaffRequestContext>;
+/**
+ * The context the staff guard attached. Throws when it is absent, which only happens when the
+ * route is missing the guard.
+ */
+export declare const getSupabaseStaffRequestContext: (request: Request) => SupabaseStaffRequestContext;
+/** The staff member's data client, from the context the staff guard attached. */
+export declare const SupabaseStaffClient: (...dataOrPipes: unknown[]) => ParameterDecorator;
 /**
  * A `SupabaseServiceClient` from the ambient env - the SDK-side replacement for the api's
  * `createSupabaseAdminClient()`.

package/dist/nest/index.js

@@ -1,11 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SupabasePublicClient = exports.createSupabaseServiceClientFromEnv = exports.SupabaseUserClient = exports.getSupabaseRequestContext = exports.attachSupabaseRequestContext = exports.SUPABASE_REQUEST_KEY = exports.configureSupabaseUserClient = exports.toHttpException = void 0;
+exports.SupabasePublicClient = exports.createSupabaseServiceClientFromEnv = exports.SupabaseStaffClient = exports.getSupabaseStaffRequestContext = exports.attachSupabaseStaffRequestContext = exports.SUPABASE_STAFF_REQUEST_KEY = exports.SupabaseUserClient = exports.getSupabaseRequestContext = exports.attachSupabaseRequestContext = exports.SUPABASE_REQUEST_KEY = exports.configureSupabaseUserClient = exports.toHttpException = void 0;
 const common_1 = require("@nestjs/common");
 const auth_1 = require("../auth");
 const auth_client_1 = require("../auth-client");
 const client_1 = require("../client");
 const errors_1 = require("../errors");
+// Aliased: the param decorator below takes the class's name.
+const staff_client_1 = require("../staff-client");
 const service_client_1 = require("../service-client");
 /**
  * The HttpException Nest should send for an SDK error: same status, and the body is
@@ -96,6 +98,61 @@ const getSupabaseRequestContext = (request) => {
 exports.getSupabaseRequestContext = getSupabaseRequestContext;
 /** The caller's data client, from the context the auth guard attached. */
 exports.SupabaseUserClient = (0, common_1.createParamDecorator)((_, ctx) => (0, exports.getSupabaseRequestContext)(ctx.switchToHttp().getRequest()).client);
+/**
+ * Where on the request the staff context is stored - `request[SUPABASE_STAFF_REQUEST_KEY]`. A key
+ * of its own, so a staff context is never found where a tenant one is expected.
+ */
+exports.SUPABASE_STAFF_REQUEST_KEY = 'supabaseStaff';
+/**
+ * `attachSupabaseRequestContext` for a staff session: verifies the token as a staff one and builds
+ * the staff member's `SupabaseStaffClient`.
+ *
+ * Idempotent: a second call hands back the context the first one attached.
+ */
+const attachSupabaseStaffRequestContext = async (request) => {
+    const existing = request[exports.SUPABASE_STAFF_REQUEST_KEY];
+    if (existing)
+        return existing;
+    const accessToken = getBearerToken(request);
+    const url = getEnvOrThrow('SUPABASE_URL');
+    const key = getEnvOrThrow('SUPABASE_PUBLISHABLE_KEY');
+    const client = (0, auth_1.createRawClient)(url, key, accessToken);
+    try {
+        const staff = await (0, auth_1.verifyStaffAccessToken)({ url, key, accessToken, client });
+        const context = {
+            staff,
+            client: (0, staff_client_1.createSupabaseStaffClient)({
+                url,
+                key,
+                accessToken,
+                client,
+                auth: { mms_id: staff.mms_id, organization_id: null },
+            }),
+        };
+        request[exports.SUPABASE_STAFF_REQUEST_KEY] = context;
+        return context;
+    }
+    catch (error) {
+        // Converted here for the same reason as the tenant attach: guards run outside the filters.
+        if (error instanceof errors_1.SupabaseClientError)
+            throw (0, exports.toHttpException)(error);
+        throw error;
+    }
+};
+exports.attachSupabaseStaffRequestContext = attachSupabaseStaffRequestContext;
+/**
+ * The context the staff guard attached. Throws when it is absent, which only happens when the
+ * route is missing the guard.
+ */
+const getSupabaseStaffRequestContext = (request) => {
+    const context = request[exports.SUPABASE_STAFF_REQUEST_KEY];
+    if (!context)
+        throw new common_1.UnauthorizedException('Request is not authenticated');
+    return context;
+};
+exports.getSupabaseStaffRequestContext = getSupabaseStaffRequestContext;
+/** The staff member's data client, from the context the staff guard attached. */
+exports.SupabaseStaffClient = (0, common_1.createParamDecorator)((_, ctx) => (0, exports.getSupabaseStaffRequestContext)(ctx.switchToHttp().getRequest()).client);
 /**
  * A `SupabaseServiceClient` from the ambient env - the SDK-side replacement for the api's
  * `createSupabaseAdminClient()`.

package/dist/notifications/index.d.ts

@@ -2,7 +2,7 @@ import type { NotificationContent, NotificationEntity, NotificationSummary, Noti
 import { NotificationChannel, NotificationStatus, type NotificationType } from '@managemint-solutions/entities/notifications/enum';
 import type { MmsList } from '@managemint-solutions/entities/common';
 import type { AuthContext } from '../auth';
-import { type AuditedTable, type AuditResource } from '../audit';
+import { type AuditResource, type OrganizationTableFactory } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 import type { GetNotificationsDto } from './dto';
 export * from './dto';
@@ -75,8 +75,6 @@ export declare class NotificationsResource {
     /** Soft delete - the outbox row stays, flagged `deleted`, so the send record survives. */
     remove(notificationId: string): Promise<void>;
 }
-/** How the outbox reaches an audited table once it knows which organization a row belongs to. */
-export type OrganizationTableFactory = (organizationId: string) => AuditedTable;
 /**
  * The outbox and the queue worker's side of the table, on the service client: RLS reserves
  * `notifications` INSERT and DELETE to the service role, and `authenticated` has no grant on

package/dist/organization-payment-methods/index.d.ts

@@ -1,4 +1,4 @@
-import { type AuditActor, type AuditResource } from '../audit';
+import type { AuditActor } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 /**
  * Everything Paystack knows an organization by, plus the two secrets the billing service acts
@@ -31,15 +31,14 @@ export type PaymentMethodLookupColumn = 'paystack_customer_code' | 'paystack_sub
  * policy. Only the service role can reach it.
  *
  * Service-role only, like the invites - this lives on the organization scope of the service
- * client and never on a caller's client. Writes are audited against the organization (the row
- * has no identity of its own), and the audit diff redacts every `paystack_*` column, so the trail
- * records that a value changed and never what it changed to.
+ * client and never on a caller's client. Writes are not audited: every column is provider
+ * machinery, and an organization's subscription history is the billing ledger, not its audit
+ * trail (`untracked` on the organizations table, docs/11-audit-trail.md).
  */
 export declare class OrganizationPaymentMethodsResource {
     private readonly supabase;
     private readonly actor;
-    private readonly audit;
-    constructor(supabase: TypedSupabaseClient, actor: AuditActor, audit: AuditResource);
+    constructor(supabase: TypedSupabaseClient, actor: AuditActor);
     /** The actor organization's payment method; every column null when nothing has been stored yet. */
     get(): Promise<OrganizationPaymentMethod>;
     /**

package/dist/organization-payment-methods/index.js

@@ -1,8 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrganizationPaymentMethodsResource = exports.PAYMENT_METHOD_COLUMNS = void 0;
-const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
-const audit_1 = require("../audit");
 const errors_1 = require("../errors");
 exports.PAYMENT_METHOD_COLUMNS = [
     'paystack_customer_code',
@@ -33,18 +31,16 @@ const EMPTY = {
  * policy. Only the service role can reach it.
  *
  * Service-role only, like the invites - this lives on the organization scope of the service
- * client and never on a caller's client. Writes are audited against the organization (the row
- * has no identity of its own), and the audit diff redacts every `paystack_*` column, so the trail
- * records that a value changed and never what it changed to.
+ * client and never on a caller's client. Writes are not audited: every column is provider
+ * machinery, and an organization's subscription history is the billing ledger, not its audit
+ * trail (`untracked` on the organizations table, docs/11-audit-trail.md).
  */
 class OrganizationPaymentMethodsResource {
     supabase;
     actor;
-    audit;
-    constructor(supabase, actor, audit) {
+    constructor(supabase, actor) {
         this.supabase = supabase;
         this.actor = actor;
-        this.audit = audit;
     }
     /** The actor organization's payment method; every column null when nothing has been stored yet. */
     async get() {
@@ -73,15 +69,6 @@ class OrganizationPaymentMethodsResource {
         }, { onConflict: 'organization_id' });
         if (error)
             throw (0, errors_1.mapPostgrestError)(error);
-        const changes = (0, audit_1.diffChanges)(before, after);
-        if (Object.keys(changes).length === 0)
-            return;
-        await this.audit.record({
-            action: enum_1.AuditTrailAction.UPDATE,
-            entityType: enum_1.AuditTrailEntityType.ORGANIZATION,
-            entityId: this.actor.organization_id,
-            changes,
-        });
     }
 }
 exports.OrganizationPaymentMethodsResource = OrganizationPaymentMethodsResource;

package/dist/organizations/dto.d.ts

@@ -1,4 +1,4 @@
-import type { CreateOrganizationDto as CreateOrganizationDtoType, UpdateOrganizationDto as UpdateOrganizationDtoType } from '@managemint-solutions/entities/organization/dto';
+import type { CreateOrganizationDto as CreateOrganizationDtoType, GetOrganizationsDto as GetOrganizationsDtoType, OrganizationIdDto as OrganizationIdDtoType, UpdateOrganizationDto as UpdateOrganizationDtoType } from '@managemint-solutions/entities/organization/dto';
 import { OrganizationTypes } from '@managemint-solutions/entities/organization/enum';
 export declare class CreateOrganizationDto implements CreateOrganizationDtoType {
     readonly org_type: OrganizationTypes;
@@ -61,3 +61,11 @@ export declare class UpdateOrganizationDto implements UpdateOrganizationDtoType
     readonly currency?: string;
     readonly leave_calendar_start_month?: number;
 }
+export declare class OrganizationIdDto implements OrganizationIdDtoType {
+    readonly organizationId: string;
+}
+export declare class GetOrganizationsDto implements GetOrganizationsDtoType {
+    readonly search?: string | null;
+    readonly page: number;
+    readonly page_size: number;
+}

package/dist/organizations/dto.js

@@ -9,7 +9,7 @@ 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.UpdateOrganizationDto = exports.CreateOrganizationDto = void 0;
+exports.GetOrganizationsDto = exports.OrganizationIdDto = exports.UpdateOrganizationDto = exports.CreateOrganizationDto = void 0;
 const enum_1 = require("@managemint-solutions/entities/organization/enum");
 const class_validator_1 = require("class-validator");
 const validators_1 = require("../validators");
@@ -450,3 +450,42 @@ __decorate([
     (0, class_validator_1.Max)(12, { message: 'Leave year start month must be between 1 and 12' }),
     __metadata("design:type", Number)
 ], UpdateOrganizationDto.prototype, "leave_calendar_start_month", void 0);
+// No tenant route takes one - a tenant only ever reaches their own organization - so this is the
+// admin api's `/organizations/:organizationId`.
+class OrganizationIdDto {
+    organizationId;
+}
+exports.OrganizationIdDto = OrganizationIdDto;
+__decorate([
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid organization ID format' }),
+    __metadata("design:type", String)
+], OrganizationIdDto.prototype, "organizationId", void 0);
+class GetOrganizationsDto {
+    search;
+    page = 1;
+    page_size = 10;
+}
+exports.GetOrganizationsDto = GetOrganizationsDto;
+__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)
+], GetOrganizationsDto.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)
+], GetOrganizationsDto.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)
+], GetOrganizationsDto.prototype, "page_size", void 0);

package/dist/organizations/index.d.ts

@@ -1,6 +1,9 @@
 import type { SeatReservation } from '@managemint-solutions/entities/billing';
-import { type AuditActor, type AuditResource, type AuditRow } from '../audit';
+import type { MmsList } from '@managemint-solutions/entities/common';
+import type { OrganizationSummary } from '@managemint-solutions/entities/organization';
+import { type AuditResource, type AuditRow, EntityAuditTrail, type ResourceActor } from '../audit';
 import type { TypedSupabaseClient } from '../client';
+import type { GetOrganizationsDto } from './dto';
 export * from './dto';
 /** The organizations row as `ORGANIZATION_SELECT` produces it, before the api shapes it. */
 export type OrganizationRow = Record<string, unknown> & {
@@ -18,10 +21,17 @@ export declare class OrganizationsResource {
     private readonly supabase;
     private readonly auth;
     private readonly table;
-    constructor(supabase: TypedSupabaseClient, auth: AuditActor, audit: AuditResource);
+    /** This record's history - its own rows and the rows that hang off it. */
+    readonly audit: EntityAuditTrail;
+    constructor(supabase: TypedSupabaseClient, auth: ResourceActor, audit: AuditResource);
     getById(organizationId: string): Promise<OrganizationRow>;
-    /** The caller's own organization, from the auth context. */
+    /** The caller's own organization, from the auth context. Staff have none: a 403. */
     get(): Promise<OrganizationRow>;
+    /**
+     * Every organization the caller can read, newest first - all of them for staff, the caller's
+     * own for a tenant, as RLS decides. `search` matches the name, trading name and email.
+     */
+    list(query: GetOrganizationsDto): Promise<MmsList<OrganizationSummary>>;
     /**
      * The whole row, unprojected. Billing reads a different handful of columns for each of its
      * flows - provisioning, a module purchase, a seat charge - and they are all single-row

package/dist/organizations/index.js

@@ -18,14 +18,37 @@ exports.OrganizationSignupResource = exports.OrganizationsResource = void 0;
 const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
 const audit_1 = require("../audit");
 const errors_1 = require("../errors");
+const tenancy_1 = require("../tenancy");
 const transforms_1 = require("../transforms");
 __exportStar(require("./dto"), exports);
+// The subscription machinery on the row - what the billing flows and the Paystack webhooks
+// move. Its history is the billing ledger (billing_transactions, invoices, billing_events);
+// the organization's audit trail is its profile, so these are never recorded there.
+const SUBSCRIPTION_COLUMNS = [
+    'billing_status',
+    'billing_status_updated_at',
+    'billing_cycle_locked',
+    'payment_frequency',
+    'payment_override',
+    'last_payment_date',
+    'next_payment_date',
+    'access_expires_at',
+    'active_seat_count',
+    'paid_seat_count',
+    'modules',
+    'pricebook_id',
+    'card_brand',
+    'card_description',
+    'card_expiry_date',
+    'card_expiring_soon',
+];
 // The organizations row *is* the organization: it has no organization_id column, hence
 // `scopeByOrganization: false` wherever it is audited.
 const ORGANIZATIONS_TABLE = {
     table: 'organizations',
     entityType: enum_1.AuditTrailEntityType.ORGANIZATION,
     scopeByOrganization: false,
+    untracked: SUBSCRIPTION_COLUMNS,
 };
 // The api maps this row into OrganizationEntity: the module keys stored here are priced
 // against the organization's pricebook, and the flat address columns are nested. That is
@@ -72,6 +95,8 @@ const ORGANIZATION_SELECT = `
         card_expiring_soon,
         pricebook_id
       `;
+// The public contract is the shared OrganizationSummary; `modules` stays the stored module keys.
+const ORGANIZATION_LIST_SELECT = 'mms_id, created_at, name, trading_name, email, billing_status, active_seat_count, paid_seat_count, modules';
 /**
  * The caller's own organization. Every method takes the id explicitly rather than reading it
  * off the auth context, because the signup and webhook paths operate on an organization that
@@ -81,10 +106,13 @@ class OrganizationsResource {
     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;
         this.table = (0, audit_1.auditedTable)(supabase, auth, audit, ORGANIZATIONS_TABLE);
+        this.audit = new audit_1.EntityAuditTrail(supabase, auth, enum_1.AuditTrailEntityType.ORGANIZATION);
     }
     async getById(organizationId) {
         const { data, error } = await this.supabase
@@ -96,9 +124,34 @@ class OrganizationsResource {
             throw (0, errors_1.mapPostgrestError)(error);
         return data;
     }
-    /** The caller's own organization, from the auth context. */
+    /** The caller's own organization, from the auth context. Staff have none: a 403. */
     async get() {
-        return this.getById(this.auth.organization_id);
+        return this.getById((0, tenancy_1.requireOrganization)(this.auth));
+    }
+    /**
+     * Every organization the caller can read, newest first - all of them for staff, the caller's
+     * own for a tenant, as RLS decides. `search` matches the name, trading name and email.
+     */
+    async list(query) {
+        const page = query.page;
+        const pageSize = query.page_size;
+        const offset = (page - 1) * pageSize;
+        const trimmedSearch = query.search?.trim();
+        // `order`/`range` return `this`, so the search can be reassigned onto the builder without a
+        // cast. Exact, not estimated, like invoices: there are tens of organizations, not tens of
+        // thousands, and the pager must not offer a page that is not there.
+        let organizationsQuery = this.supabase
+            .from('organizations')
+            .select(ORGANIZATION_LIST_SELECT, { count: 'exact' })
+            .order('created_at', { ascending: false })
+            .range(offset, offset + pageSize - 1);
+        if (trimmedSearch) {
+            organizationsQuery = organizationsQuery.or((0, transforms_1.orIlike)(['name', 'trading_name', 'email'], trimmedSearch));
+        }
+        const { data, error, count } = await organizationsQuery;
+        if (error)
+            throw (0, errors_1.mapPostgrestError)(error);
+        return (0, transforms_1.toMmsList)(data, page, pageSize, count);
     }
     /**
      * The whole row, unprojected. Billing reads a different handful of columns for each of its
@@ -203,11 +256,14 @@ class OrganizationSignupResource {
         if (error)
             throw (0, errors_1.mapPostgrestError)(error);
         const row = data;
+        const changes = (0, audit_1.snapshotChanges)(row, 'new');
+        for (const column of SUBSCRIPTION_COLUMNS)
+            delete changes[column];
         await this.auditFor(row.mms_id).record({
             action: enum_1.AuditTrailAction.INSERT,
             entityType: enum_1.AuditTrailEntityType.ORGANIZATION,
             entityId: row.mms_id,
-            changes: (0, audit_1.snapshotChanges)(row, 'new'),
+            changes,
         });
         return (0, audit_1.withoutInternalId)(row);
     }

package/dist/permissions/index.d.ts

@@ -7,6 +7,12 @@ export type PermissionFlags = {
     is_owner: boolean;
     is_admin: boolean;
 } & Record<string, boolean>;
+/**
+ * A guard's flag is interpolated into a select string, so it is checked against the shape a
+ * column name can take first - a flag never comes from a request, only from a route's own
+ * decorator, so anything else is a bug rather than a bad request.
+ */
+export declare const checkPermissionFlag: (flag: string) => void;
 /**
  * The `permissions` table. Rows are created by the `on_auth_user_created` trigger and deleted
  * with the user - INSERT and DELETE are `false` for `authenticated` - so this resource only
@@ -26,10 +32,6 @@ export declare class PermissionsResource {
      * The one lookup `PermissionsGuard` makes per gated request: the flag the route asked for,
      * plus the two that bypass it. Returns null when the caller has no permissions row, which the
      * guard treats as a denial.
-     *
-     * `flag` is interpolated into the select string, so it is checked against the shape a column
-     * name can take first - a flag never comes from a request, only from a route's own decorator,
-     * so anything else is a bug rather than a bad request.
      */
     flagsFor(userId: string, flag: string): Promise<PermissionFlags | null>;
     /** Whether a user owns the organization - the guard behind "you cannot deactivate the owner". */

package/dist/permissions/index.js

@@ -14,7 +14,7 @@ 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.PermissionsResource = void 0;
+exports.PermissionsResource = exports.checkPermissionFlag = void 0;
 const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
 const audit_1 = require("../audit");
 const errors_1 = require("../errors");
@@ -22,7 +22,24 @@ __exportStar(require("./dto"), exports);
 const PERMISSIONS_TABLE = {
     table: 'permissions',
     entityType: enum_1.AuditTrailEntityType.PERMISSION,
+    // A permissions change shows in the history of the user it belongs to.
+    related: { entityType: enum_1.AuditTrailEntityType.USER, column: 'user_id' },
 };
+/**
+ * A guard's flag is interpolated into a select string, so it is checked against the shape a
+ * column name can take first - a flag never comes from a request, only from a route's own
+ * decorator, so anything else is a bug rather than a bad request.
+ */
+const checkPermissionFlag = (flag) => {
+    if (!/^[a-z][a-z0-9_]*$/.test(flag)) {
+        throw new errors_1.SupabaseClientError({
+            status: 500,
+            error: 'Internal Error',
+            message: 'Invalid permission flag',
+        });
+    }
+};
+exports.checkPermissionFlag = checkPermissionFlag;
 /**
  * The `permissions` table. Rows are created by the `on_auth_user_created` trigger and deleted
  * with the user - INSERT and DELETE are `false` for `authenticated` - so this resource only
@@ -56,19 +73,9 @@ class PermissionsResource {
      * The one lookup `PermissionsGuard` makes per gated request: the flag the route asked for,
      * plus the two that bypass it. Returns null when the caller has no permissions row, which the
      * guard treats as a denial.
-     *
-     * `flag` is interpolated into the select string, so it is checked against the shape a column
-     * name can take first - a flag never comes from a request, only from a route's own decorator,
-     * so anything else is a bug rather than a bad request.
      */
     async flagsFor(userId, flag) {
-        if (!/^[a-z][a-z0-9_]*$/.test(flag)) {
-            throw new errors_1.SupabaseClientError({
-                status: 500,
-                error: 'Internal Error',
-                message: 'Invalid permission flag',
-            });
-        }
+        (0, exports.checkPermissionFlag)(flag);
         const { data, error } = await this.supabase
             .from('permissions')
             .select(`is_owner, is_admin, ${flag}`)

package/dist/projects/dto.d.ts

@@ -1,4 +1,4 @@
-import type { CreateProjectDto as CreateProjectDtoType, GetProjectsDto as GetProjectsDtoType, ProjectIdDto as ProjectIdDtoType, UpdateProjectDto as UpdateProjectDtoType } from '@managemint-solutions/entities/projects/dto';
+import type { CreateProjectDto as CreateProjectDtoType, GetProjectsDto as GetProjectsDtoType, StaffGetProjectsDto as StaffGetProjectsDtoType, ProjectIdDto as ProjectIdDtoType, UpdateProjectDto as UpdateProjectDtoType } from '@managemint-solutions/entities/projects/dto';
 export declare class GetProjectsDto implements Omit<GetProjectsDtoType, 'status_id_in' | 'status_id_not_in'> {
     readonly search?: string | null;
     readonly page: number;
@@ -15,6 +15,10 @@ export declare class GetProjectsDto implements Omit<GetProjectsDtoType, 'status_
     readonly client_id?: string | null;
     readonly archive: boolean;
 }
+/** A staff read across organizations, optionally narrowed to one of them. */
+export declare class StaffGetProjectsDto extends GetProjectsDto implements Omit<StaffGetProjectsDtoType, 'status_id_in' | 'status_id_not_in'> {
+    readonly organization_id?: string | null;
+}
 export declare class ProjectIdDto implements ProjectIdDtoType {
     readonly projectId: string;
 }

package/dist/projects/dto.js

@@ -9,7 +9,7 @@ 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.UpdateProjectDto = exports.CreateProjectDto = exports.ProjectIdDto = exports.GetProjectsDto = void 0;
+exports.UpdateProjectDto = exports.CreateProjectDto = exports.ProjectIdDto = exports.StaffGetProjectsDto = exports.GetProjectsDto = void 0;
 const class_validator_1 = require("class-validator");
 const class_transformer_1 = require("class-transformer");
 const transforms_1 = require("../transforms");
@@ -132,6 +132,17 @@ __decorate([
     (0, class_validator_1.IsBoolean)({ message: 'Include archived must be a boolean' }),
     __metadata("design:type", Boolean)
 ], GetProjectsDto.prototype, "archive", void 0);
+/** A staff read across organizations, optionally narrowed to one of them. */
+class StaffGetProjectsDto extends GetProjectsDto {
+    organization_id;
+}
+exports.StaffGetProjectsDto = StaffGetProjectsDto;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, validators_1.IsNullable)(),
+    (0, class_validator_1.IsUUID)('7', { message: 'Invalid organization ID format' }),
+    __metadata("design:type", Object)
+], StaffGetProjectsDto.prototype, "organization_id", void 0);
 class ProjectIdDto {
     projectId;
 }

package/dist/projects/index.d.ts

@@ -1,7 +1,7 @@
 import type { MmsList } from '@managemint-solutions/entities/common';
 import type { ProjectEntity, ProjectSummary } from '@managemint-solutions/entities/projects';
-import type { AuthContext } from '../auth';
-import { type AuditResource } from '../audit';
+import type { ClientContext } from '../auth';
+import { EntityAuditTrail, type AuditResource } from '../audit';
 import type { TypedSupabaseClient } from '../client';
 import type { CreateProjectDto, GetProjectsDto, UpdateProjectDto } from './dto';
 export * from './dto';
@@ -9,8 +9,12 @@ export declare class ProjectsResource {
     private readonly supabase;
     private readonly auth;
     private readonly table;
-    constructor(supabase: TypedSupabaseClient, auth: AuthContext, audit: AuditResource);
-    list(query: GetProjectsDto): Promise<MmsList<ProjectSummary>>;
+    /** This record's history - its own rows and the rows that hang off it. */
+    readonly audit: EntityAuditTrail;
+    constructor(supabase: TypedSupabaseClient, auth: ClientContext, audit: AuditResource);
+    list(query: GetProjectsDto & {
+        organization_id?: string | null;
+    }): Promise<MmsList<ProjectSummary>>;
     getById(projectId: string): Promise<ProjectEntity>;
     create(input: CreateProjectDto): Promise<ProjectEntity>;
     update(projectId: string, input: UpdateProjectDto): Promise<ProjectEntity>;

package/dist/projects/index.js

@@ -18,6 +18,7 @@ exports.ProjectsResource = void 0;
 const enum_1 = require("@managemint-solutions/entities/audit-trail/enum");
 const audit_1 = require("../audit");
 const errors_1 = require("../errors");
+const tenancy_1 = require("../tenancy");
 const transforms_1 = require("../transforms");
 __exportStar(require("./dto"), exports);
 // The public contract is the shared ProjectSummary / ProjectEntity from
@@ -79,6 +80,8 @@ class ProjectsResource {
     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;
@@ -86,6 +89,7 @@ class ProjectsResource {
             table: 'projects',
             entityType: enum_1.AuditTrailEntityType.PROJECTS,
         });
+        this.audit = new audit_1.EntityAuditTrail(supabase, auth, enum_1.AuditTrailEntityType.PROJECTS);
     }
     async list(query) {
         const page = query.page;
@@ -94,14 +98,16 @@ class ProjectsResource {
         const trimmedSearch = query.search?.trim();
         // `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 projectsQuery = this.supabase
+        let projectsQuery = (0, tenancy_1.scopeToOrganization)(this.supabase
             .from('projects')
-            .select(PROJECT_LIST_SELECT, { count: 'estimated' })
-            .eq('organization_id', this.auth.organization_id)
+            .select((0, tenancy_1.withOrganization)(PROJECT_LIST_SELECT, this.auth), { count: 'estimated' }), this.auth)
             .eq('archived', query.archive)
             .eq('deleted', false)
             .range(offset, offset + pageSize - 1)
             .order('created_at', { ascending: false });
+        if (query.organization_id) {
+            projectsQuery = projectsQuery.eq('organization_id', query.organization_id);
+        }
         if (trimmedSearch) {
             projectsQuery = projectsQuery.or((0, transforms_1.orIlike)(['name', 'specification'], trimmedSearch));
         }
@@ -144,10 +150,7 @@ class ProjectsResource {
         return (0, transforms_1.toMmsList)(data, page, pageSize, count);
     }
     async getById(projectId) {
-        const { data, error } = await this.supabase
-            .from('projects')
-            .select(PROJECT_DETAIL_SELECT)
-            .eq('organization_id', this.auth.organization_id)
+        const { data, error } = await (0, tenancy_1.scopeToOrganization)(this.supabase.from('projects').select(PROJECT_DETAIL_SELECT), this.auth)
             .eq('mms_id', projectId)
             .single();
         if (error)
@@ -179,7 +182,7 @@ class ProjectsResource {
             ...input,
             start_date: (0, transforms_1.toDateInput)(input.start_date),
             end_date: (0, transforms_1.toDateInput)(input.end_date),
-            organization_id: this.auth.organization_id,
+            organization_id: (0, tenancy_1.requireOrganization)(this.auth),
             created_by: this.auth.mms_id,
             created_at: new Date().toISOString(),
         });