@byline/core 3.5.1 → 3.7.0

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

@@ -0,0 +1,37 @@
+/**
+ * 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 type { DocumentLifecycleContext } from './context.js';
+export interface DeleteDocumentResult {
+    deletedVersionCount: number;
+}
+/**
+ * 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>;

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

@@ -0,0 +1,113 @@
+/**
+ * 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 { resolveHooks } from '../../@types/index.js';
+import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { ERR_NOT_FOUND } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { getUploadFields } from '../../utils/storage-utils.js';
+import { invokeHook } from './internals.js';
+/**
+ * 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 async function deleteDocument(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteDocument' }, async () => {
+        const { db, collectionPath, definition, logger } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'delete');
+        const hooks = await resolveHooks(definition);
+        // 1. Verify the document exists.
+        //    For collections that have any upload-capable image/file field
+        //    AND a storage provider, fetch with reconstruct: true so we
+        //    can read the stored file paths (and persisted variant paths)
+        //    from the field values before the DB rows are deleted.
+        const uploadFieldNames = getUploadFields(definition).map((f) => f.name);
+        const isUploadCollection = uploadFieldNames.length > 0 && ctx.storage != null;
+        const latest = await db.queries.documents.getDocumentById({
+            collection_id: ctx.collectionId,
+            document_id: params.documentId,
+            reconstruct: isUploadCollection,
+        });
+        if (latest == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId },
+            }).log(ctx.logger);
+        }
+        // Collect storage paths for every upload-capable field on the doc:
+        // the original file plus every persisted variant. Reading the
+        // variants from the field value (rather than re-deriving from
+        // `upload.sizes`) keeps cleanup correct even when the size set
+        // changes between upload and delete.
+        const storagePathsToDelete = [];
+        if (isUploadCollection) {
+            for (const fieldName of uploadFieldNames) {
+                const fieldValue = latest?.fields?.[fieldName];
+                if (!fieldValue || typeof fieldValue !== 'object')
+                    continue;
+                if (typeof fieldValue.storagePath === 'string') {
+                    storagePathsToDelete.push(fieldValue.storagePath);
+                }
+                if (Array.isArray(fieldValue.variants)) {
+                    for (const variant of fieldValue.variants) {
+                        if (variant && typeof variant.storagePath === 'string') {
+                            storagePathsToDelete.push(variant.storagePath);
+                        }
+                    }
+                }
+            }
+        }
+        const hookCtx = {
+            documentId: params.documentId,
+            collectionPath,
+            // The current document was fetched above (reconstructed only for
+            // upload collections, but the envelope carries the locale-resolved
+            // `path` projection either way). Surface it so delete hooks can purge
+            // the specific document/URL.
+            path: latest.path ?? '',
+        };
+        // 2. beforeDelete hook.
+        await invokeHook(hooks?.beforeDelete, hookCtx);
+        // 3. Soft-delete all versions.
+        const deletedVersionCount = await db.commands.documents.softDeleteDocument({
+            document_id: params.documentId,
+        });
+        // 4. Clean up storage files. Non-fatal: logs errors but does not throw.
+        if (ctx.storage && storagePathsToDelete.length > 0) {
+            for (const storagePath of storagePathsToDelete) {
+                try {
+                    await ctx.storage.delete(storagePath);
+                }
+                catch (err) {
+                    logger.error({ err, storagePath }, 'failed to delete storage file');
+                }
+            }
+        }
+        // 5. afterDelete hook.
+        await invokeHook(hooks?.afterDelete, hookCtx);
+        return { deletedVersionCount };
+    });
+}

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

@@ -0,0 +1,60 @@
+/**
+ * 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 type { DocumentLifecycleContext } from './context.js';
+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;
+}
+/**
+ * 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>;

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

@@ -0,0 +1,219 @@
+/**
+ * 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 { resolveHooks } from '../../@types/index.js';
+import { assertActorCanPerform } from '../../auth/assert-actor-can-perform.js';
+import { ERR_NOT_FOUND } from '../../lib/errors.js';
+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';
+/**
+ * Apply the `" (copy)"` suffix to the configured `useAsTitle` field on a
+ * duplicate's data tree. Handles both shapes:
+ *
+ *   - Localized title — `fields[useAsTitle]` is `{ en: '...', fr: '...' }`,
+ *     suffix is applied to every locale's value.
+ *   - Non-localized title — `fields[useAsTitle]` is a plain string;
+ *     suffix appended once.
+ *
+ * No-op when the collection has no `useAsTitle` or the title is null /
+ * undefined; the duplicate proceeds with the source's title verbatim and
+ * the editor can rename it. Mutates the tree in place.
+ */
+function applyDuplicateTitleSuffix(definition, fields, suffix) {
+    const titleField = definition.useAsTitle;
+    if (titleField == null)
+        return;
+    const value = fields[titleField];
+    if (value == null)
+        return;
+    if (typeof value === 'string') {
+        fields[titleField] = value + suffix;
+        return;
+    }
+    if (typeof value === 'object' && !Array.isArray(value) && !(value instanceof Date)) {
+        const localized = value;
+        for (const loc of Object.keys(localized)) {
+            const v = localized[loc];
+            if (typeof v === 'string') {
+                localized[loc] = v + suffix;
+            }
+        }
+    }
+}
+/**
+ * Compute the candidate path for a duplicate.
+ *
+ * Reads the default-locale value of `definition.useAsPath` (peeling the
+ * localized-shape wrapper if present) and runs it through the existing
+ * `derivePath` helper. Falls back to `crypto.randomUUID()` when no source
+ * value is available — matches `createDocument`'s behaviour for paths
+ * that can't be slugged.
+ */
+function deriveDuplicateCandidatePath(definition, fields, defaultLocale, slugifier) {
+    const useAsPath = definition.useAsPath;
+    if (useAsPath == null) {
+        return crypto.randomUUID();
+    }
+    const raw = fields[useAsPath];
+    // Peel the localized wrapper to find the default-locale value.
+    let sourceValue = raw;
+    if (raw != null && typeof raw === 'object' && !Array.isArray(raw) && !(raw instanceof Date)) {
+        sourceValue = raw[defaultLocale];
+    }
+    return derivePath(definition, { [useAsPath]: sourceValue }, defaultLocale, slugifier);
+}
+/**
+ * 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 async function duplicateDocument(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'duplicateDocument' }, async () => {
+        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
+        const slugifier = ctx.slugifier ?? slugify;
+        const hooks = await resolveHooks(definition);
+        // 1. Read source with locale='all' — single read, full multi-locale tree.
+        const source = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.sourceDocumentId,
+            locale: 'all',
+            reconstruct: true,
+            lenient: true,
+            requestContext: ctx.requestContext,
+        });
+        if (source == null) {
+            throw ERR_NOT_FOUND({
+                message: 'source document not found',
+                details: { sourceDocumentId: params.sourceDocumentId, collectionPath },
+            }).log(ctx.logger);
+        }
+        const sourceRecord = source;
+        const sourceFields = sourceRecord.fields ?? {};
+        // 2. Deep clone — we'll mutate (suffix titles, strip meta ids).
+        const clonedFields = structuredClone(sourceFields);
+        // 3. Fresh block / array-item identities for the new doc.
+        stripMetaIdsInPlace(clonedFields);
+        // 4. Suffix titles per locale (or once if non-localized).
+        const titleSuffix = ' (copy)';
+        applyDuplicateTitleSuffix(definition, clonedFields, titleSuffix);
+        // 5. Derive candidate path from the (now suffixed) default-locale title.
+        const candidatePath = deriveDuplicateCandidatePath(definition, clonedFields, defaultLocale, slugifier);
+        // 6. beforeCreate hook with duplicate marker.
+        const duplicateMarker = { sourceDocumentId: params.sourceDocumentId };
+        await invokeHook(hooks?.beforeCreate, {
+            data: clonedFields,
+            collectionPath,
+            duplicate: duplicateMarker,
+        });
+        // 6b. Reset counter fields to freshly-allocated values. The clone
+        // currently carries the source document's counter values; without
+        // this pass, the duplicate would alias the source's facet IDs and
+        // break the "one ID per term" contract.
+        await assignCounterValues({
+            fields: definition.fields,
+            data: clonedFields,
+            counters: db.commands.counters,
+        });
+        // 7. Atomic write. Try the candidate path; on ERR_PATH_CONFLICT
+        //    retry once with a 4-char UUID suffix.
+        const defaultStatus = getDefaultStatus(definition);
+        let finalPath = candidatePath;
+        let pathRetried = false;
+        let result;
+        // Append-at-end order_key for `orderable: true` collections. Computed
+        // before the insert; the source row's order is intentionally not
+        // copied — duplicates land at the end of the list.
+        const orderKey = await maybeAppendOrderKey(ctx, collectionPath);
+        // Embed walker (no-op for multi-locale richtext leaves — see
+        // restoreDocumentVersion for the same caveat).
+        await applyRichTextEmbed(ctx, clonedFields);
+        try {
+            result = await db.commands.documents
+                .createDocumentVersion({
+                collectionId,
+                collectionVersion: ctx.collectionVersion,
+                collectionConfig: definition,
+                action: 'create',
+                documentData: clonedFields,
+                path: finalPath,
+                status: defaultStatus,
+                locale: 'all',
+                orderKey,
+            })
+                .catch((err) => rethrowPathConflict(err, finalPath, defaultLocale));
+        }
+        catch (err) {
+            if (!isPathConflictError(err)) {
+                throw err;
+            }
+            // Single retry with a short UUID suffix. crypto.randomUUID() is
+            // 36 chars; take the first 4 hex digits for a compact disambiguator.
+            const shortDisambiguator = crypto.randomUUID().slice(0, 4);
+            finalPath = `${candidatePath}-${shortDisambiguator}`;
+            pathRetried = true;
+            ctx.logger?.info({ candidatePath, retryPath: finalPath, sourceDocumentId: params.sourceDocumentId }, 'duplicateDocument: candidate path collided, retrying with short-UUID suffix');
+            result = await db.commands.documents
+                .createDocumentVersion({
+                collectionId,
+                collectionVersion: ctx.collectionVersion,
+                collectionConfig: definition,
+                action: 'create',
+                documentData: clonedFields,
+                path: finalPath,
+                status: defaultStatus,
+                locale: 'all',
+                orderKey,
+            })
+                .catch((retryErr) => rethrowPathConflict(retryErr, finalPath, defaultLocale));
+        }
+        const newDocumentId = extractDocumentId(result.document);
+        const newDocumentVersionId = extractVersionId(result.document);
+        // 8. afterCreate hook with duplicate marker.
+        await invokeHook(hooks?.afterCreate, {
+            data: clonedFields,
+            collectionPath,
+            documentId: newDocumentId,
+            documentVersionId: newDocumentVersionId,
+            path: finalPath,
+            duplicate: duplicateMarker,
+        });
+        return {
+            documentId: newDocumentId,
+            documentVersionId: newDocumentVersionId,
+            sourceDocumentId: params.sourceDocumentId,
+            newPath: finalPath,
+            pathRetried,
+        };
+    });
+}

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ *
+ * One module per operation; shared helpers live in `internals.ts` (not
+ * re-exported here — the public surface is exactly this barrel).
+ */
+export { copyToLocale } from './copy-to-locale.js';
+export { createDocument } from './create.js';
+export { deleteDocument } from './delete.js';
+export { deleteLocale } from './delete-locale.js';
+export { duplicateDocument } from './duplicate.js';
+export { restoreDocumentVersion } from './restore.js';
+export { changeDocumentStatus, unpublishDocument } from './status.js';
+export { updateDocumentSystemFields } from './system-fields.js';
+export { updateDocument, updateDocumentWithPatches } from './update.js';
+export type { DocumentLifecycleContext } from './context.js';
+export type { CopyToLocaleResult } from './copy-to-locale.js';
+export type { CreateDocumentResult } from './create.js';
+export type { DeleteDocumentResult } from './delete.js';
+export type { DeleteLocaleResult } from './delete-locale.js';
+export type { DuplicateDocumentResult } from './duplicate.js';
+export type { RestoreVersionResult } from './restore.js';
+export type { ChangeStatusResult, UnpublishResult } from './status.js';
+export type { UpdateDocumentSystemFieldsResult } from './system-fields.js';
+export type { UpdateDocumentResult, UpdateDocumentWithPatchesResult } from './update.js';

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

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ *
+ * One module per operation; shared helpers live in `internals.ts` (not
+ * re-exported here — the public surface is exactly this barrel).
+ */
+export { copyToLocale } from './copy-to-locale.js';
+export { createDocument } from './create.js';
+export { deleteDocument } from './delete.js';
+export { deleteLocale } from './delete-locale.js';
+export { duplicateDocument } from './duplicate.js';
+export { restoreDocumentVersion } from './restore.js';
+export { changeDocumentStatus, unpublishDocument } from './status.js';
+export { updateDocumentSystemFields } from './system-fields.js';
+export { updateDocument, updateDocumentWithPatches } from './update.js';

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

