@byline/core 4.15.0 → 4.17.0

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

@@ -14,8 +14,8 @@ import { normaliseDateFields } from '../../utils/normalise-dates.js';
 import { getDefaultStatus } from '../../workflow/workflow.js';
 import { assignCounterValues } from '../assign-counter-values.js';
 import { normalizeNumericFields } from '../normalize-numeric-fields.js';
-import { actorId, applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
-import { commitContentVersionWithScheduleSuspension } from './publish-schedule-consistency.js';
+import { applyRichTextEmbed, extractDocumentId, extractVersionId, invokeHook, resolvePathForUpdate, rethrowPathConflict, } from './internals.js';
+import { persistExistingDocumentVersion } from './persistence.js';
 import { selfHealTreePlacement } from './tree.js';
 /**
  * Update a document via full replacement (PUT semantics).
@@ -33,7 +33,7 @@ import { selfHealTreePlacement } from './tree.js';
 export async function updateDocument(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocument' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        assertActorCanPerform(ctx.requestContext, definition, 'update');
         const hooks = await resolveHooks(definition);
         const data = params.data;
         // Fetch the real original so hooks get accurate originalData (fixes the
@@ -77,23 +77,15 @@ export async function updateDocument(ctx, params) {
             logger: ctx.logger,
         });
         await applyRichTextEmbed(ctx, data);
-        const result = await commitContentVersionWithScheduleSuspension({
-            ctx,
+        const result = await persistExistingDocumentVersion(ctx, {
             documentId: params.documentId,
-            write: () => db.commands.documents.createDocumentVersion({
-                documentId: params.documentId,
-                collectionId,
-                collectionVersion: ctx.collectionVersion,
-                collectionConfig: definition,
-                action: 'update',
-                documentData: data,
-                path: pathForCommand,
-                availableLocales: params.availableLocales,
-                status: defaultStatus,
-                locale: requestLocale,
-                previousVersionId: originalData.document_version_id,
-                createdBy: actorId(ctx),
-            }),
+            action: 'update',
+            documentData: data,
+            path: pathForCommand,
+            availableLocales: params.availableLocales,
+            status: defaultStatus,
+            locale: requestLocale,
+            previousVersionId: originalData.document_version_id,
         }).catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', sourceLocale, 'update'));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);
@@ -129,7 +121,7 @@ export async function updateDocument(ctx, params) {
 export async function updateDocumentWithPatches(ctx, params) {
     return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocumentWithPatches' }, async () => {
         const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        assertActorCanPerform(ctx.requestContext, definition, 'update');
         const hooks = await resolveHooks(definition);
         // 1. Fetch current document.
         const latest = await db.queries.documents.getDocumentById({
@@ -198,23 +190,15 @@ export async function updateDocumentWithPatches(ctx, params) {
             logger: ctx.logger,
         });
         await applyRichTextEmbed(ctx, nextData);
-        const result = await commitContentVersionWithScheduleSuspension({
-            ctx,
+        const result = await persistExistingDocumentVersion(ctx, {
             documentId: params.documentId,
-            write: () => db.commands.documents.createDocumentVersion({
-                documentId: params.documentId,
-                collectionId,
-                collectionVersion: ctx.collectionVersion,
-                collectionConfig: definition,
-                action: 'update',
-                documentData: nextData,
-                path: pathForCommand,
-                availableLocales: params.availableLocales,
-                status: defaultStatus,
-                locale: requestLocale,
-                previousVersionId: originalData.document_version_id,
-                createdBy: actorId(ctx),
-            }),
+            action: 'update',
+            documentData: nextData,
+            path: pathForCommand,
+            availableLocales: params.availableLocales,
+            status: defaultStatus,
+            locale: requestLocale,
+            previousVersionId: originalData.document_version_id,
         }).catch((err) => rethrowPathConflict(db, err, pathForCommand ?? '', sourceLocale, 'update'));
         const documentId = extractDocumentId(result.document) || params.documentId;
         const documentVersionId = extractVersionId(result.document);

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

@@ -86,6 +86,9 @@ function createMockDb() {
     // records the calls so write-point tests can assert the audit rows emitted.
     const auditAppend = vi.fn().mockResolvedValue({ id: 'audit-1' });
     const withTransaction = vi.fn(async (fn) => fn());
+    const fail = () => {
+        throw new Error('unexpected singleton mapping call');
+    };
     // Fake classifier mirroring db-postgres's real one closely enough for
     // rethrowPathConflict's consumption of the seam: a pg-shaped 23505 with a
     // constraint name classifies as a unique violation; anything else is
@@ -146,6 +149,11 @@ function createMockDb() {
                 nextScopedCounterValue: vi.fn(),
             },
             audit: { append: auditAppend },
+            singletons: {
+                lockSlot: vi.fn(fail),
+                setMapping: vi.fn(fail),
+                clearMapping: vi.fn(fail),
+            },
         },
         withTransaction: withTransaction,
         queries: {
@@ -190,6 +198,7 @@ function createMockDb() {
                     meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
                 })),
             },
+            singletons: { getMappedDocumentId: vi.fn(fail) },
         },
     };
     return {
@@ -366,6 +375,32 @@ describe('Document lifecycle service', () => {
                 price: '12.5',
             });
         });
+        it('allocates counters after beforeCreate and before persistence', async () => {
+            const callOrder = [];
+            const { db, createDocumentVersion } = createMockDb();
+            const nextCounterValue = db.commands.counters.nextCounterValue;
+            nextCounterValue.mockImplementation(async () => {
+                callOrder.push('counter');
+                return 42;
+            });
+            createDocumentVersion.mockImplementation(async () => {
+                callOrder.push('persist');
+                return { document: { id: 'ver-1', document_id: 'doc-1' }, fieldCount: 1 };
+            });
+            const definition = {
+                ...minimalCollection,
+                fields: [{ name: 'serial', type: 'counter', group: 'article-serials' }],
+                hooks: {
+                    beforeCreate: vi.fn(({ data }) => {
+                        callOrder.push('before');
+                        data.serial = 999;
+                    }),
+                },
+            };
+            await createDocument(buildCtx(db, definition), { data: {} });
+            expect(callOrder).toEqual(['before', 'counter', 'persist']);
+            expect(createDocumentVersion.mock.calls[0]?.[0].documentData.serial).toBe(42);
+        });
         it('derives path from useAsPath source field via the slugifier', async () => {
             const { db, createDocumentVersion } = createMockDb();
             const definition = { ...minimalCollection, useAsPath: 'title' };

package/dist/services/field-upload.d.ts

@@ -77,7 +77,7 @@ export interface FieldUploadContext {
     /**
      * Request-scoped auth context. Forwarded to the internal
      * `DocumentLifecycleContext` when an upload creates a document, and
-     * consulted directly at the upload entry for the `create` ability
+     * consulted directly at the upload entry for the kind-aware write ability
      * check. Required at the field-level upload boundary so `beforeStore` /
      * `afterStore` hooks can branch on `actor`.
      */

package/dist/services/field-upload.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { resolveUploadHooks } from '../@types/index.js';
+import { isSingleton, resolveUploadHooks } from '../@types/index.js';
 import { assertActorCanPerform } from '../auth/assert-actor-can-perform.js';
 import { ERR_DATABASE, ERR_STORAGE, ERR_VALIDATION } from '../lib/errors.js';
 import { withLogContext } from '../lib/logger.js';
@@ -123,10 +123,25 @@ function posixBasename(storagePath) {
 export async function uploadField(ctx, params) {
     return withLogContext({ domain: 'services', module: 'upload', function: 'uploadField' }, async () => {
         const { definition, collectionPath, storage, db, collectionId, logger, imageProcessor, fieldName, } = ctx;
-        // Upload is effectively a write under collection scope — enforce
-        // the `create` ability even when `shouldCreateDocument: false` so
-        // anonymous callers cannot push bytes into storage.
-        assertActorCanPerform(ctx.requestContext, collectionPath, 'create');
+        const { buffer, originalFilename, mimeType, fileSize, fields = {}, shouldCreateDocument = true, locale, } = params;
+        // Upload is a write even when no document is created. Preserve the
+        // anti-abuse auth gate while selecting the verb from the resource kind.
+        // A singleton's document cardinality belongs exclusively to
+        // updateSingleton, so reject the collection-only create branch before
+        // resolving hooks or writing any bytes.
+        if (isSingleton(definition)) {
+            assertActorCanPerform(ctx.requestContext, definition, 'update');
+            if (shouldCreateDocument) {
+                throw ERR_VALIDATION({
+                    message: `Cannot create a document while uploading to singleton '${collectionPath}'. ` +
+                        'Upload the field only and persist it through updateSingleton().',
+                    details: { collectionPath, fieldName },
+                }, uploadField).log(logger);
+            }
+        }
+        else {
+            assertActorCanPerform(ctx.requestContext, definition, 'create');
+        }
         const field = findUploadField(definition.fields, fieldName);
         if (!field) {
             throw ERR_VALIDATION({
@@ -143,7 +158,6 @@ export async function uploadField(ctx, params) {
                 details: { collectionPath, fieldName },
             }, uploadField).log(logger);
         }
-        const { buffer, originalFilename, mimeType, fileSize, fields = {}, shouldCreateDocument = true, locale, } = params;
         // -- Validation runs FIRST. Hooks never see a file that's about to
         //    be rejected.
         if (upload.mimeTypes && upload.mimeTypes.length > 0) {

package/dist/services/field-upload.test.node.js

@@ -5,7 +5,7 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { createSuperAdminContext } from '@byline/auth';
+import { AdminAuth, createRequestContext, createSuperAdminContext } from '@byline/auth';
 import { describe, expect, it, vi } from 'vitest';
 import { commitHookAttachment, prepareHookAttachment } from '../config/attach-hooks.js';
 import { BylineError, ErrorCodes } from '../lib/errors.js';
@@ -28,6 +28,12 @@ const uploadCollection = {
         { name: 'caption', label: 'Caption', type: 'textArea', optional: true },
     ],
 };
+const uploadSingleton = {
+    path: 'site-settings',
+    label: 'Site settings',
+    singleton: true,
+    fields: structuredClone(uploadCollection.fields),
+};
 function withFieldUpload(collection, fieldName, patch) {
     return {
         ...collection,
@@ -41,6 +47,9 @@ function withFieldUpload(collection, fieldName, patch) {
     };
 }
 function createMockDb() {
+    const fail = () => {
+        throw new Error('unexpected singleton mapping call');
+    };
     const createDocumentVersion = vi.fn().mockResolvedValue({
         document: { id: 'ver-1', document_id: 'doc-1' },
         fieldCount: 2,
@@ -82,6 +91,11 @@ function createMockDb() {
                 nextScopedCounterValue: vi.fn(),
             },
             audit: { append: vi.fn(async () => ({ id: 'audit-1' })) },
+            singletons: {
+                lockSlot: vi.fn(fail),
+                setMapping: vi.fn(fail),
+                clearMapping: vi.fn(fail),
+            },
         },
         queries: {
             collections: {
@@ -122,25 +136,32 @@ function createMockDb() {
                     meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
                 })),
             },
+            singletons: { getMappedDocumentId: vi.fn(fail) },
         },
         withTransaction: async (fn) => fn(),
     };
     return { db, createDocumentVersion };
 }
 function createMockStorage() {
-    const upload = vi.fn().mockResolvedValue({
-        storageProvider: 'local',
-        storagePath: 'media/original.png',
-        storageUrl: '/uploads/media/original.png',
+    const storedPaths = new Set();
+    const upload = vi.fn().mockImplementation(async () => {
+        storedPaths.add('media/original.png');
+        return {
+            storageProvider: 'local',
+            storagePath: 'media/original.png',
+            storageUrl: '/uploads/media/original.png',
+        };
+    });
+    const del = vi.fn().mockImplementation(async (storagePath) => {
+        storedPaths.delete(storagePath);
     });
-    const del = vi.fn().mockResolvedValue(undefined);
     const storage = {
         providerName: 'local',
         upload,
         delete: del,
         getUrl: vi.fn((storagePath) => `/uploads/${storagePath}`),
     };
-    return { storage, upload, del };
+    return { storage, upload, del, storedPaths };
 }
 const noopLogger = {
     log: vi.fn(),
@@ -170,7 +191,7 @@ function createImageProcessor(overrides) {
 }
 function buildCtx(overrides) {
     const { db, createDocumentVersion } = createMockDb();
-    const { storage, upload, del } = createMockStorage();
+    const { storage, upload, del, storedPaths } = createMockStorage();
     const imageProcessor = createImageProcessor();
     const ctx = {
         db,
@@ -186,9 +207,104 @@ function buildCtx(overrides) {
         requestContext: createSuperAdminContext({ id: 'test-super-admin' }),
         ...overrides,
     };
-    return { ctx, createDocumentVersion, upload, del, imageProcessor };
+    return { ctx, createDocumentVersion, upload, del, storedPaths, imageProcessor };
 }
 describe('uploadField service', () => {
+    it('authorizes a singleton field-only upload with its update ability', async () => {
+        const { ctx, upload } = buildCtx({
+            definition: uploadSingleton,
+            collectionPath: uploadSingleton.path,
+            requestContext: createRequestContext({
+                actor: new AdminAuth({
+                    id: 'settings-editor',
+                    abilities: ['singletons.site-settings.update'],
+                }),
+            }),
+        });
+        await expect(uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        })).resolves.toMatchObject({ storedFile: { filename: 'hero.png' } });
+        expect(upload).toHaveBeenCalledOnce();
+    });
+    it('rejects an anonymous singleton upload before writing bytes', async () => {
+        const { ctx, upload, storedPaths } = buildCtx({
+            definition: uploadSingleton,
+            collectionPath: uploadSingleton.path,
+            requestContext: createRequestContext({ actor: null, readMode: 'published' }),
+        });
+        await expect(uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        })).rejects.toMatchObject({ code: 'ERR_UNAUTHENTICATED' });
+        expect(upload).not.toHaveBeenCalled();
+        expect(storedPaths.size).toBe(0);
+    });
+    it('rejects singleton document creation before hooks, storage, or variants', async () => {
+        const beforeStore = vi.fn();
+        const definition = withFieldUpload(uploadSingleton, 'image', (field) => {
+            field.upload.hooks = { beforeStore };
+        });
+        const { ctx, upload, storedPaths, imageProcessor } = buildCtx({
+            definition,
+            collectionPath: definition.path,
+            requestContext: createRequestContext({
+                actor: new AdminAuth({
+                    id: 'settings-editor',
+                    abilities: ['singletons.site-settings.update'],
+                }),
+            }),
+        });
+        await expect(uploadField(ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: true,
+        })).rejects.toMatchObject({
+            code: ErrorCodes.VALIDATION,
+            message: expect.stringMatching(/singleton 'site-settings'.*updateSingleton/),
+        });
+        expect(beforeStore).not.toHaveBeenCalled();
+        expect(upload).not.toHaveBeenCalled();
+        expect(imageProcessor.extractMeta).not.toHaveBeenCalled();
+        expect(imageProcessor.generateVariants).not.toHaveBeenCalled();
+        expect(storedPaths.size).toBe(0);
+    });
+    it('keeps collection uploads gated on the create ability', async () => {
+        const denied = buildCtx({
+            requestContext: createRequestContext({
+                actor: new AdminAuth({ id: 'media-editor', abilities: ['collections.media.update'] }),
+            }),
+        });
+        await expect(uploadField(denied.ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        })).rejects.toMatchObject({ code: 'ERR_FORBIDDEN' });
+        expect(denied.upload).not.toHaveBeenCalled();
+        const allowed = buildCtx({
+            requestContext: createRequestContext({
+                actor: new AdminAuth({ id: 'media-creator', abilities: ['collections.media.create'] }),
+            }),
+        });
+        await expect(uploadField(allowed.ctx, {
+            buffer: Buffer.from('png'),
+            originalFilename: 'hero.png',
+            mimeType: 'image/png',
+            fileSize: 3,
+            shouldCreateDocument: false,
+        })).resolves.toBeDefined();
+        expect(allowed.upload).toHaveBeenCalledOnce();
+    });
     it('fires registry hooks for a nested array instance selected by its unique upload leaf', async () => {
         const beforeStore = vi.fn();
         const publicationFile = {

package/dist/services/index.d.ts

@@ -14,5 +14,6 @@ export { type CycleRelationValue, createReadContext, type PopulatedRelationValue
 export { buildRelationSummaryPopulateMap, type RelationTargetResolver, resolveRelationProjection, } from './relation-projection.js';
 export { type EmbedRichTextFieldsOptions, embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';
 export { collectRichTextLeaves, createRichTextDocumentReader, type PopulateRichTextFieldsOptions, populateRichTextFields, type RichTextAdapterPresence, type RichTextLeaf, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export * from './singleton-lifecycle/index.js';
 export { type SearchProviderPresence, validateSearchConfig, } from './validate-search-config.js';
 export { type FieldLeaf, walkFieldTree } from './walk-field-tree.js';

package/dist/services/index.js

@@ -15,5 +15,6 @@ export { createReadContext, populateDocuments, resolveIdentityField, } from './p
 export { buildRelationSummaryPopulateMap, resolveRelationProjection, } from './relation-projection.js';
 export { embedRichTextFields, resolveEmbedOnSave, } from './richtext-embed.js';
 export { collectRichTextLeaves, createRichTextDocumentReader, populateRichTextFields, resolvePopulateOnRead, validateRichTextFieldFlags, } from './richtext-populate.js';
+export * from './singleton-lifecycle/index.js';
 export { validateSearchConfig, } from './validate-search-config.js';
 export { walkFieldTree } from './walk-field-tree.js';

package/dist/services/populate.js

@@ -219,7 +219,7 @@ export async function populateDocuments(opts) {
             // target collection before any adapter access; unresolved target schemas
             // remain unresolved rather than bypassing the collection gate.
             if (opts.requestContext && targetDef) {
-                assertActorCanPerform(opts.requestContext, targetDef.path, 'read');
+                assertActorCanPerform(opts.requestContext, targetDef, 'read');
             }
             // Only fetch IDs we haven't materialised earlier in this request.
             const idsToFetch = Array.from(new Set(leaves

package/dist/services/populate.test.node.js

@@ -129,6 +129,9 @@ function populatedEnvelope(collectionId, documentId, document) {
  * `getCollectionById(id)` to resolve them to a path.
  */
 function makeMockAdapter(store = {}, pathByCollectionId = {}) {
+    const fail = () => {
+        throw new Error('unexpected singleton mapping call');
+    };
     const getDocumentsByDocumentIds = vi.fn(async (params) => {
         const bucket = store[params.collection_id] ?? {};
         return params.document_ids.map((id) => bucket[id]).filter((d) => d != null);
@@ -170,6 +173,11 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 nextScopedCounterValue: vi.fn(),
             },
             audit: { append: vi.fn(async () => ({ id: 'audit-1' })) },
+            singletons: {
+                lockSlot: vi.fn(fail),
+                setMapping: vi.fn(fail),
+                clearMapping: vi.fn(fail),
+            },
         },
         queries: {
             collections: {
@@ -210,6 +218,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                     meta: { total: 0, page: 1, pageSize: 20, totalPages: 0 },
                 })),
             },
+            singletons: { getMappedDocumentId: vi.fn(fail) },
         },
         withTransaction: async (fn) => fn(),
     };

package/dist/services/richtext-populate.js

@@ -87,7 +87,7 @@ export function createRichTextDocumentReader(options) {
                 details: { collectionPath },
             });
         }
-        assertActorCanPerform(requestContext, collectionPath, 'read');
+        assertActorCanPerform(requestContext, definition, 'read');
         let filters;
         if (!bypassBeforeRead) {
             filters = await compileBeforeReadFilters({

package/dist/services/singleton-lifecycle/copy-to-locale.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 '../document-lifecycle/context.js';
+import type { SingletonSaveResult } from './internals.js';
+export interface CopySingletonToLocaleParams {
+    sourceLocale: string;
+    targetLocale: string;
+    overwrite: boolean;
+}
+/** Copy localized singleton fields to another locale on the mapped document. */
+export declare function copySingletonToLocale(ctx: DocumentLifecycleContext, params: CopySingletonToLocaleParams): Promise<SingletonSaveResult>;

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

@@ -0,0 +1,100 @@
+/**
+ * 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 { ERR_NOT_FOUND, ERR_VALIDATION } from '../../lib/errors.js';
+import { withLogContext } from '../../lib/logger.js';
+import { getDefaultStatus } from '../../workflow/workflow.js';
+import { applyRichTextEmbed } from '../document-lifecycle/internals.js';
+import { mergeLocaleData } from '../document-lifecycle/merge-locale-data.js';
+import { persistExistingDocumentVersion } from '../document-lifecycle/persistence.js';
+import { authorizeSingletonUpdate, commitSingletonSave } from './internals.js';
+/** Copy localized singleton fields to another locale on the mapped document. */
+export async function copySingletonToLocale(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'singleton-lifecycle', function: 'copySingletonToLocale' }, async () => {
+        const definition = authorizeSingletonUpdate(ctx);
+        if (params.sourceLocale === params.targetLocale) {
+            throw ERR_VALIDATION({
+                message: 'sourceLocale and targetLocale must differ',
+                details: { sourceLocale: params.sourceLocale, targetLocale: params.targetLocale },
+            }).log(ctx.logger);
+        }
+        return commitSingletonSave({
+            ctx,
+            definition,
+            operation: { type: 'copyToLocale', ...params },
+            prepare: async (slot) => {
+                if (slot.documentId == null || slot.currentVersion == null) {
+                    throw ERR_NOT_FOUND({
+                        message: `singleton '${ctx.collectionPath}' has not been saved`,
+                        details: { singletonPath: ctx.collectionPath },
+                    }).log(ctx.logger);
+                }
+                const source = await ctx.db.queries.documents.getDocumentById({
+                    collection_id: ctx.collectionId,
+                    document_id: slot.documentId,
+                    locale: params.sourceLocale,
+                    reconstruct: true,
+                    lenient: true,
+                    onMissingLocale: 'omit',
+                    requestContext: ctx.requestContext,
+                });
+                if (source == null) {
+                    throw ERR_NOT_FOUND({
+                        message: 'singleton not found in source locale',
+                        details: { singletonPath: ctx.collectionPath, sourceLocale: params.sourceLocale },
+                    }).log(ctx.logger);
+                }
+                const existingTarget = await ctx.db.queries.documents.getDocumentById({
+                    collection_id: ctx.collectionId,
+                    document_id: slot.documentId,
+                    locale: params.targetLocale,
+                    reconstruct: true,
+                    lenient: true,
+                    onMissingLocale: 'omit',
+                    requestContext: ctx.requestContext,
+                });
+                const target = existingTarget ??
+                    (await ctx.db.queries.documents.getDocumentById({
+                        collection_id: ctx.collectionId,
+                        document_id: slot.documentId,
+                        locale: params.targetLocale,
+                        reconstruct: true,
+                        lenient: true,
+                        requestContext: ctx.requestContext,
+                    }));
+                if (target == null) {
+                    throw ERR_NOT_FOUND({
+                        message: 'mapped singleton document not found',
+                        details: { singletonPath: ctx.collectionPath, documentId: slot.documentId },
+                    }).log(ctx.logger);
+                }
+                const sourceFields = source.fields ?? {};
+                const targetFields = target.fields ?? {};
+                const originalData = existingTarget == null
+                    ? null
+                    : (existingTarget.fields ?? {});
+                const merged = mergeLocaleData(definition.fields, sourceFields, targetFields, params.overwrite);
+                return {
+                    data: merged.data,
+                    originalData,
+                    locale: params.targetLocale,
+                    write: async () => {
+                        await applyRichTextEmbed(ctx, merged.data);
+                        return persistExistingDocumentVersion(ctx, {
+                            documentId: slot.documentId,
+                            action: 'copy_to_locale',
+                            documentData: merged.data,
+                            status: getDefaultStatus(definition),
+                            locale: params.targetLocale,
+                            previousVersionId: slot.currentVersion?.document_version_id,
+                        });
+                    },
+                };
+            },
+        });
+    });
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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
+ */
+export { copySingletonToLocale } from './copy-to-locale.js';
+export { resolveSingletonDocumentId } from './internals.js';
+export { restoreSingletonVersion } from './restore.js';
+export { updateSingleton } from './update.js';
+export type { CopySingletonToLocaleParams } from './copy-to-locale.js';
+export type { SingletonSaveResult } from './internals.js';
+export type { UpdateSingletonParams } from './update.js';

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

@@ -0,0 +1,11 @@
+/**
+ * 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
+ */
+export { copySingletonToLocale } from './copy-to-locale.js';
+export { resolveSingletonDocumentId } from './internals.js';
+export { restoreSingletonVersion } from './restore.js';
+export { updateSingleton } from './update.js';