@byline/db-postgres 3.9.0 → 3.10.1

package/dist/database/schema/index.d.ts

@@ -3312,4 +3312,187 @@ export declare const jsonStoreRelations: import("drizzle-orm").Relations<"byline
     document: import("drizzle-orm").One<"byline_document_versions", true>;
     collection: import("drizzle-orm").One<"byline_collections", true>;
 }>;
+export declare const auditLog: import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "byline_audit_log";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        document_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "document_id";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        collection_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "collection_id";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        actor_id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "actor_id";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        actor_realm: import("drizzle-orm/pg-core").PgColumn<{
+            name: "actor_realm";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 16;
+        }>;
+        action: import("drizzle-orm/pg-core").PgColumn<{
+            name: "action";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 64;
+        }>;
+        field: import("drizzle-orm/pg-core").PgColumn<{
+            name: "field";
+            tableName: "byline_audit_log";
+            dataType: "string";
+            columnType: "PgVarchar";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: 128;
+        }>;
+        before: import("drizzle-orm/pg-core").PgColumn<{
+            name: "before";
+            tableName: "byline_audit_log";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        after: import("drizzle-orm/pg-core").PgColumn<{
+            name: "after";
+            tableName: "byline_audit_log";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        occurred_at: import("drizzle-orm/pg-core").PgColumn<{
+            name: "occurred_at";
+            tableName: "byline_audit_log";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "pg";
+}>;
 export { adminPermissions, adminPermissionsRelations, adminRefreshTokens, adminRefreshTokensRelations, adminRoleAdminUser, adminRoleAdminUserRelations, adminRoles, adminRolesRelations, adminUsers, adminUsersRelations, } from './auth.js';

package/dist/database/schema/index.js

@@ -632,6 +632,39 @@ export const jsonStoreRelations = relations(jsonStore, ({ one }) => ({
     }),
 }));
 // ---------------------------------------------------------------------------
+// Audit log — byline_audit_log
+// ---------------------------------------------------------------------------
+// Document-grain audit log. Records the changes the immutable version stream
+// does NOT capture an actor for: non-versioned system-field writes (path,
+// availableLocales), in-place status transitions, and deletions — plus, later,
+// admin-module events. One generic table (nullable `document_id`, namespaced
+// `action`) so the system-wide activity report and future admin-realm auditing
+// fit without a second migration. Append-only and deliberately **FK-free**: an
+// audit row is an immutable historical fact that must outlive the document,
+// collection, or actor it references — a `document.deleted` row cannot be
+// allowed to cascade-delete itself. See docs/AUDIT.md — Workstream 2.
+export const auditLog = pgTable('byline_audit_log', {
+    id: uuid('id').primaryKey(), // UUIDv7 — time-ordered, so id ordering ≈ time ordering
+    document_id: uuid('document_id'), // NULL for admin-realm (non-document) events; no FK
+    collection_id: uuid('collection_id'), // no FK — outlives the collection
+    actor_id: uuid('actor_id'), // NULL = system / internal tooling / non-UUID synthetic actor
+    actor_realm: varchar('actor_realm', { length: 16 }).notNull(), // 'admin' | 'user' | 'system'
+    action: varchar('action', { length: 64 }).notNull(), // namespaced, e.g. 'document.path.changed'
+    field: varchar('field', { length: 128 }), // the changed field where meaningful (e.g. 'path'), else NULL
+    before: jsonb('before'),
+    after: jsonb('after'),
+    occurred_at: timestamp('occurred_at', { precision: 6, withTimezone: true })
+        .notNull()
+        .defaultNow(),
+}, (table) => [
+    // Per-document history, time-ordered (id is UUIDv7).
+    index('idx_audit_log_document_id').on(table.document_id, table.id),
+    // Per-actor activity — the system-wide report's actor filter.
+    index('idx_audit_log_actor_id').on(table.actor_id, table.id),
+    // Action-type filter for the activity report.
+    index('idx_audit_log_action').on(table.action, table.id),
+]);
+// ---------------------------------------------------------------------------
 // Auth schema — byline_admin_users, byline_admin_roles, etc.
 // See ./auth.ts for definitions and rationale.
 // ---------------------------------------------------------------------------

