@byline/client 3.9.0 → 3.10.1

package/dist/collection-handle.d.ts

@@ -5,9 +5,9 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import type { ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
+import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
 import type { BylineClient } from './client.js';
-import type { ClientDocument, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, HistoryOptions, UpdateOptions } from './types.js';
+import type { AuditLogOptions, ClientDocument, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, HistoryOptions, UpdateOptions } from './types.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -123,6 +123,22 @@ export declare class CollectionHandle {
      * mapped to the same `{ docs, meta }` envelope `find()` returns.
      */
     history<F = Record<string, any>>(documentId: string, options?: HistoryOptions): Promise<FindResult<F>>;
+    /**
+     * Fetch the document-grain audit log for a single document (docs/AUDIT.md —
+     * Workstream 3): the non-versioned system-field writes (path,
+     * available-locales), in-place status transitions, and the deletion event
+     * the immutable version stream deliberately does not record an actor for.
+     *
+     * Applies `beforeRead` as an access gate via `findById` — exactly as
+     * `history()` does — so an actor who cannot see the document at all gets an
+     * empty log rather than leaking change metadata. Entries are newest-first.
+     * Actor *ids* are returned raw; resolving them to display labels is an
+     * admin-realm concern handled above the SDK.
+     *
+     * Returns an empty page when the adapter has no audit-query capability
+     * (`queries.audit` absent) — the same graceful shape as a gated-out read.
+     */
+    auditLog(documentId: string, options?: AuditLogOptions): Promise<AuditLogPage>;
     /**
      * Fetch a specific version of a document by its `documentVersionId`.
      * Used by admin diff views.

package/dist/collection-handle.js

@@ -358,6 +358,49 @@ export class CollectionHandle {
             },
         };
     }
+    /**
+     * Fetch the document-grain audit log for a single document (docs/AUDIT.md —
+     * Workstream 3): the non-versioned system-field writes (path,
+     * available-locales), in-place status transitions, and the deletion event
+     * the immutable version stream deliberately does not record an actor for.
+     *
+     * Applies `beforeRead` as an access gate via `findById` — exactly as
+     * `history()` does — so an actor who cannot see the document at all gets an
+     * empty log rather than leaking change metadata. Entries are newest-first.
+     * Actor *ids* are returned raw; resolving them to display labels is an
+     * admin-realm concern handled above the SDK.
+     *
+     * Returns an empty page when the adapter has no audit-query capability
+     * (`queries.audit` absent) — the same graceful shape as a gated-out read.
+     */
+    async auditLog(documentId, options = {}) {
+        await this.resolveAndAssertRead();
+        const readCtx = options._readContext ?? createReadContext();
+        const locale = options.locale ?? this.client.defaultLocale;
+        const page = options.page ?? 1;
+        const pageSize = options.pageSize ?? 20;
+        const empty = { entries: [], meta: { total: 0, page, pageSize, totalPages: 0 } };
+        // Access gate — same rationale as `history()`. `status: 'any'` asks "can
+        // the actor see *any* version of this document?", so a draft-only doc with
+        // the owning actor still surfaces its audit log.
+        if (!options._bypassBeforeRead) {
+            const accessible = await this.findById(documentId, {
+                locale,
+                status: 'any',
+                _readContext: readCtx,
+            });
+            if (accessible == null)
+                return empty;
+        }
+        const audit = this.client.db.queries.audit;
+        if (audit == null)
+            return empty;
+        return audit.getDocumentAuditLog({
+            document_id: documentId,
+            page,
+            page_size: pageSize,
+        });
+    }
     /**
      * Fetch a specific version of a document by its `documentVersionId`.
      * Used by admin diff views.

package/dist/index.d.ts

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-export { type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, } from '@byline/core';
+export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type CreateDocumentResult, type CycleRelationValue, createReadContext, type DeleteDocumentResult, ERR_CONFLICT, ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_READ_BUDGET_EXCEEDED, ERR_VALIDATION, type PopulatedRelationValue, type PopulateFieldOptions, type PopulateFieldSpec, type PopulateMap, type PopulateSpec, type ReadContext, type ReadMode, type RestoreVersionResult, type UnpublishResult, type UnresolvedRelationValue, type UpdateDocumentResult, } from '@byline/core';
 export { BylineClient, createBylineClient } from './client.js';
 export { CollectionHandle } from './collection-handle.js';
-export type { BylineClientConfig, ClientDocument, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, PopulatedRelation, SortDirection, SortSpec, UpdateOptions, WhereClause, WhereValue, WithPopulated, } from './types.js';
+export type { AuditLogOptions, BylineClientConfig, ClientDocument, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, PopulatedRelation, SortDirection, SortSpec, UpdateOptions, WhereClause, WhereValue, WithPopulated, } from './types.js';

package/dist/types.d.ts

@@ -229,6 +229,22 @@ export interface HistoryOptions extends BeforeReadControls {
     /** @internal — see `_readContext` on read options. */
     _readContext?: ReadContext;
 }
+/**
+ * Options for `CollectionHandle.auditLog(documentId, options)`. The
+ * document-grain audit log (docs/AUDIT.md — Workstream 3) records the
+ * non-versioned changes the immutable version stream does not capture an
+ * actor for: system-field writes (path, available-locales), in-place status
+ * transitions, and the deletion event. Entries are newest-first and paged;
+ * `_bypassBeforeRead` skips the `findById` access gate for admin tooling.
+ */
+export interface AuditLogOptions extends BeforeReadControls {
+    page?: number;
+    pageSize?: number;
+    /** Locale used by the access-gate `findById`. Defaults to the client's `defaultLocale`. */
+    locale?: string;
+    /** @internal — see `_readContext` on read options. */
+    _readContext?: ReadContext;
+}
 /**
  * Options for `CollectionHandle.findByVersion(versionId, options)`. No
  * `BeforeReadControls` — `findByVersion` is a low-level pass-through

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.9.0",
+  "version": "3.10.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -38,8 +38,8 @@
   ],
   "dependencies": {
     "npm-run-all": "^4.1.5",
-    "@byline/auth": "3.9.0",
-    "@byline/core": "3.9.0"
+    "@byline/auth": "3.10.1",
+    "@byline/core": "3.10.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",
@@ -51,7 +51,7 @@
     "tsx": "^4.22.3",
     "typescript": "6.0.3",
     "vitest": "^4.1.7",
-    "@byline/db-postgres": "3.9.0"
+    "@byline/db-postgres": "3.10.1"
   },
   "publishConfig": {
     "access": "public",