@basaltkit/audit-viewer 1.2.0 → 1.3.0

package/dist/plugin.js

@@ -1,4 +1,4 @@
-import { createToken, ctx, definePlugin } from '@basaltkit/core';
+import { createToken, ctx, definePlugin, ensureMetadata } from '@basaltkit/core';
 import { AUDIT } from '@basaltkit/audit';
 import { route } from '@basaltkit/http';
 import { z } from 'zod';
@@ -9,7 +9,10 @@ export function auditViewerPlugin(options = {}) {
     return definePlugin({
         name: 'basalt:audit-viewer',
         register({ container }) {
-            container.singleton(AUDIT_VIEWER, () => new AuditViewer(container.get(AUDIT), options));
+            // 'tenancy:active' is tenancyPlugin's marker: how a generic package
+            // learns the app is multi-tenant without importing @basaltkit/tenancy.
+            const metadata = ensureMetadata(container);
+            container.singleton(AUDIT_VIEWER, () => new AuditViewer(container.get(AUDIT), options, () => metadata.get('tenancy:active').length > 0));
         },
     });
 }

package/dist/viewer.d.ts

@@ -64,10 +64,28 @@ export interface AuditViewerOptions {
  */
 export declare class AuditViewer {
     private readonly audit;
+    /**
+     * Whether the host app is multi-tenant, i.e. whether `@basaltkit/tenancy`
+     * is registered. `auditViewerPlugin` wires this to the container's
+     * `'tenancy:active'` metadata marker — a signal, not an import, so this
+     * generic package never depends on the opt-in SaaS layer.
+     *
+     * Defaults to `false`: a hand-built viewer behaves single-tenant.
+     */
+    private readonly tenancyActive;
     private readonly bucketMs;
     private readonly topN;
     private readonly maxScan;
-    constructor(audit: Audit, options?: AuditViewerOptions);
+    constructor(audit: Audit, options?: AuditViewerOptions, 
+    /**
+     * Whether the host app is multi-tenant, i.e. whether `@basaltkit/tenancy`
+     * is registered. `auditViewerPlugin` wires this to the container's
+     * `'tenancy:active'` metadata marker — a signal, not an import, so this
+     * generic package never depends on the opt-in SaaS layer.
+     *
+     * Defaults to `false`: a hand-built viewer behaves single-tenant.
+     */
+    tenancyActive?: () => boolean);
     page(query?: ViewerQuery): Promise<AuditPage>;
     get(id: string, tenantId?: string): Promise<AuditEntry | null>;
     stats(query?: ViewerQuery): Promise<AuditStats>;
@@ -75,5 +93,15 @@ export declare class AuditViewer {
     /** Reads at most `maxScan` rows and reports whether the trail had more. */
     private match;
     private top;
+    /**
+     * The tenant to scope a read to, or `undefined` when the app has no tenant
+     * dimension at all.
+     *
+     * In a multi-tenant app an unresolvable tenant is an error — an unscoped read
+     * would cross tenants. In a single-tenant app (no `tenancyPlugin`) there is
+     * nothing to scope to and nothing to cross, so the read proceeds unscoped;
+     * `Audit.trail()` applies the same rule one layer down and still forces the
+     * ambient tenant whenever one exists.
+     */
     private tenant;
 }

package/dist/viewer.js

@@ -14,11 +14,22 @@ const DEFAULT_MAX_SCAN = 10_000;
  */
 export class AuditViewer {
     audit;
+    tenancyActive;
     bucketMs;
     topN;
     maxScan;
-    constructor(audit, options = {}) {
+    constructor(audit, options = {}, 
+    /**
+     * Whether the host app is multi-tenant, i.e. whether `@basaltkit/tenancy`
+     * is registered. `auditViewerPlugin` wires this to the container's
+     * `'tenancy:active'` metadata marker — a signal, not an import, so this
+     * generic package never depends on the opt-in SaaS layer.
+     *
+     * Defaults to `false`: a hand-built viewer behaves single-tenant.
+     */
+    tenancyActive = () => false) {
         this.audit = audit;
+        this.tenancyActive = tenancyActive;
         this.bucketMs = options.bucketMs ?? DAY;
         this.topN = options.topN ?? 20;
         this.maxScan = options.maxScan ?? DEFAULT_MAX_SCAN;
@@ -61,7 +72,7 @@ export class AuditViewer {
     async match(query) {
         const tenantId = this.tenant(query.tenantId);
         const trail = await this.audit.trail({
-            tenantId,
+            ...(tenantId !== undefined ? { tenantId } : {}),
             limit: this.maxScan,
             ...(query.event !== undefined ? { event: query.event } : {}),
             ...(query.actorId !== undefined ? { actorId: query.actorId } : {}),
@@ -74,10 +85,22 @@ export class AuditViewer {
     top(counts) {
         return [...counts.entries()].sort((a, b) => b[1] - a[1]).slice(0, this.topN);
     }
+    /**
+     * The tenant to scope a read to, or `undefined` when the app has no tenant
+     * dimension at all.
+     *
+     * In a multi-tenant app an unresolvable tenant is an error — an unscoped read
+     * would cross tenants. In a single-tenant app (no `tenancyPlugin`) there is
+     * nothing to scope to and nothing to cross, so the read proceeds unscoped;
+     * `Audit.trail()` applies the same rule one layer down and still forces the
+     * ambient tenant whenever one exists.
+     */
     tenant(explicit) {
         const id = explicit ?? tryCtx()?.['tenant']?.id;
-        if (!id)
+        if (id)
+            return id;
+        if (this.tenancyActive())
             throw new AuditTenantRequiredError();
-        return id;
+        return undefined;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basaltkit/audit-viewer",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "engines": {
     "node": ">=22.5.0"
   },
@@ -18,7 +18,7 @@
     "dist"
   ],
   "dependencies": {
-    "@basaltkit/audit": "^1.3.0",
+    "@basaltkit/audit": "^1.4.0",
     "@basaltkit/core": "^1.3.1",
     "@basaltkit/http": "^1.14.0"
   },