@byline/core 3.2.1 → 3.3.0

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

@@ -340,6 +340,34 @@ export interface IDocumentCommands {
         document: any;
         fieldCount: number;
     }>;
+    /**
+     * Standalone, non-versioned write of a document's URL path
+     * (`byline_document_paths`). Edits the document-grain, sticky path row
+     * in-place **without** minting a new version or touching workflow status —
+     * the change is immediate and applies across every version. Backs the admin
+     * path widget's direct-write Save. The unique constraint on
+     * `(collection_id, locale, path)` may surface as `ERR_PATH_CONFLICT` from the
+     * lifecycle layer. See `docs/I18N.md`.
+     */
+    updateDocumentPath(params: {
+        documentId: string;
+        collectionId: string;
+        locale: string;
+        path: string;
+    }): Promise<void>;
+    /**
+     * Standalone, non-versioned write of a document's editorial advertised-locale
+     * set (`byline_document_available_locales`). Replaces the document-grain set
+     * wholesale **without** minting a new version or touching workflow status —
+     * the change is immediate and applies across every version. `[]` clears it.
+     * Backs the admin available-locales widget's direct-write Save. See
+     * `docs/I18N.md`.
+     */
+    setDocumentAvailableLocales(params: {
+        documentId: string;
+        collectionId: string;
+        availableLocales: string[];
+    }): Promise<void>;
     /**
      * Mutate the status on an existing document version row.
      *

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

@@ -39,6 +39,8 @@ function createMockDb(options) {
             collections: { create, update, delete: vi.fn(fail) },
             documents: {
                 createDocumentVersion: vi.fn(fail),
+                updateDocumentPath: vi.fn(fail),
+                setDocumentAvailableLocales: vi.fn(fail),
                 setDocumentStatus: vi.fn(fail),
                 archivePublishedVersions: vi.fn(fail),
                 softDeleteDocument: vi.fn(fail),
@@ -182,6 +184,8 @@ describe('ensureCollections', () => {
                 collections: { create, update, delete: vi.fn() },
                 documents: {
                     createDocumentVersion: vi.fn(),
+                    updateDocumentPath: vi.fn(),
+                    setDocumentAvailableLocales: vi.fn(),
                     setDocumentStatus: vi.fn(),
                     archivePublishedVersions: vi.fn(),
                     softDeleteDocument: vi.fn(),

package/dist/services/discover-counter-groups.test.node.js

@@ -24,6 +24,8 @@ function makeAdapter(options) {
             collections: { create: vi.fn(fail), update: vi.fn(fail), delete: vi.fn(fail) },
             documents: {
                 createDocumentVersion: vi.fn(fail),
+                updateDocumentPath: vi.fn(fail),
+                setDocumentAvailableLocales: vi.fn(fail),
                 setDocumentStatus: vi.fn(fail),
                 archivePublishedVersions: vi.fn(fail),
                 softDeleteDocument: vi.fn(fail),

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

@@ -104,6 +104,13 @@ 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;
@@ -263,6 +270,53 @@ export declare function updateDocumentWithPatches(ctx: DocumentLifecycleContext,
      */
     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.
  *

package/dist/services/document-lifecycle.js

@@ -460,6 +460,95 @@ export async function updateDocumentWithPatches(ctx, params) {
         return { documentId, documentVersionId };
     });
 }
+/**
+ * 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 async function updateDocumentSystemFields(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'updateDocumentSystemFields' }, async () => {
+        const { db, collectionId, collectionPath, defaultLocale } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        const requestLocale = params.locale ?? defaultLocale;
+        // Resolve the document's source-locale anchor + current path. Both feed
+        // the path source-locale guard below; the fetch also asserts existence.
+        const latest = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.documentId,
+            locale: requestLocale,
+            reconstruct: true,
+        });
+        if (latest == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId },
+            }).log(ctx.logger);
+        }
+        const originalData = latest;
+        const sourceLocale = originalData.source_locale ?? defaultLocale;
+        // Path: honour the same source-locale-only rule the versioned write
+        // uses. `resolvePathForUpdate` returns `undefined` to mean "skip the
+        // write" (null/empty override, or a translation-locale save).
+        const explicitPath = typeof params.path === 'string' && params.path.length > 0 ? params.path : null;
+        const pathForCommand = resolvePathForUpdate({
+            explicitPath,
+            currentPath: originalData.path,
+            requestLocale,
+            sourceLocale,
+            documentId: params.documentId,
+            logger: ctx.logger,
+        });
+        if (pathForCommand !== undefined) {
+            await db.commands.documents
+                .updateDocumentPath({
+                documentId: params.documentId,
+                collectionId,
+                locale: sourceLocale,
+                path: pathForCommand,
+            })
+                .catch((err) => rethrowPathConflict(err, pathForCommand, defaultLocale));
+        }
+        // Advertised locales: rewrite the document-grain set wholesale.
+        const availableLocalesWritten = params.availableLocales !== undefined;
+        if (params.availableLocales !== undefined) {
+            await db.commands.documents.setDocumentAvailableLocales({
+                documentId: params.documentId,
+                collectionId,
+                availableLocales: params.availableLocales,
+            });
+        }
+        return {
+            documentId: params.documentId,
+            path: pathForCommand,
+            availableLocalesWritten,
+        };
+    });
+}
 /**
  * Change a document's workflow status.
  *

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

@@ -45,6 +45,8 @@ function createMockDb() {
             },
             documents: {
                 createDocumentVersion,
+                updateDocumentPath: vi.fn(),
+                setDocumentAvailableLocales: vi.fn(),
                 setDocumentStatus,
                 archivePublishedVersions,
                 softDeleteDocument,

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

@@ -53,6 +53,8 @@ function createMockDb() {
             },
             documents: {
                 createDocumentVersion,
+                updateDocumentPath: vi.fn(),
+                setDocumentAvailableLocales: vi.fn(),
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),

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

@@ -141,6 +141,8 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
             collections: { create: vi.fn(), update: vi.fn(), delete: vi.fn() },
             documents: {
                 createDocumentVersion: vi.fn(),
+                updateDocumentPath: vi.fn(),
+                setDocumentAvailableLocales: vi.fn(),
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),

package/package.json

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