@byline/core 3.0.0 → 3.0.2

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

@@ -360,6 +360,10 @@ export interface BeforeUpdateContext {
         sourceLocale: string;
         targetLocale: string;
     };
+    /** Set only when the update originates from a Delete-Locale operation. */
+    deleteLocale?: {
+        locale: string;
+    };
 }
 /**
  * Context passed to `afterUpdate` hooks.
@@ -385,6 +389,10 @@ export interface AfterUpdateContext {
         sourceLocale: string;
         targetLocale: string;
     };
+    /** Mirrors `BeforeUpdateContext.deleteLocale`. */
+    deleteLocale?: {
+        locale: string;
+    };
 }
 /**
  * Context passed to `beforeStatusChange` / `afterStatusChange` hooks.
@@ -729,7 +737,7 @@ export interface CollectionDefinition {
      * collection has at least one `localized` field, so the validator rejects
      * `advertiseLocales: true` on a collection with none.
      *
-     * See `docs/AVAILABLE-LOCALES.md`.
+     * See `docs/I18N.md`.
      */
     advertiseLocales?: boolean;
     /**
@@ -864,8 +872,8 @@ export type BlocksUnion<Bs extends readonly Block[]> = Bs[number] extends infer
  * on hand-authored fields without waiting for them to be placed inside a
  * `fields: [...]` array. Replaces the `as const satisfies Field` pattern.
  *
- * For factories that *generate* a field shape from input (e.g. mapped-type
- * driven fields like `availableLanguagesField`), a custom return type is
+ * For factories that *generate* a field shape from input (e.g. a helper whose
+ * return type is a mapped type over its options), a custom return type is
  * still the right tool — `defineField` is for identity / passthrough cases.
  *
  * The companion data-shape extractor `FieldData<F>` lives in

package/dist/@types/collection-types.js

@@ -182,8 +182,8 @@ export function defineBlock(definition) {
  * on hand-authored fields without waiting for them to be placed inside a
  * `fields: [...]` array. Replaces the `as const satisfies Field` pattern.
  *
- * For factories that *generate* a field shape from input (e.g. mapped-type
- * driven fields like `availableLanguagesField`), a custom return type is
+ * For factories that *generate* a field shape from input (e.g. a helper whose
+ * return type is a mapped type over its options), a custom return type is
  * still the right tool — `defineField` is for identity / passthrough cases.
  *
  * The companion data-shape extractor `FieldData<F>` lives in

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

@@ -39,7 +39,7 @@ export type ReadMode = 'any' | 'published';
  * safe default for internal/direct reads); `@byline/client` defaults it to
  * `'fallback'` for application reads. Availability follows path-coverage against
  * the default content locale; a document with no localized content is available
- * in every locale. See `docs/CONTENT-LOCALE-RESOLUTION.md`.
+ * in every locale. See `docs/I18N.md`.
  */
 export type MissingLocalePolicy = 'empty' | 'fallback' | 'omit';
 /**
@@ -215,7 +215,7 @@ export interface IDbAdapter {
      * boot by `initBylineCore` so in-place upgrades self-heal without a manual
      * step or a migrate-ordering constraint — a no-op (zero rows) once every
      * document is stamped. Optional so adapters that don't model `source_locale`
-     * need not implement it. See docs/DEFAULT-LOCALE-SWITCHING.md.
+     * need not implement it. See docs/I18N.md.
      */
     backfillSourceLocales?: () => Promise<{
         rowsUpdated: number;
@@ -315,7 +315,7 @@ export interface IDocumentCommands {
          * editorial advertised-locale set. `undefined` leaves the existing set
          * untouched (sticky across versions, like `path`); `[]` clears it. The
          * locale values are the advertised content locales themselves, not the
-         * write locale. See `docs/AVAILABLE-LOCALES.md`.
+         * write locale. See `docs/I18N.md`.
          */
         availableLocales?: string[];
         locale?: string;
@@ -373,6 +373,24 @@ export interface IDocumentCommands {
     softDeleteDocument(params: {
         document_id: string;
     }): Promise<number>;
+    /**
+     * Remove one content locale's data from a document by writing a new
+     * immutable version that carries forward every store row except the target
+     * locale's (the `'all'` rows and all other locales are kept). The prior
+     * version still holds the deleted locale, so the operation is recoverable.
+     *
+     * `status` is the new version's status (the lifecycle service passes the
+     * workflow default — a fresh draft). Returns the new and previous version
+     * ids, or `null` when the document has no current version.
+     */
+    deleteDocumentLocale(params: {
+        documentId: string;
+        locale: string;
+        status?: string;
+    }): Promise<{
+        newVersionId: string;
+        previousVersionId: string;
+    } | null>;
     /**
      * Write the fractional-index `order_key` on a single `byline_documents`
      * row. Used by the reorder server fn for `orderable: true` collections.

package/dist/@types/site-config.d.ts

@@ -63,7 +63,7 @@ export interface BaseConfig {
              * its path locale, and the completeness ledger — so changing this value
              * is safe for existing data: they keep reading against the locale they
              * were authored in. New documents created after the change anchor to the
-             * new value. See docs/DEFAULT-LOCALE-SWITCHING.md.
+             * new value. See docs/I18N.md.
              *
              * (Switching this on a live system still needs the one-time
              * `backfillSourceLocales()` maintenance step to have stamped any rows

package/dist/core.js

@@ -96,7 +96,7 @@ export const initBylineCore = async (config, pinoLogger) => {
     // and is a no-op (zero rows) once every document is stamped. Self-heals
     // in-place upgrades without a manual maintenance step. The write path stamps
     // new documents directly, so steady-state boots touch nothing. See
-    // docs/DEFAULT-LOCALE-SWITCHING.md.
+    // docs/I18N.md.
     if (typeof composed.db.backfillSourceLocales === 'function') {
         const { rowsUpdated } = await composed.db.backfillSourceLocales();
         if (rowsUpdated > 0) {

package/dist/schemas/zod/builder.js

@@ -197,7 +197,7 @@ export const createBaseSchema = (collection) => {
         id: z.uuid(),
         versionId: z.uuid().optional(),
         path: z.string().optional(),
-        // The document's content source-locale anchor (see docs/DEFAULT-LOCALE-SWITCHING.md).
+        // The document's content source-locale anchor (see docs/I18N.md).
         // Carried through list/get responses so the admin can badge it; Zod would
         // otherwise strip it as an undeclared key.
         sourceLocale: z.string().optional(),

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

@@ -42,6 +42,7 @@ function createMockDb(options) {
                 setDocumentStatus: vi.fn(fail),
                 archivePublishedVersions: vi.fn(fail),
                 softDeleteDocument: vi.fn(fail),
+                deleteDocumentLocale: vi.fn(fail),
                 setOrderKey: vi.fn(fail),
             },
             counters: {
@@ -183,6 +184,7 @@ describe('ensureCollections', () => {
                     setDocumentStatus: vi.fn(),
                     archivePublishedVersions: vi.fn(),
                     softDeleteDocument: vi.fn(),
+                    deleteDocumentLocale: vi.fn(),
                     setOrderKey: vi.fn(),
                 },
                 counters: {

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

@@ -27,6 +27,7 @@ function makeAdapter(options) {
                 setDocumentStatus: vi.fn(fail),
                 archivePublishedVersions: vi.fn(fail),
                 softDeleteDocument: vi.fn(fail),
+                deleteDocumentLocale: vi.fn(fail),
                 setOrderKey: vi.fn(fail),
             },
             counters: {

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

@@ -135,6 +135,13 @@ export interface CopyToLocaleResult {
      */
     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;
@@ -185,7 +192,7 @@ export declare function createDocument(ctx: DocumentLifecycleContext, params: {
      * 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/AVAILABLE-LOCALES.md.
+     * the safe opt-in default); `[]` clears it. See docs/I18N.md.
      */
     availableLocales?: string[];
 }): Promise<CreateDocumentResult>;
@@ -217,7 +224,7 @@ export declare function updateDocument(ctx: DocumentLifecycleContext, params: {
      * 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/AVAILABLE-LOCALES.md.
+     * available-locales sidebar widget. See docs/I18N.md.
      */
     availableLocales?: string[];
 }): Promise<UpdateDocumentResult>;
@@ -252,7 +259,7 @@ export declare function updateDocumentWithPatches(ctx: DocumentLifecycleContext,
      * 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/AVAILABLE-LOCALES.md.
+     * array replaces it wholesale. See docs/I18N.md.
      */
     availableLocales?: string[];
 }): Promise<UpdateDocumentWithPatchesResult>;
@@ -421,3 +428,32 @@ export declare function copyToLocale(ctx: DocumentLifecycleContext, params: {
     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>;

package/dist/services/document-lifecycle.js

@@ -134,7 +134,7 @@ function resolvePathForUpdate(args) {
         // skip the write (existing path row stays as-is — sticky). The path row
         // lives under the document's source_locale (its anchor), not the mutable
         // global default — so this stays correct after the global default is
-        // switched. See docs/DEFAULT-LOCALE-SWITCHING.md.
+        // switched. See docs/I18N.md.
         return explicitPath ?? undefined;
     }
     // Non-source-locale (translation) write: reject any path change with a warn
@@ -1341,3 +1341,107 @@ export async function copyToLocale(ctx, params) {
         };
     });
 }
