@byline/core 1.0.0 → 1.2.0

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

@@ -320,21 +320,32 @@ export interface AfterCreateContext {
     documentVersionId: string;
 }
 /**
- * Context passed to `beforeUpdate` hooks — both PUT and patch flows.
+ * Context passed to `beforeUpdate` hooks — PUT, patch, and restore flows.
  *
  * `data` is the next version (mutable). `originalData` is the previous
  * version as reconstructed from storage.
+ *
+ * `restore` is set only when the update originates from a "make current"
+ * action against a historical version. Userland hooks that need to react
+ * differently (e.g. tag the audit entry, skip search re-index) can branch
+ * on its presence.
  */
 export interface BeforeUpdateContext {
     data: Record<string, any>;
     originalData: Record<string, any>;
     collectionPath: string;
+    restore?: {
+        sourceVersionId: string;
+    };
 }
 /**
  * Context passed to `afterUpdate` hooks.
  *
  * Includes the `documentId` and `documentVersionId` of the newly created
  * version so the hook can reference the persisted document.
+ *
+ * `restore` mirrors `BeforeUpdateContext.restore` — present only when the
+ * update was triggered by restoring a historical version.
  */
 export interface AfterUpdateContext {
     data: Record<string, any>;
@@ -342,6 +353,9 @@ export interface AfterUpdateContext {
     collectionPath: string;
     documentId: string;
     documentVersionId: string;
+    restore?: {
+        sourceVersionId: string;
+    };
 }
 /**
  * Context passed to `beforeStatusChange` / `afterStatusChange` hooks.

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

@@ -112,6 +112,11 @@ export interface UnpublishResult {
 export interface DeleteDocumentResult {
     deletedVersionCount: number;
 }
+export interface RestoreVersionResult {
+    documentId: string;
+    documentVersionId: string;
+    sourceVersionId: string;
+}
 /**
  * Create a new document.
  *
@@ -216,6 +221,50 @@ export declare function changeDocumentStatus(ctx: DocumentLifecycleContext, para
 export declare function unpublishDocument(ctx: DocumentLifecycleContext, params: {
     documentId: string;
 }): Promise<UnpublishResult>;
+/**
+ * Restore a historical document version as the new current version.
+ *
+ * Reads the source version with `locale: 'all'` so the entire multi-locale
+ * field tree (with `_id` / `_type` meta inlined onto blocks and array items
+ * by `reconstructFromUnifiedRows`) is captured. That tree is then re-emitted
+ * through `createDocumentVersion` with `locale: 'all'`, which produces a
+ * fresh version row with a new UUIDv7 id and the latest `created_at`. The
+ * `current_documents` view (`ROW_NUMBER() OVER PARTITION BY document_id
+ * ORDER BY created_at DESC`) automatically promotes the new row to current.
+ *
+ * Status is hard-defaulted to the workflow's first status — restoring an
+ * old `published` version must never silently re-publish content. The user
+ * runs the restored draft through the normal workflow.
+ *
+ * `path` is sticky from the previous current version (not from the source),
+ * matching the semantics of `updateDocument`. A path change made between
+ * the source and now should not be undone by the restore.
+ *
+ * Auth reuses the `update` ability — restore is conceptually an edit
+ * against an existing document.
+ *
+ * Hooks: fires `beforeUpdate` / `afterUpdate` with a `restore: { sourceVersionId }`
+ * field on the context. Userland hooks that need to react differently
+ * (e.g. tag the audit entry, skip search re-index) can branch on its
+ * presence.
+ *
+ * Flow:
+ *   1. Auth: `update` ability.
+ *   2. Read source version with `locale: 'all'`.
+ *   3. Validate source belongs to `documentId` (defence against forged
+ *      cross-document version ids).
+ *   4. Read current version metadata; reject if the source IS already the
+ *      current version (nothing to restore).
+ *   5. Read current document with reconstruction for hook `originalData`.
+ *   6. `hooks.beforeUpdate({ data, originalData, collectionPath, restore })`
+ *   7. `db.commands.documents.createDocumentVersion(...)` with
+ *      `action: 'restore'`, `locale: 'all'`, sticky path, default status.
+ *   8. `hooks.afterUpdate({ ..., restore })`
+ */
+export declare function restoreDocumentVersion(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    sourceVersionId: string;
+}): Promise<RestoreVersionResult>;
 /**
  * Soft-delete a document.
  *

package/dist/services/document-lifecycle.js

@@ -383,6 +383,146 @@ export async function unpublishDocument(ctx, params) {
         return { archivedCount };
     });
 }
+/**
+ * Restore a historical document version as the new current version.
+ *
+ * Reads the source version with `locale: 'all'` so the entire multi-locale
+ * field tree (with `_id` / `_type` meta inlined onto blocks and array items
+ * by `reconstructFromUnifiedRows`) is captured. That tree is then re-emitted
+ * through `createDocumentVersion` with `locale: 'all'`, which produces a
+ * fresh version row with a new UUIDv7 id and the latest `created_at`. The
+ * `current_documents` view (`ROW_NUMBER() OVER PARTITION BY document_id
+ * ORDER BY created_at DESC`) automatically promotes the new row to current.
+ *
+ * Status is hard-defaulted to the workflow's first status — restoring an
+ * old `published` version must never silently re-publish content. The user
+ * runs the restored draft through the normal workflow.
+ *
+ * `path` is sticky from the previous current version (not from the source),
+ * matching the semantics of `updateDocument`. A path change made between
+ * the source and now should not be undone by the restore.
+ *
+ * Auth reuses the `update` ability — restore is conceptually an edit
+ * against an existing document.
+ *
+ * Hooks: fires `beforeUpdate` / `afterUpdate` with a `restore: { sourceVersionId }`
+ * field on the context. Userland hooks that need to react differently
+ * (e.g. tag the audit entry, skip search re-index) can branch on its
+ * presence.
+ *
+ * Flow:
+ *   1. Auth: `update` ability.
+ *   2. Read source version with `locale: 'all'`.
+ *   3. Validate source belongs to `documentId` (defence against forged
+ *      cross-document version ids).
+ *   4. Read current version metadata; reject if the source IS already the
+ *      current version (nothing to restore).
+ *   5. Read current document with reconstruction for hook `originalData`.
+ *   6. `hooks.beforeUpdate({ data, originalData, collectionPath, restore })`
+ *   7. `db.commands.documents.createDocumentVersion(...)` with
+ *      `action: 'restore'`, `locale: 'all'`, sticky path, default status.
+ *   8. `hooks.afterUpdate({ ..., restore })`
+ */
+export async function restoreDocumentVersion(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'restoreDocumentVersion' }, async () => {
+        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        const hooks = definition.hooks;
+        // 1. Read source version (full multi-locale tree).
+        const source = await db.queries.documents.getDocumentByVersion({
+            document_version_id: params.sourceVersionId,
+            locale: 'all',
+        });
+        if (source == null) {
+            throw ERR_NOT_FOUND({
+                message: 'source version not found',
+                details: { sourceVersionId: params.sourceVersionId },
+            }).log(ctx.logger);
+        }
+        // 2. Cross-document forgery check.
+        if (source.document_id !== params.documentId) {
+            throw ERR_VALIDATION({
+                message: 'source version does not belong to the target document',
+                details: {
+                    documentId: params.documentId,
+                    sourceVersionId: params.sourceVersionId,
+                    sourceDocumentId: source.document_id,
+                },
+            }).log(ctx.logger);
+        }
+        // 3. Current version metadata — used both for the already-current
+        //    guard and for the sticky path resolution.
+        const currentMeta = await db.queries.documents.getCurrentVersionMetadata({
+            collection_id: collectionId,
+            document_id: params.documentId,
+        });
+        if (currentMeta == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId },
+            }).log(ctx.logger);
+        }
+        if (currentMeta.document_version_id === params.sourceVersionId) {
+            throw ERR_INVALID_TRANSITION({
+                message: 'source version is already the current version of this document',
+                details: {
+                    documentId: params.documentId,
+                    sourceVersionId: params.sourceVersionId,
+                },
+            }).log(ctx.logger);
+        }
+        // 4. originalData for hooks: full reconstruction of the current
+        //    version (locale-scoped, matching updateDocument's semantics).
+        const latest = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.documentId,
+            locale: defaultLocale,
+            reconstruct: true,
+        });
+        const originalData = latest ?? {};
+        const sourceFields = source.fields ?? {};
+        const restoreContext = { sourceVersionId: params.sourceVersionId };
+        // 5. beforeUpdate.
+        await invokeHook(hooks?.beforeUpdate, {
+            data: sourceFields,
+            originalData,
+            collectionPath,
+            restore: restoreContext,
+        });
+        // 6. Persist new version. locale: 'all' carries every locale row in
+        //    the source tree forward in a single flatten pass — the
+        //    cross-locale carry-forward branch in createDocumentVersion does
+        //    not fire when locale === 'all'.
+        const result = await db.commands.documents.createDocumentVersion({
+            documentId: params.documentId,
+            collectionId,
+            collectionVersion: ctx.collectionVersion,
+            collectionConfig: definition,
+            action: 'restore',
+            documentData: sourceFields,
+            path: currentMeta.path,
+            status: getDefaultStatus(definition),
+            locale: 'all',
+            previousVersionId: currentMeta.document_version_id,
+        });
+        const documentId = extractDocumentId(result.document) || params.documentId;
+        const documentVersionId = extractVersionId(result.document);
+        // 7. afterUpdate.
+        await invokeHook(hooks?.afterUpdate, {
+            data: sourceFields,
+            originalData,
+            collectionPath,
+            documentId,
+            documentVersionId,
+            restore: restoreContext,
+        });
+        return {
+            documentId,
+            documentVersionId,
+            sourceVersionId: params.sourceVersionId,
+        };
+    });
+}
 /**
  * Soft-delete a document.
  *

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

@@ -8,7 +8,7 @@
 import { AdminAuth, AuthError, AuthErrorCodes, createRequestContext, createSuperAdminContext, } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
 import { BylineError, ErrorCodes } from '../lib/errors.js';
-import { changeDocumentStatus, createDocument, deleteDocument, unpublishDocument, updateDocument, updateDocumentWithPatches, } from './document-lifecycle.js';
+import { changeDocumentStatus, createDocument, deleteDocument, restoreDocumentVersion, unpublishDocument, updateDocument, updateDocumentWithPatches, } from './document-lifecycle.js';
 // ---------------------------------------------------------------------------
 // Fixtures / Helpers
 // ---------------------------------------------------------------------------
@@ -648,6 +648,180 @@ describe('Document lifecycle service', () => {
         });
     });
     // -----------------------------------------------------------------------
+    // restoreDocumentVersion
+    // -----------------------------------------------------------------------
+    describe('restoreDocumentVersion', () => {
+        function setupRestore(opts) {
+            const sourceDocumentId = opts?.sourceDocumentId ?? 'doc-1';
+            const currentVersionId = opts?.currentVersionId ?? 'ver-current';
+            const sourceVersionId = 'ver-source';
+            const currentPath = opts?.currentPath ?? 'sticky-path';
+            const sourceFields = opts?.sourceFields ?? {
+                title: { en: 'Old EN', fr: 'Vieux FR' },
+            };
+            const mocks = createMockDb();
+            const { db } = mocks;
+            db.queries.documents.getDocumentByVersion.mockResolvedValue({
+                document_version_id: sourceVersionId,
+                document_id: sourceDocumentId,
+                path: 'long-ago-path',
+                status: 'archived',
+                fields: sourceFields,
+            });
+            mocks.getCurrentVersionMetadata.mockResolvedValue({
+                document_version_id: currentVersionId,
+                document_id: 'doc-1',
+                collection_id: 'col-1',
+                path: currentPath,
+                status: 'published',
+                created_at: new Date(),
+                updated_at: new Date(),
+            });
+            mocks.getDocumentById.mockResolvedValue({
+                document_version_id: currentVersionId,
+                path: currentPath,
+                status: 'published',
+                fields: { title: 'Currently Published' },
+            });
+            mocks.createDocumentVersion.mockResolvedValue({
+                document: { id: 'ver-restored', document_id: 'doc-1' },
+                fieldCount: 5,
+            });
+            return { ...mocks, sourceVersionId, currentVersionId, sourceFields, currentPath };
+        }
+        it('reads the source with locale: "all" and re-emits via createDocumentVersion', async () => {
+            const { db, createDocumentVersion, sourceVersionId, sourceFields, currentVersionId } = setupRestore();
+            const ctx = buildCtx(db);
+            const result = await restoreDocumentVersion(ctx, {
+                documentId: 'doc-1',
+                sourceVersionId,
+            });
+            expect(db.queries.documents.getDocumentByVersion).toHaveBeenCalledWith({
+                document_version_id: sourceVersionId,
+                locale: 'all',
+            });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+            const call = createDocumentVersion.mock.calls[0]?.[0];
+            expect(call.action).toBe('restore');
+            expect(call.locale).toBe('all');
+            expect(call.documentData).toEqual(sourceFields);
+            expect(call.previousVersionId).toBe(currentVersionId);
+            expect(result).toEqual({
+                documentId: 'doc-1',
+                documentVersionId: 'ver-restored',
+                sourceVersionId,
+            });
+        });
+        it('hard-defaults the new version status to the workflow default (never inherits source status)', async () => {
+            const { db, createDocumentVersion, sourceVersionId } = setupRestore();
+            const ctx = buildCtx(db);
+            await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+            // Source version was 'archived'; default status for minimalCollection is 'draft'.
+            expect(createDocumentVersion.mock.calls[0]?.[0].status).toBe('draft');
+        });
+        it('keeps path sticky from the current version, not the source', async () => {
+            const { db, createDocumentVersion, sourceVersionId } = setupRestore({
+                currentPath: 'sticky-path',
+            });
+            const ctx = buildCtx(db);
+            await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+            expect(createDocumentVersion.mock.calls[0]?.[0].path).toBe('sticky-path');
+        });
+        it('rejects when the source version belongs to a different document', async () => {
+            const { db, sourceVersionId, createDocumentVersion } = setupRestore({
+                sourceDocumentId: 'doc-OTHER',
+            });
+            const ctx = buildCtx(db);
+            try {
+                await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+                expect.fail('expected ERR_VALIDATION');
+            }
+            catch (err) {
+                expect(err).toBeInstanceOf(BylineError);
+                expect(err.code).toBe(ErrorCodes.VALIDATION);
+            }
+            expect(createDocumentVersion).not.toHaveBeenCalled();
+        });
+        it('rejects when the source is already the current version', async () => {
+            const sourceVersionId = 'ver-source';
+            const mocks = createMockDb();
+            const { db } = mocks;
+            db.queries.documents.getDocumentByVersion.mockResolvedValue({
+                document_version_id: sourceVersionId,
+                document_id: 'doc-1',
+                path: 'p',
+                status: 'draft',
+                fields: {},
+            });
+            mocks.getCurrentVersionMetadata.mockResolvedValue({
+                document_version_id: sourceVersionId, // SAME as source
+                document_id: 'doc-1',
+                collection_id: 'col-1',
+                path: 'p',
+                status: 'draft',
+                created_at: new Date(),
+                updated_at: new Date(),
+            });
+            const ctx = buildCtx(db);
+            try {
+                await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+                expect.fail('expected ERR_INVALID_TRANSITION');
+            }
+            catch (err) {
+                expect(err.code).toBe(ErrorCodes.INVALID_TRANSITION);
+            }
+            expect(mocks.createDocumentVersion).not.toHaveBeenCalled();
+        });
+        it('fires beforeUpdate / afterUpdate with restore: { sourceVersionId } context', async () => {
+            const beforeUpdate = vi.fn();
+            const afterUpdate = vi.fn();
+            const { db, sourceVersionId } = setupRestore();
+            const definition = { ...minimalCollection, hooks: { beforeUpdate, afterUpdate } };
+            const ctx = buildCtx(db, definition);
+            await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+            expect(beforeUpdate).toHaveBeenCalledWith(expect.objectContaining({
+                collectionPath: 'articles',
+                restore: { sourceVersionId },
+                originalData: expect.objectContaining({
+                    fields: expect.objectContaining({ title: 'Currently Published' }),
+                }),
+            }));
+            expect(afterUpdate).toHaveBeenCalledWith(expect.objectContaining({
+                documentId: 'doc-1',
+                documentVersionId: 'ver-restored',
+                restore: { sourceVersionId },
+            }));
+        });
+        it('throws ERR_FORBIDDEN when actor lacks collections.<path>.update', async () => {
+            const { db, sourceVersionId } = setupRestore();
+            const ctx = buildCtx(db);
+            const actor = new AdminAuth({
+                id: 'editor',
+                abilities: ['collections.articles.read'],
+            });
+            ctx.requestContext = createRequestContext({ actor });
+            try {
+                await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+                expect.fail('expected ERR_FORBIDDEN');
+            }
+            catch (err) {
+                expect(err.code).toBe(AuthErrorCodes.FORBIDDEN);
+                expect(err.message).toContain('collections.articles.update');
+            }
+        });
+        it('permits restore when actor holds only collections.<path>.update (no separate restore verb needed)', async () => {
+            const { db, createDocumentVersion, sourceVersionId } = setupRestore();
+            const ctx = buildCtx(db);
+            const actor = new AdminAuth({
+                id: 'editor',
+                abilities: ['collections.articles.update', 'collections.articles.read'],
+            });
+            ctx.requestContext = createRequestContext({ actor });
+            await restoreDocumentVersion(ctx, { documentId: 'doc-1', sourceVersionId });
+            expect(createDocumentVersion).toHaveBeenCalledOnce();
+        });
+    });
+    // -----------------------------------------------------------------------
     // Ability enforcement (Phase 4)
     // -----------------------------------------------------------------------
     describe('ability enforcement', () => {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -73,7 +73,7 @@
     "pino": "^10.3.1",
     "uuid": "^14.0.0",
     "zod": "^4.4.2",
-    "@byline/auth": "1.0.0"
+    "@byline/auth": "1.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.14",