@byline/core 3.11.2 → 3.12.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.11.2",
+  "version": "3.12.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.11.2"
+    "@byline/auth": "3.12.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",

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

@@ -1,513 +0,0 @@
-/**
- * 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 so that internal-tooling callers (seed scripts, migration
-     * tools) continue to compile. Production write paths always supply it
-     * — `assertActorCanPerform` runs at every lifecycle entry and rejects
-     * a missing context.
-     *
-     * See docs/AUTHN-AUTHZ.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 UpdateDocumentSystemFieldsResult {
-    documentId: string;
-    /** The path actually written, or `undefined` when no path write occurred. */
-    path?: string;
-    /** Whether the advertised-locale set was rewritten this call. */
-    availableLocalesWritten: boolean;
-}
-export interface ChangeStatusResult {
-    previousStatus: string;
-    newStatus: string;
-}
-export interface UnpublishResult {
-    archivedCount: number;
-}
-export interface DeleteDocumentResult {
-    deletedVersionCount: number;
-}
-export interface RestoreVersionResult {
-    documentId: string;
-    documentVersionId: string;
-    sourceVersionId: string;
-}
-export interface CopyToLocaleResult {
-    documentId: string;
-    documentVersionId: string;
-    /** Source locale read for the copy. */
-    sourceLocale: string;
-    /** Target locale into which the source's localized leaves were written. */
-    targetLocale: string;
-    /**
-     * Number of localized field values copied from source to target. Useful
-     * for UI toasts ("Copied 4 fields from EN to FR"). A zero result means
-     * the source had no localized content to copy into the target under the
-     * chosen merge rule (e.g. `overwrite: false` and target was already
-     * fully populated).
-     */
-    fieldsUpdated: number;
-}
-export interface DeleteLocaleResult {
-    documentId: string;
-    /** The newly-created version that omits the deleted locale's content. */
-    documentVersionId: string;
-    /** The content locale that was removed. */
-    locale: string;
-}
-export interface DuplicateDocumentResult {
-    /** The newly-created document's id. */
-    documentId: string;
-    /** The newly-created version id (every duplicate starts at version 1). */
-    documentVersionId: string;
-    /** The id of the document this duplicate was cloned from. */
-    sourceDocumentId: string;
-    /**
-     * Final `path` written into `byline_document_paths` for the new document.
-     * Surfaced in the result so the UI can include it in success toasts /
-     * navigate to it directly.
-     */
-    newPath: string;
-    /**
-     * `true` when the candidate path collided with an existing row and the
-     * lifecycle retried with a short-UUID suffix. UIs can surface a hint that
-     * the auto-generated path is uglier than usual so the editor knows to
-     * adjust it via the path widget.
-     */
-    pathRetried: boolean;
-}
-/**
- * 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;
-    /**
-     * The editorial advertised-locale set (from the admin available-locales
-     * sidebar widget). Document-grain and sticky like `path`: passed straight
-     * to the storage primitive, which replaces the document's rows wholesale.
-     * `undefined` writes nothing (a new document starts with an empty set —
-     * the safe opt-in default); `[]` clears it. See docs/I18N.md.
-     */
-    availableLocales?: 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;
-    /**
-     * The editorial advertised-locale set. `undefined` leaves the existing
-     * set untouched (sticky — document-grain, like `path`); an explicit array
-     * (empty included) replaces it wholesale. Driven by the admin
-     * available-locales sidebar widget. See docs/I18N.md.
-     */
-    availableLocales?: 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;
-    /**
-     * The editorial advertised-locale set (typically supplied alongside
-     * patches when the admin available-locales widget has been edited).
-     * `undefined` leaves the existing set untouched (sticky); an explicit
-     * array replaces it wholesale. See docs/I18N.md.
-     */
-    availableLocales?: string[];
-}): Promise<UpdateDocumentWithPatchesResult>;
-/**
- * Write a document's system-managed, document-grain fields — `path` and the
- * editorial `availableLocales` set — **without** minting a new version or
- * touching workflow status.
- *
- * These fields are document-grain (they live in `byline_document_paths` and
- * `byline_document_available_locales`, keyed by logical document, sticky across
- * versions), so a workflow status change would falsely imply the edit is gated
- * behind publish. It is not: the write is immediate and applies across every
- * version. This service backs the admin path / available-locales widgets'
- * direct-write Save (the `direct-write` and `both` dirty-reason cases). The
- * public *advertised* set remains the intersection of `availableLocales` with
- * the resolved version's completeness ledger. See docs/I18N.md.
- *
- * Flow:
- *   1. `assertActorCanPerform('update')` — same auth gate as content writes.
- *   2. Fetch the document to resolve its `source_locale` anchor + current path.
- *   3. Path (when supplied): `resolvePathForUpdate` enforces the source-locale
- *      rule (translation-locale path edits are dropped with a warn); a real
- *      change is written via `updateDocumentPath`, mapping the unique-constraint
- *      violation to `ERR_PATH_CONFLICT`.
- *   4. `availableLocales` (when supplied): rewritten wholesale via
- *      `setDocumentAvailableLocales`.
- *
- * No content hooks fire — these are not content writes. Accountability for
- * these mutations is the job of the (planned) document-grain audit log.
- *
- * @throws {BylineError} ERR_NOT_FOUND if the document does not exist.
- * @throws {BylineError} ERR_PATH_CONFLICT if the path is already in use.
- */
-export declare function updateDocumentSystemFields(ctx: DocumentLifecycleContext, params: {
-    documentId: string;
-    locale?: string;
-    /**
-     * Explicit path override from the path widget. `null` / empty / omitted
-     * means "no path write" (the existing row stays sticky). A non-empty
-     * string is written when the request locale is the document's source
-     * locale; on a translation locale it is dropped with a warn.
-     */
-    path?: string | null;
-    /**
-     * The editorial advertised-locale set from the available-locales widget.
-     * `undefined` means "no advertised-locale write"; an explicit array — `[]`
-     * included — replaces the set wholesale.
-     */
-    availableLocales?: string[];
-}): Promise<UpdateDocumentSystemFieldsResult>;
-/**
- * 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>;
-/**
- * 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.
- *
- * 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>;
-/**
- * Duplicate a document, cloning all of its locales into a brand-new
- * document atomically.
- *
- * Flow:
- *   1. `assertActorCanPerform('create')` — duplicating is a create at the
- *      ability level. The source must be readable (any RBAC scoping the
- *      caller has applies via the storage read).
- *   2. Fetch the source with `locale: 'all'` so a single read carries the
- *      full multi-locale tree forward.
- *   3. Deep-clone the source fields; strip block / array-item `_id` meta
- *      so the new doc gets fresh identities.
- *   4. Append `" (copy)"` to the `useAsTitle` field's value(s).
- *   5. Derive a candidate path from the default-locale suffixed title.
- *   6. `hooks.beforeCreate({ data, collectionPath, duplicate })`.
- *   7. `db.commands.documents.createDocumentVersion(...)` with `locale:
- *      'all'`, `action: 'create'`, no `documentId` → fresh document_id.
- *      On `ERR_PATH_CONFLICT` retry once with the candidate path plus a
- *      4-char UUID suffix; bounded to two attempts, no existence
- *      pre-check, no TOCTOU race.
- *   8. `hooks.afterCreate({ data, collectionPath, documentId,
- *      documentVersionId, duplicate })`.
- *
- * The write is atomic at the storage layer — a partial duplicate is
- * structurally impossible. Editors are expected to rename both the
- * title and the system path after the operation; the UI surfaces a
- * confirmation modal that calls this out.
- */
-export declare function duplicateDocument(ctx: DocumentLifecycleContext, params: {
-    sourceDocumentId: string;
-}): Promise<DuplicateDocumentResult>;
-/**
- * Copy a document's content from one locale into another, in place on
- * the same document.
- *
- * Reads the source and target locales separately (the storage layer
- * resolves localized fields to flat single-locale shapes when given a
- * specific `resolveLocale`). A schema-aware merge walker decides, leaf
- * by leaf, whether to take the source's value or keep the target's,
- * driven by the `overwrite` flag. The merged tree is written via
- * `createDocumentVersion({ action: 'copy_to_locale', locale: target })`
- * — the existing cross-locale carry-forward in the storage primitive
- * preserves every *other* locale's rows untouched.
- *
- * Non-localized fields are never altered by this operation: they live
- * on `locale: 'all'` rows and the merge walker passes the target's
- * value through so the write does not blank them.
- *
- * Path is sticky and lives on default-locale only; this operation never
- * touches `byline_document_paths`. Status resets to the workflow
- * default — translations land as drafts.
- *
- * Flow:
- *   1. `assertActorCanPerform('update')` — same gate as a translation save.
- *   2. Reject if `sourceLocale === targetLocale`.
- *   3. Fetch source via `getDocumentById({ locale: sourceLocale })`.
- *   4. Fetch target via `getDocumentById({ locale: targetLocale })`.
- *   5. `mergeLocaleData(definition.fields, source.fields, target.fields, overwrite)`.
- *   6. `hooks.beforeUpdate({ data, originalData, collectionPath, copyToLocale })`.
- *   7. `createDocumentVersion({ documentId, action: 'copy_to_locale',
- *      locale: targetLocale, documentData, previousVersionId, status })`.
- *   8. `hooks.afterUpdate({ ..., copyToLocale })`.
- */
-export declare function copyToLocale(ctx: DocumentLifecycleContext, params: {
-    documentId: string;
-    sourceLocale: string;
-    targetLocale: string;
-    overwrite: boolean;
-}): Promise<CopyToLocaleResult>;
-/**
- * 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
- * store rows (every other locale and all non-localized `'all'` rows are
- * carried forward by the storage primitive).
- *
- * The default content locale is the document's anchor (path + source_locale)
- * and can never be removed — rejected up front. The new version lands as the
- * workflow's default status (a fresh draft), exactly like `copyToLocale`: the
- * previously-published version keeps serving — including the locale being
- * removed — until the new version is reviewed and published. The deletion is
- * recoverable: the prior version still holds the locale, so restoring it
- * brings the content back.
- *
- * Flow:
- *   1. `assertActorCanPerform('update')` — removing a translation is an edit.
- *   2. Reject `locale === defaultLocale`.
- *   3. Read the document in the target locale (validates existence; supplies
- *      `originalData` for hooks and the availability set for the presence
- *      check).
- *   4. Reject when the locale has no content to delete.
- *   5. `hooks.beforeUpdate({ …, deleteLocale: { locale } })`.
- *   6. `db.commands.documents.deleteDocumentLocale({ …, status: default })`.
- *   7. `hooks.afterUpdate({ …, deleteLocale: { locale } })`.
- */
-export declare function deleteLocale(ctx: DocumentLifecycleContext, params: {
-    documentId: string;
-    locale: string;
-}): Promise<DeleteLocaleResult>;