@purposeinplay/payload-ai-translate 0.1.0

package/dist/lib/effective-locales.d.ts

@@ -0,0 +1,181 @@
+import type { Payload } from 'payload';
+import type { AITranslatePluginConfig } from '../types.js';
+export declare function invalidateSettingsCache(slug?: string): void;
+/** @internal test helper */
+export declare function _resetEffectiveLocalesCache(): void;
+/**
+ * Resolved auto-translate decision for a specific surface.
+ *
+ * - `locales`: the (possibly empty) list of target locales that should
+ *   auto-translate on the next publish.
+ * - `skipAutoOnPublish`: when `true`, the auto-translate path is gated
+ *   off — the hook should bail before creating a job. Manual Translate…
+ *   (via the dialog or per-field button) is NOT affected by this flag.
+ *   See W-4 in the panel review for the intentional scope: this layer
+ *   only narrows automation, never the manual entry points.
+ */
+export type EffectiveLocaleDecision = {
+    locales: string[];
+    skipAutoOnPublish: boolean;
+};
+/**
+ * Read the per-doc auto-translate locale-narrow override from a saved doc.
+ *
+ * The plugin injects `_aiTranslateAutoLocales` (`select hasMany`) into
+ * every tracked collection / global as a NARROW filter — only locales
+ * the editor explicitly picks fan out. Two states are meaningful:
+ *
+ *   - `undefined` / not-an-array / empty array → no narrowing (inherit
+ *     the collection-level decision; fan out to every enabled locale).
+ *   - non-empty array → restrict the fan-out to these locales.
+ *
+ * Editors who want to OPT A DOC OUT of auto-translate entirely use the
+ * sibling `_aiTranslateOptOut` boolean field — see `getDocOptOut`.
+ *
+ * Historical note: pre-fix versions of the plugin documented a 3-state
+ * contract where `[]` meant "explicit opt-out." That state was
+ * unreachable at the storage layer because Payload's hasMany select
+ * serializes both "admin never touched it" and "admin cleared every
+ * checkbox" as 0 rows in the join table → empty array on read. The
+ * collapse meant auto-translate was effectively dead by default. The
+ * fix splits the two responsibilities: this field narrows locales when
+ * non-empty; the new boolean opts the whole doc out when true.
+ */
+export declare function getDocAutoLocaleOverride(doc: unknown): string[] | undefined;
+/**
+ * Read the per-doc opt-out flag. `true` means "skip auto-translate
+ * entirely for this document, regardless of collection or site-wide
+ * settings." Manual Translate from the dialog is NOT gated by this
+ * flag — same scope as the collection-level `enabled` flag.
+ *
+ * Defaults to `false`: a document that has never had the field touched
+ * (or is missing it on legacy/pre-migration data) participates in
+ * auto-translate normally.
+ */
+export declare function getDocOptOut(doc: unknown): boolean;
+/**
+ * Compute the locales that should auto-translate on the next publish for
+ * the given surface (collection slug OR global slug), by intersecting:
+ *
+ * 1. Plugin config `targetLocales` — the universe.
+ * 2. Site-wide `enabledTargetLocales` from `translation-settings`.
+ *    Empty / unset = "all enabled" (back-compat default).
+ * 3. Per-surface `perCollection` row, if any:
+ *    - `enabled: false`      → no locales + `skipAutoOnPublish: true`.
+ *    - `autoOnPublish: false` → no locales + `skipAutoOnPublish: true`.
+ *    - `targetLocalesOverride` non-empty → narrows further.
+ *
+ * Each layer NARROWS the previous — never widens.
+ *
+ * **Fail-safe on read failure**: a `findGlobal` exception (DB blip,
+ * permission misconfig, slug mismatch) returns
+ * `{ locales: [], skipAutoOnPublish: true }`. Auto-translate skips, the
+ * editor doesn't see a phantom job, and no LLM spend is incurred
+ * against locales the admin may have disabled but we couldn't read.
+ * Manual translate still works because it doesn't route through this
+ * function. This was a behavior flip from "fail-open" — see W-3 in the
+ * 2026-05-15 panel review for the rationale.
+ */
+export declare function getEffectiveAutoLocales(payload: Payload, config: AITranslatePluginConfig, surfaceSlug?: string): Promise<EffectiveLocaleDecision>;
+/**
+ * Returns `true` when the admin set `perCollection[surfaceSlug].enabled = false`.
+ *
+ * Used by the manual-translate endpoint to gate the dialog AND per-field
+ * button so the `enabled` checkbox is a true kill switch (BUG-08 fix).
+ * The sibling `autoOnPublish` flag remains automation-only — admins
+ * who want "manual translate yes, auto-translate no" should use that
+ * flag instead of `enabled: false`.
+ *
+ * **Fail-safe-OPEN on read failure**: returns `false` (allows translate)
+ * if settings can't be read. Blocking manual translate on a DB blip is
+ * more disruptive than letting the user proceed.
+ */
+export declare function isSurfaceDisabledByAdmin(payload: Payload, config: AITranslatePluginConfig, surfaceSlug: string): Promise<boolean>;
+/**
+ * Resolved state of the three plugin-wide kill switches added in v1.2.8.
+ * Each flag supersedes every per-collection setting — when `false`, the
+ * corresponding subsystem refuses to do work regardless of what the
+ * `perCollection` row says.
+ *
+ * Fail-safe direction matches the existing per-domain reasoning:
+ *
+ * - `autoEnabled` fails CLOSED on read failure (returns `false`). This
+ *   mirrors `getEffectiveAutoLocales`: when we can't read settings, we
+ *   don't know whether the admin disabled auto-translate, so we don't
+ *   spend tokens. The after-change hook becomes a no-op until settings
+ *   read recovers — same as if every locale were narrowed away.
+ *
+ * - `manualEnabled` fails OPEN on read failure (returns `true`). The
+ *   manual entry points are user-initiated; blocking them on a DB blip
+ *   is more disruptive than letting the editor through. This mirrors
+ *   `isSurfaceDisabledByAdmin`'s open-on-failure direction.
+ *
+ * - `bulkEnabled` fails OPEN on read failure (returns `true`). New bulk
+ *   runs are user-initiated; same reasoning as manual.
+ */
+export type GlobalKillSwitches = {
+    autoEnabled: boolean;
+    manualEnabled: boolean;
+    bulkEnabled: boolean;
+};
+export declare function getGlobalKillSwitches(payload: Payload, config: AITranslatePluginConfig): Promise<GlobalKillSwitches>;
+/**
+ * Return the set of field paths the admin opted out of translation
+ * for `surfaceSlug`, stored on the matching `perCollection` row of the
+ * `translation-settings` global.
+ *
+ * Scope: applies to BOTH manual and automation paths. The admin
+ * decision "don't translate `meta.description` on posts" is global —
+ * it would be surprising if Manual Translate… ignored it. This is the
+ * intentional difference vs `enabled` / `autoOnPublish`, which are
+ * automation-only gates.
+ *
+ * **Fail-safe-OPEN on read failure**: returns an empty set if the
+ * settings global can't be read. Blocking a manual translate on a DB
+ * blip would be more disruptive than letting the (already-tracked)
+ * field through. The locale-resolution function above flips the other
+ * direction because it's gating LLM SPEND, not which fields go in.
+ */
+export declare function getExcludedFieldPaths(payload: Payload, config: AITranslatePluginConfig, surfaceSlug: string): Promise<Set<string>>;
+/**
+ * Surface-aware variant of `getEffectiveExcludePatterns`.
+ *
+ * Reads the `perCollection[surfaceSlug].translateSlug` flag from the
+ * translation-settings global. When `true`, drops `'slug'` from the
+ * effective patterns so the resolver picks it up. When `false` (the
+ * default), behaviour is identical to `getEffectiveExcludePatterns`.
+ *
+ * Use this in every translation path that operates on a known
+ * surface — `translateDocument`, `translateGlobal`, the estimate
+ * endpoint, the cost-guard pre-flight, and the admin UI's
+ * client-config map. The static `getEffectiveExcludePatterns` is
+ * still appropriate for config-build-time paths (per-field button
+ * injection) that have no async context AND no per-row knowledge.
+ *
+ * **Fail-safe-CLOSED on read failure**: returns the base patterns
+ * unchanged. This is the conservative direction — if we can't read
+ * the toggle, we keep slug excluded (no per-locale URL churn from a
+ * DB blip). Mirrors `getExcludedFieldPaths`' policy of "blocking
+ * manual translate on a settings-read blip is more disruptive than
+ * letting the field through" — except in this case the opposite
+ * applies because the default IS exclusion.
+ */
+export declare function getEffectiveExcludePatternsForSurface(payload: Payload, config: AITranslatePluginConfig, surfaceSlug: string): Promise<string[]>;
+/**
+ * Prefix-aware match: `path` is excluded if it appears in `excluded`
+ * OR any ancestor segment of it does. Excluding `layout` therefore
+ * excludes `layout.columns`, `layout.columns.richText`, etc.
+ *
+ * Why prefix and not exact: editors think in top-level fields. The
+ * admin UI offers ONE checkbox per top-level field — unchecking
+ * "Layout" should skip everything under it. Exact-match would leave
+ * `layout.columns.richText` translating even when the editor opted
+ * the entire Layout out. Per-leaf exclusions are still expressible
+ * via the more specific path (e.g. `meta.description`).
+ *
+ * Implementation note: O(D × |excluded|) per call where D is the
+ * path's segment depth (small constant in practice). Acceptable for
+ * the per-fire filter; would warrant a trie if exclusion lists grew
+ * to hundreds.
+ */
+export declare function isPathExcluded(path: string, excluded: Set<string>): boolean;

