@byline/core 3.7.0 → 3.8.0

package/dist/@types/db-types.d.ts

@@ -415,6 +415,8 @@ export interface IDocumentCommands {
         documentId: string;
         locale: string;
         status?: string;
+        /** Acting user id for the version audit trail (`created_by`). See docs/AUDIT.md. */
+        createdBy?: string;
     }): Promise<{
         newVersionId: string;
         previousVersionId: string;

package/dist/schemas/zod/builder.d.ts

@@ -12,6 +12,8 @@ export declare const createBaseSchema: (collection?: CollectionDefinition) => z.
     hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
     createdAt: z.ZodISODateTime;
     updatedAt: z.ZodISODateTime;
+    createdBy: z.ZodOptional<z.ZodUUID>;
+    eventType: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const createFieldsSchema: (fields: Field[], strict?: boolean) => z.ZodObject<{
     [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -44,6 +46,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     fields: z.ZodObject<{
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -62,6 +66,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
@@ -78,6 +84,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -113,6 +121,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -140,6 +150,8 @@ export declare const createCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
@@ -157,6 +169,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     fields: z.ZodObject<{
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -175,6 +189,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
@@ -191,6 +207,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -226,6 +244,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -253,6 +273,8 @@ export declare const createCollectionSchemas: (collection: CollectionDefinition)
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
@@ -270,6 +292,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     fields: z.ZodObject<{
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -288,6 +312,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
@@ -304,6 +330,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -339,6 +367,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -366,6 +396,8 @@ export declare const createTypedCollectionSchemas: (collection: CollectionDefini
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;
@@ -383,6 +415,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     fields: z.ZodObject<{
         [x: string]: z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>;
@@ -401,6 +435,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     list: z.ZodObject<{
         docs: z.ZodArray<z.ZodObject<{
@@ -417,6 +453,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -452,6 +490,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
             hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
             createdAt: z.ZodISODateTime;
             updatedAt: z.ZodISODateTime;
+            createdBy: z.ZodOptional<z.ZodUUID>;
+            eventType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
         meta: z.ZodObject<{
             page: z.ZodNumber;
@@ -479,6 +519,8 @@ export declare const createTypedCollectionSchemasForPath: (path: string) => {
         hasPublishedVersion: z.ZodOptional<z.ZodBoolean>;
         createdAt: z.ZodISODateTime;
         updatedAt: z.ZodISODateTime;
+        createdBy: z.ZodOptional<z.ZodUUID>;
+        eventType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
     update: z.ZodObject<{
         [x: string]: z.ZodOptional<z.ZodType<any, unknown, z.core.$ZodTypeInternals<any, unknown>>>;

package/dist/schemas/zod/builder.js

@@ -205,6 +205,11 @@ export const createBaseSchema = (collection) => {
         hasPublishedVersion: z.boolean().optional(),
         createdAt: z.iso.datetime(),
         updatedAt: z.iso.datetime(),
+        // Version audit metadata — acting user + action (see docs/AUDIT.md — Workstream 1).
+        // Declared so list/get/history responses carry them through the
+        // server-fn parse; Zod would otherwise strip them as undeclared keys.
+        createdBy: z.uuid().optional(),
+        eventType: z.string().optional(),
     });
 };
 // Create field schemas for a collection.

package/dist/services/document-lifecycle/copy-to-locale.js

@@ -10,7 +10,7 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
-import { applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
+import { actorId, applyRichTextEmbed, extractVersionId, invokeHook } from './internals.js';
 import { mergeLocaleData } from './merge-locale-data.js';
 /**
  * Copy a document's content from one locale into another, in place on
@@ -133,6 +133,7 @@ export async function copyToLocale(ctx, params) {
             status: getDefaultStatus(definition),
             locale: params.targetLocale,
             previousVersionId,
+            createdBy: actorId(ctx),
         });
         const documentVersionId = extractVersionId(writeResult.document);
         await invokeHook(hooks?.afterUpdate, {

package/dist/services/document-lifecycle/create.js

@@ -13,7 +13,7 @@ import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { slugify } from '../../utils/slugify.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
-import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
+import { actorId, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, maybeAppendOrderKey, rethrowPathConflict, } from './internals.js';
 /**
  * Create a new document.
  *
@@ -75,6 +75,7 @@ export async function createDocument(ctx, params) {
             status: params.status ?? data.status ?? getDefaultStatus(definition),
             locale: params.locale ?? defaultLocale,
             orderKey,
+            createdBy: actorId(ctx),
         })
             .catch((err) => rethrowPathConflict(err, resolvedPath, defaultLocale));
         const documentId = extractDocumentId(result.document);

package/dist/services/document-lifecycle/delete-locale.js

@@ -10,7 +10,7 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
-import { invokeHook } from './internals.js';
+import { actorId, invokeHook } from './internals.js';
 /**
  * Remove one content locale's data from a document, in place on the same
  * document, by writing a new immutable version that omits that locale's
@@ -90,6 +90,7 @@ export async function deleteLocale(ctx, params) {
             documentId: params.documentId,
             locale: params.locale,
             status: getDefaultStatus(definition),
+            createdBy: actorId(ctx),
         });
         if (result == null) {
             throw ERR_NOT_FOUND({

package/dist/services/document-lifecycle/duplicate.js

@@ -12,7 +12,7 @@ import { withLogContext } from '../../lib/logger.js';
 import { slugify } from '../../utils/slugify.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
-import { applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, isPathConflictError, maybeAppendOrderKey, rethrowPathConflict, stripMetaIdsInPlace, } from './internals.js';
+import { actorId, applyRichTextEmbed, derivePath, extractDocumentId, extractVersionId, invokeHook, isPathConflictError, maybeAppendOrderKey, rethrowPathConflict, stripMetaIdsInPlace, } from './internals.js';
 /**
  * Apply the `" (copy)"` suffix to the configured `useAsTitle` field on a
  * duplicate's data tree. Handles both shapes:
@@ -170,6 +170,7 @@ export async function duplicateDocument(ctx, params) {
                 status: defaultStatus,
                 locale: 'all',
                 orderKey,
+                createdBy: actorId(ctx),
             })
                 .catch((err) => rethrowPathConflict(err, finalPath, defaultLocale));
         }
@@ -194,6 +195,7 @@ export async function duplicateDocument(ctx, params) {
                 status: defaultStatus,
                 locale: 'all',
                 orderKey,
+                createdBy: actorId(ctx),
             })
                 .catch((retryErr) => rethrowPathConflict(retryErr, finalPath, defaultLocale));
         }

package/dist/services/document-lifecycle/internals.d.ts

@@ -15,6 +15,14 @@ import { type CollectionDefinition, type CollectionHookSlot } from '../../@types
 import type { BylineLogger } from '../../lib/logger.js';
 import type { SlugifierFn } from '../../utils/slugify.js';
 import type { DocumentLifecycleContext } from './context.js';
+/**
+ * The acting user's id for the version audit trail (`created_by` on
+ * `byline_document_versions`). `undefined` for internal-tooling callers
+ * without a `requestContext` (seeds, migrations — the documented escape
+ * hatch), which persists as NULL. Both actor realms (`AdminAuth`,
+ * `UserAuth`) carry `id`. See docs/AUDIT.md — Workstream 1.
+ */
+export declare function actorId(ctx: DocumentLifecycleContext): string | undefined;
 /**
  * Safely invoke an optional hook slot, awaiting the result if it returns a
  * Promise. When the slot is an array of functions they are executed

package/dist/services/document-lifecycle/internals.js

@@ -17,6 +17,16 @@ import { ERR_PATH_CONFLICT, ErrorCodes } from '../../lib/errors.js';
 import { generateKeyBetween } from '../../lib/fractional-index.js';
 import { createReadContext } from '../populate.js';
 import { embedRichTextFields } from '../richtext-embed.js';
+/**
+ * The acting user's id for the version audit trail (`created_by` on
+ * `byline_document_versions`). `undefined` for internal-tooling callers
+ * without a `requestContext` (seeds, migrations — the documented escape
+ * hatch), which persists as NULL. Both actor realms (`AdminAuth`,
+ * `UserAuth`) carry `id`. See docs/AUDIT.md — Workstream 1.
+ */
+export function actorId(ctx) {
+    return ctx.requestContext?.actor?.id;
+}
 /**
  * Safely invoke an optional hook slot, awaiting the result if it returns a
  * Promise. When the slot is an array of functions they are executed

package/dist/services/document-lifecycle/restore.js

@@ -10,7 +10,7 @@ import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
 import { ERR_INVALID_TRANSITION, ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
 import { withLogContext } from '../../lib/logger.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
-import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook } from './internals.js';
+import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, } from './internals.js';
 /**
  * Restore a historical document version as the new current version.
  *
@@ -139,6 +139,7 @@ export async function restoreDocumentVersion(ctx, params) {
             status: getDefaultStatus(definition),
             locale: 'all',
             previousVersionId: currentMeta.document_version_id,
+            createdBy: actorId(ctx),
         });
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);

package/dist/services/document-lifecycle/update.js

@@ -13,7 +13,7 @@ import { applyPatches } from '../../patches/index.js';
 import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
-import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
+import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
 /**
  * Update a document via full replacement (PUT semantics).
  *
@@ -85,6 +85,7 @@ export async function updateDocument(ctx, params) {
             status: defaultStatus,
             locale: requestLocale,
             previousVersionId: originalData.document_version_id,
+            createdBy: actorId(ctx),
         })
             .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;
@@ -198,6 +199,7 @@ export async function updateDocumentWithPatches(ctx, params) {
             status: defaultStatus,
             locale: requestLocale,
             previousVersionId: originalData.document_version_id,
+            createdBy: actorId(ctx),
         })
             .catch((err) => rethrowPathConflict(err, pathForCommand ?? '', defaultLocale));
         const documentId = extractDocumentId(result.document) || params.documentId;

package/dist/services/document-lifecycle.test.node.js

@@ -139,6 +139,17 @@ describe('Document lifecycle service', () => {
             expect(result.documentId).toBe('doc-1');
             expect(result.documentVersionId).toBe('ver-1');
         });
+        it('passes the acting user id as createdBy for the audit trail', async () => {
+            const { db, createDocumentVersion } = createMockDb();
+            const ctx = buildCtx(db);
+            await createDocument(ctx, {
+                data: { title: 'Hello' },
+                locale: 'en',
+            });
+            // Audit contract (docs/AUDIT.md — W1): every version row
+            // records the actor that created it.
+            expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBe('test-super-admin');
+        });
         it('invokes beforeCreate and afterCreate hooks in order', async () => {
             const callOrder = [];
             const hooks = {
@@ -307,6 +318,16 @@ describe('Document lifecycle service', () => {
     // updateDocument (PUT)
     // -----------------------------------------------------------------------
     describe('updateDocument', () => {
+        it('passes the acting user id as createdBy for the audit trail', async () => {
+            const { db, getDocumentById, createDocumentVersion } = createMockDb();
+            getDocumentById.mockResolvedValue({ status: 'draft', fields: { title: 'Old' } });
+            const ctx = buildCtx(db);
+            await updateDocument(ctx, {
+                documentId: 'doc-1',
+                data: { title: 'New' },
+            });
+            expect(createDocumentVersion.mock.calls[0]?.[0].createdBy).toBe('test-super-admin');
+        });
         it('fetches the original before calling hooks', async () => {
             const { db, getDocumentById, createDocumentVersion } = createMockDb();
             getDocumentById.mockResolvedValue({ status: 'draft', fields: { title: 'Old' } });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.7.0"
+    "@byline/auth": "3.8.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",