package/dist/index.js

@@ -9,6 +9,8 @@ import { drizzle } from 'drizzle-orm/node-postgres';
 import pg from 'pg';
 import * as schema from './database/schema/index.js';
 import { DBManagerImpl, TXManagerImpl } from './lib/db-manager.js';
+import { createAuditCommands } from './modules/audit/audit-commands.js';
+import { createAuditQueries } from './modules/audit/audit-queries.js';
 import { createCounterCommands } from './modules/counters/counters-commands.js';
 import { createCommandBuilders, } from './modules/storage/storage-commands.js';
 import { createQueryBuilders } from './modules/storage/storage-queries.js';
@@ -30,12 +32,20 @@ export const pgAdapter = ({ connectionString, collections, defaultContentLocale,
     const commandBuilders = createCommandBuilders(dbManager, defaultContentLocale);
     const queryBuilders = createQueryBuilders(db, collections, defaultContentLocale);
     const counterCommands = createCounterCommands(db);
+    // Audit writes run on the DBManager so they join an ambient `withTransaction`
+    // (atomic with the mutation they record); audit reads run on the pool.
+    const auditCommands = createAuditCommands(dbManager);
+    const auditQueries = createAuditQueries(db);
     return {
         commands: {
             ...commandBuilders,
             counters: counterCommands,
+            audit: auditCommands,
+        },
+        queries: {
+            ...queryBuilders,
+            audit: auditQueries,
         },
-        queries: queryBuilders,
         withTransaction: (fn) => txManager.withTransaction(fn),
         drizzle: db,
         pool,

package/dist/modules/audit/audit-commands.d.ts

@@ -0,0 +1,27 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Append-only audit-log writes (docs/AUDIT.md — Workstream 2). A deliberately
+ * dumb command: it inserts one row and knows nothing about *which* changes
+ * warrant an audit entry — that policy lives in the lifecycle services, which
+ * wrap the mutation + this append in `withTransaction` so they commit
+ * atomically. Runs on the `DBManager` executor, so an `append` issued inside a
+ * `withTransaction` boundary joins the ambient transaction.
+ */
+import type { AuditLogAppendInput, IAuditCommands } from '@byline/core';
+import type { DBManager } from '../../lib/db-manager.js';
+export declare class AuditCommands implements IAuditCommands {
+    private dbManager;
+    constructor(dbManager: DBManager);
+    /** Ambient transaction when a `withTransaction` boundary is open, else the pool. */
+    private get db();
+    append(input: AuditLogAppendInput): Promise<{
+        id: string;
+    }>;
+}
+export declare function createAuditCommands(dbManager: DBManager): AuditCommands;

package/dist/modules/audit/audit-commands.js

@@ -0,0 +1,40 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { v7 as uuidv7 } from 'uuid';
+import { auditLog } from '../../database/schema/index.js';
+export class AuditCommands {
+    dbManager;
+    constructor(dbManager) {
+        this.dbManager = dbManager;
+    }
+    /** Ambient transaction when a `withTransaction` boundary is open, else the pool. */
+    get db() {
+        return this.dbManager.get();
+    }
+    async append(input) {
+        const id = uuidv7(); // time-ordered, so id ordering ≈ occurred_at ordering
+        await this.db.insert(auditLog).values({
+            id,
+            document_id: input.documentId ?? null,
+            collection_id: input.collectionId ?? null,
+            actor_id: input.actorId ?? null,
+            actor_realm: input.actorRealm,
+            action: input.action,
+            field: input.field ?? null,
+            // `?? null` only coerces undefined → SQL NULL; a real `false`/`0`/`''`
+            // before/after value is preserved.
+            before: input.before ?? null,
+            after: input.after ?? null,
+            // occurred_at defaults to now() at the DB.
+        });
+        return { id };
+    }
+}
+export function createAuditCommands(dbManager) {
+    return new AuditCommands(dbManager);
+}

package/dist/modules/audit/audit-queries.d.ts

@@ -0,0 +1,29 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Audit-log reads (docs/AUDIT.md — Workstreams 3 & 4). Reads run on the pool
+ * directly — they never need to join an audit write's transaction — so this
+ * takes the raw connection rather than the `DBManager`. Access scoping is the
+ * caller's responsibility (the document's own read gate); these queries do no
+ * scoping of their own.
+ */
+import type { AuditLogPage, IAuditQueries } from '@byline/core';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type * as schema from '../../database/schema/index.js';
+type DatabaseConnection = NodePgDatabase<typeof schema>;
+export declare class AuditQueries implements IAuditQueries {
+    private db;
+    constructor(db: DatabaseConnection);
+    getDocumentAuditLog(params: {
+        document_id: string;
+        page?: number;
+        page_size?: number;
+    }): Promise<AuditLogPage>;
+}
+export declare function createAuditQueries(db: DatabaseConnection): AuditQueries;
+export {};

package/dist/modules/audit/audit-queries.js

@@ -0,0 +1,55 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { desc, eq, sql } from 'drizzle-orm';
+import { auditLog } from '../../database/schema/index.js';
+function toEntry(row) {
+    return {
+        id: row.id,
+        documentId: row.document_id,
+        collectionId: row.collection_id,
+        actorId: row.actor_id,
+        actorRealm: row.actor_realm,
+        action: row.action,
+        field: row.field,
+        before: row.before,
+        after: row.after,
+        occurredAt: row.occurred_at,
+    };
+}
+export class AuditQueries {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async getDocumentAuditLog(params) {
+        const page = params.page ?? 1;
+        const pageSize = params.page_size ?? 20;
+        const offset = (page - 1) * pageSize;
+        const totalResult = await this.db
+            .select({ count: sql `count(*)` })
+            .from(auditLog)
+            .where(eq(auditLog.document_id, params.document_id));
+        const total = Number(totalResult[0]?.count) || 0;
+        const totalPages = Math.ceil(total / pageSize);
+        const rows = await this.db
+            .select()
+            .from(auditLog)
+            .where(eq(auditLog.document_id, params.document_id))
+            // id is UUIDv7 — DESC is newest-first without a separate sort column.
+            .orderBy(desc(auditLog.id))
+            .limit(pageSize)
+            .offset(offset);
+        return {
+            entries: rows.map(toEntry),
+            meta: { total, page, pageSize, totalPages },
+        };
+    }
+}
+export function createAuditQueries(db) {
+    return new AuditQueries(db);
+}

package/dist/modules/audit/tests/audit-log.test.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/modules/audit/tests/audit-log.test.js

@@ -0,0 +1,117 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Integration tests for the audit-log storage layer (docs/AUDIT.md — W2):
+ * `audit.append` (write) + `audit.getDocumentAuditLog` (read), and the
+ * load-bearing property that an `append` issued inside `withTransaction`
+ * commits or rolls back **with** the transaction it is part of.
+ */
+import { v7 as uuidv7 } from 'uuid';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { setupTestDB, teardownTestDB } from '../../../lib/test-helper.js';
+import { createAuditCommands } from '../audit-commands.js';
+import { createAuditQueries } from '../audit-queries.js';
+let auditCommands;
+let auditQueries;
+let txManager;
+describe('audit-log storage', () => {
+    beforeAll(() => {
+        const testDB = setupTestDB([]);
+        txManager = testDB.txManager;
+        auditCommands = createAuditCommands(testDB.dbManager);
+        auditQueries = createAuditQueries(testDB.db);
+    });
+    afterAll(async () => {
+        await teardownTestDB();
+    });
+    it('appends an entry and reads it back with full field fidelity', async () => {
+        const documentId = uuidv7();
+        const collectionId = uuidv7();
+        const actorId = uuidv7();
+        await auditCommands.append({
+            documentId,
+            collectionId,
+            actorId,
+            actorRealm: 'admin',
+            action: 'document.path.changed',
+            field: 'path',
+            before: 'old-slug',
+            after: 'new-slug',
+        });
+        const page = await auditQueries.getDocumentAuditLog({ document_id: documentId });
+        expect(page.meta.total).toBe(1);
+        const entry = page.entries[0];
+        expect(entry.documentId).toBe(documentId);
+        expect(entry.collectionId).toBe(collectionId);
+        expect(entry.actorId).toBe(actorId);
+        expect(entry.actorRealm).toBe('admin');
+        expect(entry.action).toBe('document.path.changed');
+        expect(entry.field).toBe('path');
+        expect(entry.before).toBe('old-slug');
+        expect(entry.after).toBe('new-slug');
+        expect(entry.occurredAt).toBeInstanceOf(Date);
+    });
+    it('persists NULL actor + structured before/after, and returns newest-first', async () => {
+        const documentId = uuidv7();
+        // A system write (no actor) with object-shaped before/after.
+        await auditCommands.append({
+            documentId,
+            actorId: null,
+            actorRealm: 'system',
+            action: 'document.locales.changed',
+            field: 'availableLocales',
+            before: ['en'],
+            after: ['en', 'fr'],
+        });
+        await auditCommands.append({
+            documentId,
+            actorRealm: 'admin',
+            action: 'document.status.changed',
+            field: 'status',
+            before: 'draft',
+            after: 'published',
+        });
+        const page = await auditQueries.getDocumentAuditLog({ document_id: documentId });
+        expect(page.meta.total).toBe(2);
+        // UUIDv7 ids → newest first: the status change was appended last.
+        expect(page.entries[0]?.action).toBe('document.status.changed');
+        expect(page.entries[1]?.action).toBe('document.locales.changed');
+        const localesEntry = page.entries[1];
+        expect(localesEntry.actorId).toBeNull();
+        expect(localesEntry.before).toEqual(['en']);
+        expect(localesEntry.after).toEqual(['en', 'fr']);
+    });
+    it('rolls back the audit row when its enclosing transaction throws', async () => {
+        const documentId = uuidv7();
+        await expect(txManager.withTransaction(async () => {
+            await auditCommands.append({
+                documentId,
+                actorRealm: 'admin',
+                action: 'document.deleted',
+            });
+            // The unit of work fails after the audit append. If the append had run
+            // on the pool rather than the ambient tx, the row would survive.
+            throw new Error('boom');
+        })).rejects.toThrow('boom');
+        const page = await auditQueries.getDocumentAuditLog({ document_id: documentId });
+        expect(page.meta.total).toBe(0);
+    });
+    it('commits the audit row with its enclosing transaction', async () => {
+        const documentId = uuidv7();
+        await txManager.withTransaction(async () => {
+            await auditCommands.append({
+                documentId,
+                actorRealm: 'admin',
+                action: 'document.deleted',
+            });
+        });
+        const page = await auditQueries.getDocumentAuditLog({ document_id: documentId });
+        expect(page.meta.total).toBe(1);
+        expect(page.entries[0]?.action).toBe('document.deleted');
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/db-postgres",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.9.0",
+  "version": "3.10.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -57,9 +57,9 @@
     "pg": "^8.21.0",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.9.0",
-    "@byline/admin": "3.9.0",
-    "@byline/core": "3.9.0"
+    "@byline/admin": "3.10.1",
+    "@byline/auth": "3.10.1",
+    "@byline/core": "3.10.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",