package/dist/lib/effective-locales.js

@@ -0,0 +1,302 @@
+import { DEFAULT_SETTINGS_GLOBAL_SLUG } from '../settings-global.js';
+import { getEffectiveExcludePatterns } from './exclude-fields.js';
+const SETTINGS_CACHE_TTL_MS = 30_000;
+const settingsCache = new Map();
+export function invalidateSettingsCache(slug) {
+    if (slug) {
+        settingsCache.delete(slug);
+    } else {
+        settingsCache.clear();
+    }
+}
+/** @internal test helper */ export function _resetEffectiveLocalesCache() {
+    settingsCache.clear();
+}
+async function readSettings(payload, config) {
+    const slug = config.settings?.globalSlug ?? DEFAULT_SETTINGS_GLOBAL_SLUG;
+    const cached = settingsCache.get(slug);
+    const now = Date.now();
+    if (cached && cached.expiresAt > now) {
+        return {
+            failed: false,
+            settings: cached.value
+        };
+    }
+    try {
+        const settings = await payload.findGlobal({
+            slug,
+            depth: 0,
+            overrideAccess: true
+        });
+        settingsCache.set(slug, {
+            value: settings,
+            expiresAt: now + SETTINGS_CACHE_TTL_MS
+        });
+        return {
+            failed: false,
+            settings
+        };
+    } catch (err) {
+        payload.logger?.error?.(`[ai-translate] Failed to read "${slug}" global — settings-driven gates will fall back to safe defaults. Underlying error: ${err instanceof Error ? err.message : 'Unknown error'}`);
+        // Do NOT cache the failure — next fire should retry.
+        return {
+            failed: true,
+            settings: null
+        };
+    }
+}
+/**
+ * Read the per-doc auto-translate locale-narrow override from a saved doc.
+ *
+ * The plugin injects `_aiTranslateAutoLocales` (`select hasMany`) into
+ * every tracked collection / global as a NARROW filter — only locales
+ * the editor explicitly picks fan out. Two states are meaningful:
+ *
+ *   - `undefined` / not-an-array / empty array → no narrowing (inherit
+ *     the collection-level decision; fan out to every enabled locale).
+ *   - non-empty array → restrict the fan-out to these locales.
+ *
+ * Editors who want to OPT A DOC OUT of auto-translate entirely use the
+ * sibling `_aiTranslateOptOut` boolean field — see `getDocOptOut`.
+ *
+ * Historical note: pre-fix versions of the plugin documented a 3-state
+ * contract where `[]` meant "explicit opt-out." That state was
+ * unreachable at the storage layer because Payload's hasMany select
+ * serializes both "admin never touched it" and "admin cleared every
+ * checkbox" as 0 rows in the join table → empty array on read. The
+ * collapse meant auto-translate was effectively dead by default. The
+ * fix splits the two responsibilities: this field narrows locales when
+ * non-empty; the new boolean opts the whole doc out when true.
+ */ export function getDocAutoLocaleOverride(doc) {
+    if (!doc || typeof doc !== 'object') return undefined;
+    const value = doc._aiTranslateAutoLocales;
+    if (!Array.isArray(value)) return undefined;
+    // Defensive copy + ensure all elements are strings (the field is a
+    // typed select; this filters out any stray malformed entries from
+    // direct DB writes or older data).
+    const cleaned = value.filter((v)=>typeof v === 'string');
+    // Empty array = inherit. Explicit opt-out lives on the
+    // `_aiTranslateOptOut` boolean instead.
+    if (cleaned.length === 0) return undefined;
+    return cleaned;
+}
+/**
+ * Read the per-doc opt-out flag. `true` means "skip auto-translate
+ * entirely for this document, regardless of collection or site-wide
+ * settings." Manual Translate from the dialog is NOT gated by this
+ * flag — same scope as the collection-level `enabled` flag.
+ *
+ * Defaults to `false`: a document that has never had the field touched
+ * (or is missing it on legacy/pre-migration data) participates in
+ * auto-translate normally.
+ */ export function getDocOptOut(doc) {
+    if (!doc || typeof doc !== 'object') return false;
+    const value = doc._aiTranslateOptOut;
+    return value === true;
+}
+/**
+ * Compute the locales that should auto-translate on the next publish for
+ * the given surface (collection slug OR global slug), by intersecting:
+ *
+ * 1. Plugin config `targetLocales` — the universe.
+ * 2. Site-wide `enabledTargetLocales` from `translation-settings`.
+ *    Empty / unset = "all enabled" (back-compat default).
+ * 3. Per-surface `perCollection` row, if any:
+ *    - `enabled: false`      → no locales + `skipAutoOnPublish: true`.
+ *    - `autoOnPublish: false` → no locales + `skipAutoOnPublish: true`.
+ *    - `targetLocalesOverride` non-empty → narrows further.
+ *
+ * Each layer NARROWS the previous — never widens.
+ *
+ * **Fail-safe on read failure**: a `findGlobal` exception (DB blip,
+ * permission misconfig, slug mismatch) returns
+ * `{ locales: [], skipAutoOnPublish: true }`. Auto-translate skips, the
+ * editor doesn't see a phantom job, and no LLM spend is incurred
+ * against locales the admin may have disabled but we couldn't read.
+ * Manual translate still works because it doesn't route through this
+ * function. This was a behavior flip from "fail-open" — see W-3 in the
+ * 2026-05-15 panel review for the rationale.
+ */ export async function getEffectiveAutoLocales(payload, config, surfaceSlug) {
+    const universe = config.targetLocales ?? [];
+    if (universe.length === 0) {
+        return {
+            locales: [],
+            skipAutoOnPublish: false
+        };
+    }
+    const read = await readSettings(payload, config);
+    if (read.failed) {
+        // Locale resolution is fail-safe-skip: we don't know which locales
+        // the admin disabled, so spending tokens against any of them is a
+        // policy violation. Manual translate still works because it doesn't
+        // route through this function.
+        return {
+            locales: [],
+            skipAutoOnPublish: true
+        };
+    }
+    const settings = read.settings;
+    // Per-surface override is evaluated FIRST when surfaceSlug is provided.
+    // `enabled: false` and `autoOnPublish: false` short-circuit the entire
+    // resolution — there's no point computing the site-wide intersection
+    // when we're about to return an empty list anyway. Saves a small bit
+    // of work per fire, scales meaningfully under bulk-publish.
+    if (surfaceSlug && Array.isArray(settings?.perCollection)) {
+        const row = settings.perCollection.find((r)=>Boolean(r) && r?.slug === surfaceSlug);
+        if (row) {
+            if (row.enabled === false) {
+                return {
+                    locales: [],
+                    skipAutoOnPublish: true
+                };
+            }
+            if (row.autoOnPublish === false) {
+                return {
+                    locales: [],
+                    skipAutoOnPublish: true
+                };
+            }
+        }
+    }
+    // Site-wide allow-list. Empty / unset = "all configured target locales".
+    const enabled = settings?.enabledTargetLocales;
+    let siteWide = universe;
+    if (Array.isArray(enabled) && enabled.length > 0) {
+        siteWide = universe.filter((l)=>enabled.includes(l));
+    }
+    // Per-surface target-locale narrowing (applied after the
+    // `enabled` / `autoOnPublish` gate above).
+    if (surfaceSlug && Array.isArray(settings?.perCollection)) {
+        const row = settings.perCollection.find((r)=>r?.slug === surfaceSlug);
+        const override = row?.targetLocalesOverride;
+        if (Array.isArray(override) && override.length > 0) {
+            return {
+                locales: siteWide.filter((l)=>override.includes(l)),
+                skipAutoOnPublish: false
+            };
+        }
+    }
+    return {
+        locales: siteWide,
+        skipAutoOnPublish: false
+    };
+}
+/**
+ * Returns `true` when the admin set `perCollection[surfaceSlug].enabled = false`.
+ *
+ * Used by the manual-translate endpoint to gate the dialog AND per-field
+ * button so the `enabled` checkbox is a true kill switch (BUG-08 fix).
+ * The sibling `autoOnPublish` flag remains automation-only — admins
+ * who want "manual translate yes, auto-translate no" should use that
+ * flag instead of `enabled: false`.
+ *
+ * **Fail-safe-OPEN on read failure**: returns `false` (allows translate)
+ * if settings can't be read. Blocking manual translate on a DB blip is
+ * more disruptive than letting the user proceed.
+ */ export async function isSurfaceDisabledByAdmin(payload, config, surfaceSlug) {
+    const read = await readSettings(payload, config);
+    if (read.failed || !read.settings?.perCollection) return false;
+    const row = read.settings.perCollection.find((r)=>r?.slug === surfaceSlug);
+    return row?.enabled === false;
+}
+export async function getGlobalKillSwitches(payload, config) {
+    const read = await readSettings(payload, config);
+    if (read.failed) {
+        return {
+            autoEnabled: false,
+            manualEnabled: true,
+            bulkEnabled: true
+        };
+    }
+    const settings = read.settings;
+    return {
+        autoEnabled: settings?.globalAutoTranslateEnabled !== false,
+        manualEnabled: settings?.globalManualTranslateEnabled !== false,
+        bulkEnabled: settings?.globalBulkTranslateEnabled !== false
+    };
+}
+/**
+ * Return the set of field paths the admin opted out of translation
+ * for `surfaceSlug`, stored on the matching `perCollection` row of the
+ * `translation-settings` global.
+ *
+ * Scope: applies to BOTH manual and automation paths. The admin
+ * decision "don't translate `meta.description` on posts" is global —
+ * it would be surprising if Manual Translate… ignored it. This is the
+ * intentional difference vs `enabled` / `autoOnPublish`, which are
+ * automation-only gates.
+ *
+ * **Fail-safe-OPEN on read failure**: returns an empty set if the
+ * settings global can't be read. Blocking a manual translate on a DB
+ * blip would be more disruptive than letting the (already-tracked)
+ * field through. The locale-resolution function above flips the other
+ * direction because it's gating LLM SPEND, not which fields go in.
+ */ export async function getExcludedFieldPaths(payload, config, surfaceSlug) {
+    const read = await readSettings(payload, config);
+    if (read.failed || !read.settings) return new Set();
+    const rows = read.settings.perCollection;
+    if (!Array.isArray(rows)) return new Set();
+    const row = rows.find((r)=>r?.slug === surfaceSlug);
+    const paths = row?.excludedFieldPaths;
+    if (!Array.isArray(paths)) return new Set();
+    return new Set(paths.filter((p)=>typeof p === 'string'));
+}
+/**
+ * Surface-aware variant of `getEffectiveExcludePatterns`.
+ *
+ * Reads the `perCollection[surfaceSlug].translateSlug` flag from the
+ * translation-settings global. When `true`, drops `'slug'` from the
+ * effective patterns so the resolver picks it up. When `false` (the
+ * default), behaviour is identical to `getEffectiveExcludePatterns`.
+ *
+ * Use this in every translation path that operates on a known
+ * surface — `translateDocument`, `translateGlobal`, the estimate
+ * endpoint, the cost-guard pre-flight, and the admin UI's
+ * client-config map. The static `getEffectiveExcludePatterns` is
+ * still appropriate for config-build-time paths (per-field button
+ * injection) that have no async context AND no per-row knowledge.
+ *
+ * **Fail-safe-CLOSED on read failure**: returns the base patterns
+ * unchanged. This is the conservative direction — if we can't read
+ * the toggle, we keep slug excluded (no per-locale URL churn from a
+ * DB blip). Mirrors `getExcludedFieldPaths`' policy of "blocking
+ * manual translate on a settings-read blip is more disruptive than
+ * letting the field through" — except in this case the opposite
+ * applies because the default IS exclusion.
+ */ export async function getEffectiveExcludePatternsForSurface(payload, config, surfaceSlug) {
+    const base = getEffectiveExcludePatterns(config);
+    const read = await readSettings(payload, config);
+    if (read.failed || !read.settings?.perCollection) return base;
+    const row = read.settings.perCollection.find((r)=>r?.slug === surfaceSlug);
+    if (row?.translateSlug !== true) return base;
+    // Drop only the exact `'slug'` pattern. Don't touch suffix/glob
+    // patterns like `'**.slug'` if a consumer ever uses them — those
+    // are a deliberate broader exclusion the editor isn't opting out of.
+    return base.filter((p)=>p !== 'slug');
+}
+/**
+ * Prefix-aware match: `path` is excluded if it appears in `excluded`
+ * OR any ancestor segment of it does. Excluding `layout` therefore
+ * excludes `layout.columns`, `layout.columns.richText`, etc.
+ *
+ * Why prefix and not exact: editors think in top-level fields. The
+ * admin UI offers ONE checkbox per top-level field — unchecking
+ * "Layout" should skip everything under it. Exact-match would leave
+ * `layout.columns.richText` translating even when the editor opted
+ * the entire Layout out. Per-leaf exclusions are still expressible
+ * via the more specific path (e.g. `meta.description`).
+ *
+ * Implementation note: O(D × |excluded|) per call where D is the
+ * path's segment depth (small constant in practice). Acceptable for
+ * the per-fire filter; would warrant a trie if exclusion lists grew
+ * to hundreds.
+ */ export function isPathExcluded(path, excluded) {
+    if (excluded.size === 0) return false;
+    if (excluded.has(path)) return true;
+    const segments = path.split('.');
+    for(let i = segments.length - 1; i > 0; i--){
+        const prefix = segments.slice(0, i).join('.');
+        if (excluded.has(prefix)) return true;
+    }
+    return false;
+}