@@ -0,0 +1,113 @@
+/**
+ * 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
+ */
+/**
+ * Helpers shared by the per-operation lifecycle modules. Internal to the
+ * `document-lifecycle/` directory — nothing here is re-exported through
+ * the barrel (`index.ts`), so the package's public surface is unchanged
+ * by the per-operation split.
+ */
+import { type CollectionDefinition, type CollectionHookSlot } from '../../@types/index.js';
+import type { BylineLogger } from '../../lib/logger.js';
+import type { SlugifierFn } from '../../utils/slugify.js';
+import type { DocumentLifecycleContext } from './context.js';
+/**
+ * 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
+ * sequentially in order.
+ */
+export declare function invokeHook<Ctx>(hook: CollectionHookSlot<Ctx> | undefined, ctx: Ctx): Promise<void>;
+/**
+ * Run the registered richtext embed adapter across every rich-text leaf
+ * in the outgoing document data. Mirror of the read-side
+ * `populateRichTextFields` — fires once per write, mutates `data` in
+ * place. Per-leaf errors are logged and swallowed by `embedRichTextFields`
+ * itself (branch C); document-level errors propagate.
+ *
+ * No-op when no embed adapter is registered. The bootstrap validator
+ * (step 7 of the link-refactor strategy) will eventually fail-fast for
+ * collections that declare `embedRelationsOnSave: true` without a
+ * registered adapter; until then a missing adapter is silent and writes
+ * proceed unmodified.
+ */
+export declare function applyRichTextEmbed(ctx: DocumentLifecycleContext, data: Record<string, any>): Promise<void>;
+/**
+ * For collections with `orderable: true` on their schema definition, compute
+ * an append-at-end fractional-index key for a newly-inserted document.
+ * Returns `undefined` when the collection hasn't opted in (or has no
+ * definition registered, e.g. in unit-test environments), so the storage row
+ * gets `order_key = NULL` and the existing "no ordering" behavior holds.
+ */
+export declare function maybeAppendOrderKey(ctx: DocumentLifecycleContext, collectionPath: string): Promise<string | undefined>;
+/** Extract `id` from the document object returned by `createDocumentVersion`. */
+export declare function extractVersionId(document: any): string;
+/** Extract the logical document id from the document object returned by `createDocumentVersion`. */
+export declare function extractDocumentId(document: any): string;
+/**
+ * Detect a Postgres unique-constraint violation on
+ * `byline_document_paths(collection_id, locale, path)` and translate it
+ * to `ERR_PATH_CONFLICT`. Any other error is rethrown unchanged.
+ *
+ * The Postgres SQLSTATE for unique violations is `23505`. Drivers carry
+ * the constraint name on the error object (`constraint`); matching by
+ * name keeps this targeted to the path constraint and avoids spuriously
+ * rebranding unrelated unique violations as path conflicts.
+ *
+ * Drizzle wraps the underlying pg error in `DrizzleQueryError` with the
+ * original attached as `cause`, so we walk a short cause chain to find
+ * the carried `code` / `constraint`.
+ */
+export declare function rethrowPathConflict(err: unknown, path: string, locale: string): never;
+/**
+ * Detect whether an error is the `ERR_PATH_CONFLICT` raised by
+ * `rethrowPathConflict`. Used by `duplicateDocument`'s retry logic to
+ * keep the conflict-handling path separate from genuine errors.
+ */
+export declare function isPathConflictError(err: unknown): boolean;
+/**
+ * Resolve the path argument the storage primitive should receive on an
+ * update operation. Phase 1 only writes path rows under the default
+ * content locale; on translation saves a supplied path is dropped with
+ * a `logger.warn`, leaving the existing default-locale row untouched.
+ *
+ * Returns `undefined` to signal the storage primitive should skip the
+ * path write entirely (no upsert).
+ */
+export declare function resolvePathForUpdate(args: {
+    explicitPath: string | null;
+    currentPath: string | undefined;
+    requestLocale: string;
+    sourceLocale: string;
+    documentId: string;
+    logger?: BylineLogger;
+}): string | undefined;
+/**
+ * Derive the `path` value written into `byline_document_paths` at
+ * create time.
+ *
+ *   1. `definition.useAsPath` set → slugify the named source field's value
+ *      in the default content locale.
+ *   2. Source field absent / empty → fall back to `crypto.randomUUID()`.
+ *
+ * Caller passes explicit overrides separately; this helper only handles
+ * the auto-derivation cascade.
+ */
+export declare function derivePath(definition: CollectionDefinition, data: Record<string, any>, defaultLocale: string, slugifier: SlugifierFn): string;
+/**
+ * Strip the synthetic `_id` / `_type` meta keys from every block and
+ * array-item node in a reconstructed document tree.
+ *
+ * Reconstructed `locale: 'all'` trees carry stable `_id` values for
+ * blocks and array items (see CLAUDE.md → "Block/array items carry a
+ * stable `_id`"). For a *duplicate*, the new document is conceptually a
+ * fresh entity — its blocks should get fresh meta ids rather than
+ * inheriting the source's. Mutates the tree in place.
+ *
+ * Distinct from `restoreDocumentVersion`, which deliberately preserves
+ * `_id`s so block identity is stable across history.
+ */
+export declare function stripMetaIdsInPlace(value: unknown): void;