@byline/core 0.9.3

package/dist/services/collection-bootstrap.test.node.js

@@ -0,0 +1,208 @@
+/**
+ * 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 { describe, expect, it, vi } from 'vitest';
+import { fingerprintCollection } from '../storage/collection-fingerprint.js';
+import { ensureCollections } from './collection-bootstrap.js';
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+function baseCollection() {
+    return {
+        path: 'news',
+        labels: { singular: 'News', plural: 'News' },
+        fields: [{ name: 'title', type: 'text' }],
+        workflow: {
+            statuses: [{ name: 'draft' }, { name: 'published' }, { name: 'archived' }],
+        },
+    };
+}
+// Build a minimal IDbAdapter. We only wire the methods `ensureCollections`
+// actually calls; the others throw if touched so we catch accidental usage.
+function createMockDb(options) {
+    const getCollectionByPath = vi.fn().mockResolvedValue(options.existingRow ?? null);
+    const create = vi
+        .fn()
+        .mockImplementation(async (_path, _config, _opts) => [
+        { id: 'col-new' },
+    ]);
+    const update = vi.fn().mockResolvedValue([{ id: options.existingRow?.id ?? 'col-new' }]);
+    const fail = () => {
+        throw new Error('not expected to be called');
+    };
+    const db = {
+        commands: {
+            collections: { create, update, delete: vi.fn(fail) },
+            documents: {
+                createDocumentVersion: vi.fn(fail),
+                setDocumentStatus: vi.fn(fail),
+                archivePublishedVersions: vi.fn(fail),
+                softDeleteDocument: vi.fn(fail),
+            },
+        },
+        queries: {
+            collections: {
+                getAllCollections: vi.fn(fail),
+                getCollectionByPath,
+                getCollectionById: vi.fn(fail),
+            },
+            documents: {
+                getDocumentById: vi.fn(fail),
+                getCurrentVersionMetadata: vi.fn(fail),
+                getDocumentByPath: vi.fn(fail),
+                getDocumentByVersion: vi.fn(fail),
+                getDocumentsByVersionIds: vi.fn(fail),
+                getDocumentsByDocumentIds: vi.fn(fail),
+                getDocumentHistory: vi.fn(fail),
+                getPublishedVersion: vi.fn(fail),
+                getPublishedDocumentIds: vi.fn(fail),
+                getDocumentCountsByStatus: vi.fn(fail),
+                findDocuments: vi.fn(fail),
+            },
+        },
+    };
+    return { db, create, update, getCollectionByPath };
+}
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('ensureCollections', () => {
+    it('inserts a new row with version 1 and the schema fingerprint', async () => {
+        const def = baseCollection();
+        const { db, create, update } = createMockDb({ existingRow: null });
+        const records = await ensureCollections({ definitions: [def], db });
+        expect(create).toHaveBeenCalledTimes(1);
+        expect(update).not.toHaveBeenCalled();
+        const [path, config, opts] = create.mock.calls[0];
+        expect(path).toBe('news');
+        expect(config).toBe(def);
+        const expectedHash = await fingerprintCollection(def);
+        expect(opts).toEqual({ version: 1, schemaHash: expectedHash });
+        expect(records.get('news')).toEqual({
+            collectionId: 'col-new',
+            version: 1,
+            schemaHash: expectedHash,
+        });
+    });
+    it('honours an explicit version pin on first insert', async () => {
+        const def = { ...baseCollection(), version: 5 };
+        const { db, create } = createMockDb({ existingRow: null });
+        await ensureCollections({ definitions: [def], db });
+        const [, , opts] = create.mock.calls[0];
+        expect(opts.version).toBe(5);
+    });
+    it('is a no-op when the stored hash matches the current fingerprint', async () => {
+        const def = baseCollection();
+        const hash = await fingerprintCollection(def);
+        const { db, create, update } = createMockDb({
+            existingRow: { id: 'col-1', version: 3, schema_hash: hash },
+        });
+        const records = await ensureCollections({ definitions: [def], db });
+        expect(create).not.toHaveBeenCalled();
+        expect(update).not.toHaveBeenCalled();
+        expect(records.get('news')).toEqual({
+            collectionId: 'col-1',
+            version: 3,
+            schemaHash: hash,
+        });
+    });
+    it('auto-bumps the version when the fingerprint changes', async () => {
+        const def = baseCollection();
+        // Seed the DB with a mismatched hash.
+        const { db, update } = createMockDb({
+            existingRow: { id: 'col-1', version: 3, schema_hash: 'stale-hash' },
+        });
+        const records = await ensureCollections({ definitions: [def], db });
+        expect(update).toHaveBeenCalledTimes(1);
+        const [id, patch] = update.mock.calls[0];
+        expect(id).toBe('col-1');
+        expect(patch).toEqual({
+            config: def,
+            version: 4,
+            schemaHash: await fingerprintCollection(def),
+        });
+        expect(records.get('news')?.version).toBe(4);
+    });
+    it('uses an explicit pin on update when >= the stored version', async () => {
+        const def = { ...baseCollection(), version: 9 };
+        const { db, update } = createMockDb({
+            existingRow: { id: 'col-1', version: 3, schema_hash: 'stale' },
+        });
+        const records = await ensureCollections({ definitions: [def], db });
+        expect(update.mock.calls[0]?.[1].version).toBe(9);
+        expect(records.get('news')?.version).toBe(9);
+    });
+    it('throws when an explicit pin is less than the stored version', async () => {
+        const def = { ...baseCollection(), version: 2 };
+        const { db } = createMockDb({
+            existingRow: { id: 'col-1', version: 5, schema_hash: 'stale' },
+        });
+        await expect(ensureCollections({ definitions: [def], db })).rejects.toThrow(/backwards/i);
+    });
+    it('backfills schema_hash without bumping when stored hash is null', async () => {
+        const def = baseCollection();
+        const { db, update } = createMockDb({
+            existingRow: { id: 'col-1', version: 3, schema_hash: null },
+        });
+        const records = await ensureCollections({ definitions: [def], db });
+        expect(update).toHaveBeenCalledTimes(1);
+        const [, patch] = update.mock.calls[0];
+        expect(patch.version).toBe(3); // unchanged
+        expect(patch.schemaHash).toBe(await fingerprintCollection(def));
+        expect(records.get('news')?.version).toBe(3);
+    });
+    it('reconciles multiple collections in one pass', async () => {
+        const a = baseCollection();
+        const b = { ...baseCollection(), path: 'pages' };
+        const hashA = await fingerprintCollection(a);
+        // For `a` the DB matches; for `b` it does not exist yet.
+        const getCollectionByPath = vi.fn(async (path) => {
+            if (path === 'news')
+                return { id: 'col-news', version: 2, schema_hash: hashA };
+            return null;
+        });
+        const create = vi.fn().mockResolvedValue([{ id: 'col-pages' }]);
+        const update = vi.fn();
+        const db = {
+            commands: {
+                collections: { create, update, delete: vi.fn() },
+                documents: {
+                    createDocumentVersion: vi.fn(),
+                    setDocumentStatus: vi.fn(),
+                    archivePublishedVersions: vi.fn(),
+                    softDeleteDocument: vi.fn(),
+                },
+            },
+            queries: {
+                collections: {
+                    getAllCollections: vi.fn(),
+                    getCollectionByPath,
+                    getCollectionById: vi.fn(),
+                },
+                documents: {
+                    getDocumentById: vi.fn(),
+                    getCurrentVersionMetadata: vi.fn(),
+                    getDocumentByPath: vi.fn(),
+                    getDocumentByVersion: vi.fn(),
+                    getDocumentsByVersionIds: vi.fn(),
+                    getDocumentsByDocumentIds: vi.fn(),
+                    getDocumentHistory: vi.fn(),
+                    getPublishedVersion: vi.fn(),
+                    getPublishedDocumentIds: vi.fn(),
+                    getDocumentCountsByStatus: vi.fn(),
+                    findDocuments: vi.fn(),
+                },
+            },
+        };
+        const records = await ensureCollections({ definitions: [a, b], db });
+        expect(records.get('news')?.version).toBe(2);
+        expect(records.get('pages')?.version).toBe(1);
+        expect(create).toHaveBeenCalledTimes(1);
+        expect(update).not.toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=collection-bootstrap.test.node.js.map

package/dist/services/collection-bootstrap.test.node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collection-bootstrap.test.node.js","sourceRoot":"","sources":["../../src/services/collection-bootstrap.test.node.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,245 @@
+/**
+ * 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
+ */
+/**
+ * Document lifecycle service.
+ *
+ * Orchestrates CRUD operations and workflow transitions, invoking collection
+ * hooks at the appropriate points. Sits between the API route layer and the
+ * storage adapter (`IDbAdapter`) so that every operation path — POST, PUT,
+ * PATCH, status change, unpublish — goes through a single set of hooks.
+ *
+ * Hook invocations run **outside** the storage transaction. They are suitable
+ * for logging, cache invalidation, webhooks, and similar side-effects.
+ *
+ * This module depends only on `@byline/core` types and utilities — it has no
+ * dependency on any specific database adapter.
+ */
+import type { RequestContext } from '@byline/auth';
+import { type CollectionDefinition, type IDbAdapter, type IStorageProvider } from '../@types/index.js';
+import { type SlugifierFn } from '../utils/slugify.js';
+import type { BylineLogger } from '../lib/logger.js';
+import type { DocumentPatch } from '../patches/index.js';
+/**
+ * The shared context every lifecycle function requires. Built once per
+ * request by the API route layer and passed through.
+ */
+export interface DocumentLifecycleContext {
+    /** The database adapter returned by `getServerConfig().db`. */
+    db: IDbAdapter;
+    /** The resolved `CollectionDefinition` (includes `hooks`). */
+    definition: CollectionDefinition;
+    /** The database-level collection row ID. */
+    collectionId: string;
+    /**
+     * The collection's current schema version. Stamped onto every
+     * `documentVersions` row written during the lifecycle call so that
+     * Phase-2 in-memory migration can later resolve each document against
+     * the shape it was authored under. Callers resolve this from the core
+     * registry (`core.getCollectionRecord(path).version`).
+     */
+    collectionVersion: number;
+    /** The collection `path` string (e.g. `'docs'`, `'news'`). */
+    collectionPath: string;
+    /**
+     * Storage provider for this collection. Required when the collection
+     * has any upload-capable image/file field, so that the original files
+     * and their persisted variants can be cleaned up on document deletion.
+     *
+     * Resolved by the route layer as:
+     *   `field.upload?.storage ?? serverConfig.storage`
+     *
+     * Optional — callers whose collections have no upload-capable fields
+     * are unaffected.
+     */
+    storage?: IStorageProvider;
+    /** Structured logger instance. Provided via the DI registry. */
+    logger: BylineLogger;
+    /**
+     * The default content locale (e.g. `'en'`). Used to anchor `path`
+     * derivation: the slugifier always runs against the default-locale
+     * source value, and creating a brand-new document in any other locale
+     * is rejected.
+     *
+     * Sourced by callers from `ServerConfig.i18n.content.defaultLocale`.
+     */
+    defaultLocale: string;
+    /**
+     * Installation slugifier. When omitted, the lifecycle falls back to
+     * the default `slugify` exported from `@byline/core`.
+     */
+    slugifier?: SlugifierFn;
+    /**
+     * Request-scoped context carrying the authenticated actor, request id,
+     * and related per-request metadata.
+     *
+     * Plumbing only in Phase 0 of the auth roadmap — present on the context
+     * so every lifecycle service can accept and forward it, but no ability
+     * assertions are performed yet. Phase 4 turns enforcement on: lifecycle
+     * entry points will call `context.requestContext?.actor?.assertAbility(...)`
+     * before any storage mutation.
+     *
+     * Optional in Phase 0 so that existing callers (admin server fns, seed
+     * scripts, tests) continue to compile. Phase 4 tightens the type.
+     *
+     * See docs/analysis/AUTHN-AUTHZ-ANALYSIS.md.
+     */
+    requestContext?: RequestContext;
+}
+export interface CreateDocumentResult {
+    documentId: string;
+    documentVersionId: string;
+}
+export interface UpdateDocumentResult {
+    documentId: string;
+    documentVersionId: string;
+}
+export interface UpdateDocumentWithPatchesResult {
+    documentId: string;
+    documentVersionId: string;
+}
+export interface ChangeStatusResult {
+    previousStatus: string;
+    newStatus: string;
+}
+export interface UnpublishResult {
+    archivedCount: number;
+}
+export interface DeleteDocumentResult {
+    deletedVersionCount: number;
+}
+/**
+ * Create a new document.
+ *
+ * Flow:
+ *   1. Default-locale enforcement: reject if `params.locale` is anything
+ *      other than the configured default content locale (a brand-new
+ *      document's canonical `path` lives in the default locale).
+ *   2. `normaliseDateFields(data)`
+ *   3. `hooks.beforeCreate({ data, collectionPath })`
+ *   4. Resolve `path` — explicit `params.path` → derive via `useAsPath`
+ *      → UUID fallback.
+ *   5. `db.commands.documents.createDocumentVersion(...)` (action = 'create')
+ *   6. `hooks.afterCreate({ data, collectionPath, documentId, documentVersionId })`
+ */
+export declare function createDocument(ctx: DocumentLifecycleContext, params: {
+    data: Record<string, any>;
+    locale?: string;
+    status?: string;
+    /**
+     * Explicit, user-supplied path (e.g. from the admin sidebar widget
+     * or an SDK caller importing legacy content). When omitted, the
+     * lifecycle derives the value from `definition.useAsPath`.
+     */
+    path?: string;
+}): Promise<CreateDocumentResult>;
+/**
+ * Update a document via full replacement (PUT semantics).
+ *
+ * Unlike the previous implementation, this now fetches the current version
+ * from storage to provide a real `originalData` to hooks.
+ *
+ * Flow:
+ *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
+ *   2. `normaliseDateFields(data)`
+ *   3. `hooks.beforeUpdate({ data, originalData, collectionPath })`
+ *   4. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
+ *   5. `hooks.afterUpdate({ data, originalData, collectionPath, documentId, documentVersionId })`
+ */
+export declare function updateDocument(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    data: Record<string, any>;
+    locale?: string;
+    /**
+     * Explicit path override. When omitted, the previous version's path
+     * carries forward unchanged (sticky). The lifecycle never re-derives
+     * `path` from the source field on update — that is an explicit user
+     * action driven by the admin path widget.
+     */
+    path?: string;
+}): Promise<UpdateDocumentResult>;
+/**
+ * Update a document via patch application.
+ *
+ * Flow:
+ *   1. Fetch current document via `getDocumentById({ reconstruct: true })`
+ *   2. Optimistic concurrency check on `documentVersionId`
+ *   3. `applyPatches(definition, originalData, patches)` → `nextData`
+ *   4. `normaliseDateFields(nextData)`
+ *   5. `hooks.beforeUpdate({ data: nextData, originalData, collectionPath })`
+ *   6. `db.commands.documents.createDocumentVersion(...)` (action = 'update')
+ *   7. `hooks.afterUpdate({ data: nextData, originalData, collectionPath, documentId, documentVersionId })`
+ *
+ * @throws {BylineError} ERR_CONFLICT if the supplied `documentVersionId` does not match the current version.
+ * @throws {BylineError} ERR_PATCH_FAILED if `applyPatches` fails.
+ */
+export declare function updateDocumentWithPatches(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    patches: DocumentPatch[];
+    /** Client-supplied version ID for optimistic concurrency. */
+    documentVersionId?: string;
+    locale?: string;
+    /**
+     * Explicit path override (typically supplied alongside patches when
+     * the admin path widget has been edited). When omitted, sticky from
+     * the previous version.
+     */
+    path?: string;
+}): Promise<UpdateDocumentWithPatchesResult>;
+/**
+ * Change a document's workflow status.
+ *
+ * Flow:
+ *   1. Fetch current document metadata
+ *   2. Validate transition via `validateStatusTransition()`
+ *   3. `hooks.beforeStatusChange({ documentId, documentVersionId, collectionPath, previousStatus, nextStatus })`
+ *   4. `db.commands.documents.setDocumentStatus(...)` — in-place mutation
+ *   5. Auto-archive: if transitioning to `'published'`, archive other published versions
+ *   6. `hooks.afterStatusChange({ documentId, documentVersionId, collectionPath, previousStatus, nextStatus })`
+ */
+export declare function changeDocumentStatus(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+    nextStatus: string;
+}): Promise<ChangeStatusResult>;
+/**
+ * Unpublish a document by archiving its published version(s).
+ *
+ * Flow:
+ *   1. `hooks.beforeUnpublish({ documentId, collectionPath })`
+ *   2. `db.commands.documents.archivePublishedVersions(...)`
+ *   3. `hooks.afterUnpublish({ documentId, collectionPath, archivedCount })`
+ */
+export declare function unpublishDocument(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+}): Promise<UnpublishResult>;
+/**
+ * Soft-delete a document.
+ *
+ * Marks all versions of the document as deleted (`is_deleted = true`). The
+ * `current_documents` view automatically filters deleted rows, so the
+ * document disappears from all list / page queries without physically
+ * removing data.
+ *
+ * When the collection has any upload-capable image/file field and
+ * `ctx.storage` is provided, every original file and persisted variant
+ * across those fields is also removed from storage after the DB
+ * soft-delete succeeds. Variant paths are read from the field value's
+ * `variants` array (no re-derivation from `upload.sizes`), so cleanup
+ * stays correct even if the size set changed between upload and delete.
+ * File cleanup failures are logged but are non-fatal.
+ *
+ * Flow:
+ *   1. Fetch current document (reconstruct when upload-capable fields exist)
+ *   2. `hooks.beforeDelete({ documentId, collectionPath })`
+ *   3. `db.commands.documents.softDeleteDocument({ document_id })`
+ *   4. Storage file + variant cleanup (skipped when no upload fields, non-fatal)
+ *   5. `hooks.afterDelete({ documentId, collectionPath })`
+ */
+export declare function deleteDocument(ctx: DocumentLifecycleContext, params: {
+    documentId: string;
+}): Promise<DeleteDocumentResult>;
+//# sourceMappingURL=document-lifecycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"document-lifecycle.d.ts","sourceRoot":"","sources":["../../src/services/document-lifecycle.ts"],"names":[],"mappings":"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"}