+// ---------------------------------------------------------------------------
+// deleteLocale
+// ---------------------------------------------------------------------------
+/**
+ * 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 async function deleteLocale(ctx, params) {
+    return withLogContext({ domain: 'services', module: 'lifecycle', function: 'deleteLocale' }, async () => {
+        const { db, definition, collectionId, collectionPath, defaultLocale } = ctx;
+        assertActorCanPerform(ctx.requestContext, collectionPath, 'update');
+        // The default locale anchors the document's path and source_locale —
+        // it cannot be deleted (the other locales fall back to it).
+        if (params.locale === defaultLocale) {
+            throw ERR_VALIDATION({
+                message: `cannot delete the default content locale ('${defaultLocale}')`,
+                details: { documentId: params.documentId, locale: params.locale, collectionPath },
+            }).log(ctx.logger);
+        }
+        // Read the document in the locale being removed — validates existence,
+        // supplies originalData for hooks, and the availability set for the
+        // content-presence check below.
+        const target = await db.queries.documents.getDocumentById({
+            collection_id: collectionId,
+            document_id: params.documentId,
+            locale: params.locale,
+            reconstruct: true,
+            lenient: true,
+            requestContext: ctx.requestContext,
+        });
+        if (target == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId, collectionPath },
+            }).log(ctx.logger);
+        }
+        const targetRecord = target;
+        // `_availableVersionLocales` is the derived (path-coverage) set; it is
+        // the same source the editor's Delete-Locale picker is built from, so a
+        // locale offered in the UI resolves here. A partially-translated locale
+        // that never reached full coverage is not deletable through this path.
+        const available = targetRecord._availableVersionLocales ?? [];
+        if (!available.includes(params.locale)) {
+            throw ERR_NOT_FOUND({
+                message: `locale '${params.locale}' has no content to delete`,
+                details: { documentId: params.documentId, locale: params.locale, collectionPath },
+            }).log(ctx.logger);
+        }
+        const hooks = definition.hooks;
+        const deleteLocaleMarker = { locale: params.locale };
+        const originalData = targetRecord.fields ?? {};
+        await invokeHook(hooks?.beforeUpdate, {
+            data: originalData,
+            originalData,
+            collectionPath,
+            deleteLocale: deleteLocaleMarker,
+        });
+        const result = await db.commands.documents.deleteDocumentLocale({
+            documentId: params.documentId,
+            locale: params.locale,
+            status: getDefaultStatus(definition),
+        });
+        if (result == null) {
+            throw ERR_NOT_FOUND({
+                message: 'document not found',
+                details: { documentId: params.documentId, collectionPath },
+            }).log(ctx.logger);
+        }
+        await invokeHook(hooks?.afterUpdate, {
+            data: originalData,
+            originalData,
+            collectionPath,
+            documentId: params.documentId,
+            documentVersionId: result.newVersionId,
+            deleteLocale: deleteLocaleMarker,
+        });
+        return {
+            documentId: params.documentId,
+            documentVersionId: result.newVersionId,
+            locale: params.locale,
+        };
+    });
+}

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

@@ -47,6 +47,7 @@ function createMockDb() {
                 setDocumentStatus,
                 archivePublishedVersions,
                 softDeleteDocument,
+                deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
             },
             counters: {

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

@@ -56,6 +56,7 @@ function createMockDb() {
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),
+                deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
             },
             counters: {

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

@@ -144,6 +144,7 @@ function makeMockAdapter(store = {}, pathByCollectionId = {}) {
                 setDocumentStatus: vi.fn(),
                 archivePublishedVersions: vi.fn(),
                 softDeleteDocument: vi.fn(),
+                deleteDocumentLocale: vi.fn(),
                 setOrderKey: vi.fn(),
             },
             counters: {

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -79,7 +79,7 @@
     "sharp": "^0.34.5",
     "uuid": "^14.0.0",
     "zod": "^4.4.3",
-    "@byline/auth": "3.0.0"
+    "@byline/auth": "3.0.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.15",