@focus-reactive/payload-plugin-translator 0.7.1 → 0.8.0

package/dist/server/features/createTranslationRoutes.d.ts

@@ -1,6 +1,8 @@
 import type { CollectionSlug, Endpoint } from "payload";
 import type { AccessGuard } from "../shared";
 import type { TaskRunnerFactory } from "../modules/task-runner";
+import type { CollectionSchemaMap } from "../../types/CollectionSchemaMap";
+import type { ProvenanceStoreFactory } from "../modules/provenance";
 export type TranslationRoutesDeps = {
     taskRunnerFactory: TaskRunnerFactory;
     /** Collections the plugin manages — gates which slugs the routes accept. */
@@ -9,15 +11,21 @@ export type TranslationRoutesDeps = {
     };
     access?: AccessGuard;
     basePath?: string;
+    /** Original per-collection field schema — needed to recompute source fingerprints for staleness. */
+    schemaMap: CollectionSchemaMap;
+    /** Builds a provenance store; absent when provenance is disabled (staleness then reports empty). */
+    provenanceStoreFactory?: ProvenanceStoreFactory;
 };
 /**
- * The translator's HTTP surface as one shared bundle: the 6 job-API endpoints
+ * The translator's HTTP surface as one shared bundle: the job-API endpoints
  * (enqueue / run / cancel / cancel-by-collection / document-status /
- * collection-status), all wired to the same runner factory and access guard.
+ * collection-status) plus the provenance-backed staleness endpoints
+ * (document-staleness / dismiss), all wired to the same access guard.
  *
  * Extracted from the plugin's `init()` so registration is a single unit. The
  * document and collection levels each contribute this bundle via the level
  * context; the plugin deduplicates by method + path, so it registers exactly
- * once. Behaviour-preserving: same endpoints, same order, same wiring.
+ * once. The staleness endpoints always register; when provenance is disabled
+ * (`provenanceStoreFactory` absent) they simply report no staleness.
  */
-export declare function createTranslationRoutes({ taskRunnerFactory, collectionConfig, access, basePath, }: TranslationRoutesDeps): Endpoint[];
+export declare function createTranslationRoutes({ taskRunnerFactory, collectionConfig, access, basePath, schemaMap, provenanceStoreFactory, }: TranslationRoutesDeps): Endpoint[];

package/dist/server/features/createTranslationRoutes.js

@@ -4,23 +4,33 @@ import { createCancelRoute } from "./cancel";
 import { createCancelByCollectionRoute } from "./cancel-by-collection";
 import { createGetDocumentStatusRoute } from "./get-document-status";
 import { createGetCollectionStatusRoute } from "./get-collection-status";
+import { createGetDocumentStalenessRoute, createDismissStalenessRoute } from "./staleness";
 /**
- * The translator's HTTP surface as one shared bundle: the 6 job-API endpoints
+ * The translator's HTTP surface as one shared bundle: the job-API endpoints
  * (enqueue / run / cancel / cancel-by-collection / document-status /
- * collection-status), all wired to the same runner factory and access guard.
+ * collection-status) plus the provenance-backed staleness endpoints
+ * (document-staleness / dismiss), all wired to the same access guard.
  *
  * Extracted from the plugin's `init()` so registration is a single unit. The
  * document and collection levels each contribute this bundle via the level
  * context; the plugin deduplicates by method + path, so it registers exactly
- * once. Behaviour-preserving: same endpoints, same order, same wiring.
- */ export function createTranslationRoutes({ taskRunnerFactory, collectionConfig, access, basePath }) {
+ * once. The staleness endpoints always register; when provenance is disabled
+ * (`provenanceStoreFactory` absent) they simply report no staleness.
+ */ export function createTranslationRoutes({ taskRunnerFactory, collectionConfig, access, basePath, schemaMap, provenanceStoreFactory }) {
+    const stalenessConfig = {
+        availableCollections: collectionConfig.availableCollections,
+        schemaMap,
+        provenanceStoreFactory
+    };
     return [
         createEnqueueRoute(taskRunnerFactory, collectionConfig, access, basePath),
         createRunRoute(taskRunnerFactory, access, basePath),
         createCancelRoute(taskRunnerFactory, access, basePath),
         createCancelByCollectionRoute(collectionConfig, taskRunnerFactory, access, basePath),
         createGetDocumentStatusRoute(collectionConfig, taskRunnerFactory, access, basePath),
-        createGetCollectionStatusRoute(collectionConfig, taskRunnerFactory, access, basePath)
+        createGetCollectionStatusRoute(collectionConfig, taskRunnerFactory, access, basePath),
+        createGetDocumentStalenessRoute(stalenessConfig, access, basePath),
+        createDismissStalenessRoute(stalenessConfig, access, basePath)
     ];
 }
 

package/dist/server/features/get-document-status/model.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { JobIdSchema } from "../../shared";
+import { JobIdSchema, toClientErrorMessage } from "../../shared";
 /**
  * Input validation schema.
  *
@@ -28,7 +28,12 @@ import { JobIdSchema } from "../../shared";
             target_lng: task.input.targetLng,
             strategy: task.input.strategy
         },
-        error: task.error,
+        // Never ship the raw provider/runtime error to the browser outside development — it can leak
+        // implementation detail and secrets (e.g. a partial API key). The full error stays in the job
+        // record + server logs.
+        error: task.error ? {
+            message: toClientErrorMessage(task.error.message)
+        } : undefined,
         cancelled: task.cancelled
     };
 }

package/dist/server/features/staleness/dismissStaleness.handler.d.ts

@@ -0,0 +1,8 @@
+import type { PayloadRequest } from "payload";
+import type { StalenessConfig } from "./model";
+/** Dismisses (acknowledges) staleness of one target locale for a document. */
+export declare class DismissStalenessHandler {
+    private readonly config;
+    constructor(config: StalenessConfig);
+    handle(req: PayloadRequest): Promise<Response>;
+}

package/dist/server/features/staleness/dismissStaleness.handler.js

@@ -0,0 +1,27 @@
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable } from "../_lib/collection-utils";
+import { DismissStalenessInputSchema } from "./model";
+import { dismissLocaleStaleness } from "./service";
+/** Dismisses (acknowledges) staleness of one target locale for a document. */ export class DismissStalenessHandler {
+    config;
+    constructor(config){
+        this.config = config;
+    }
+    async handle(req) {
+        const validationResult = DismissStalenessInputSchema.safeParse(await req.json?.());
+        if (validationResult.error) {
+            return ServerResponse.validationError(validationResult.error.issues);
+        }
+        const { collection_slug, collection_id, target_lng } = validationResult.data;
+        const collectionSlug = isCollectionAvailable(collection_slug, this.config.availableCollections);
+        if (!collectionSlug) {
+            return ServerResponse.badRequest("Collection not available for translation");
+        }
+        await dismissLocaleStaleness(req.payload, this.config, collectionSlug, collection_id, target_lng);
+        return ServerResponse.success({
+            success: true
+        });
+    }
+}
+
+//# sourceMappingURL=dismissStaleness.handler.js.map

package/dist/server/features/staleness/getDocumentStaleness.handler.d.ts

@@ -0,0 +1,12 @@
+import type { PayloadRequest } from "payload";
+import type { StalenessConfig } from "./model";
+/**
+ * Reads per-locale staleness for a single document. Best-effort: a recompute failure (e.g. the
+ * consumer enabled provenance but has not run the SQL migration, so the sidecar table is missing)
+ * degrades to an empty result and a log line — it must never 500 the document panel.
+ */
+export declare class GetDocumentStalenessHandler {
+    private readonly config;
+    constructor(config: StalenessConfig);
+    handle(req: PayloadRequest): Promise<Response>;
+}

package/dist/server/features/staleness/getDocumentStaleness.handler.js

@@ -0,0 +1,43 @@
+import { ServerResponse } from "../../shared";
+import { isCollectionAvailable } from "../_lib/collection-utils";
+import { GetDocumentStalenessInputSchema } from "./model";
+import { computeDocumentStaleness } from "./service";
+/**
+ * Reads per-locale staleness for a single document. Best-effort: a recompute failure (e.g. the
+ * consumer enabled provenance but has not run the SQL migration, so the sidecar table is missing)
+ * degrades to an empty result and a log line — it must never 500 the document panel.
+ */ export class GetDocumentStalenessHandler {
+    config;
+    constructor(config){
+        this.config = config;
+    }
+    async handle(req) {
+        const validationResult = GetDocumentStalenessInputSchema.safeParse(req.routeParams);
+        if (validationResult.error) {
+            return ServerResponse.validationError(validationResult.error.issues);
+        }
+        const { collection_slug, collection_id } = validationResult.data;
+        const collectionSlug = isCollectionAvailable(collection_slug, this.config.availableCollections);
+        if (!collectionSlug) {
+            return ServerResponse.badRequest("Collection not available for translation");
+        }
+        try {
+            const locales = await computeDocumentStaleness(req.payload, this.config, collectionSlug, collection_id);
+            return ServerResponse.success({
+                locales
+            });
+        } catch (error) {
+            req.payload.logger.error({
+                err: error,
+                collection: collectionSlug,
+                documentId: collection_id,
+                msg: "translator: failed to compute translation staleness"
+            });
+            return ServerResponse.success({
+                locales: []
+            });
+        }
+    }
+}
+
+//# sourceMappingURL=getDocumentStaleness.handler.js.map

package/dist/server/features/staleness/index.d.ts

@@ -0,0 +1,2 @@
+export { createGetDocumentStalenessRoute, createDismissStalenessRoute } from "./route";
+export type { StalenessConfig, StalenessLocaleOutput } from "./model";

package/dist/server/features/staleness/index.js

@@ -0,0 +1,3 @@
+export { createGetDocumentStalenessRoute, createDismissStalenessRoute } from "./route";
+
+//# sourceMappingURL=index.js.map

package/dist/server/features/staleness/model.d.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import type { CollectionSlug } from "payload";
+import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
+import type { ProvenanceStoreFactory } from "../../modules/provenance";
+/**
+ * Route params for reading a document's per-locale staleness.
+ *
+ * `collection_id` accepts any shape Payload allows as a document id — see {@link JobIdSchema}.
+ */
+export declare const GetDocumentStalenessInputSchema: z.ZodObject<{
+    collection_id: z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>, string, string | number>;
+    collection_slug: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    collection_slug: string;
+    collection_id: string;
+}, {
+    collection_slug: string;
+    collection_id: string | number;
+}>;
+/** Body for dismissing (acknowledging) staleness of one target locale. */
+export declare const DismissStalenessInputSchema: z.ZodObject<{
+    collection_id: z.ZodEffects<z.ZodUnion<[z.ZodEffects<z.ZodString, string, string>, z.ZodNumber]>, string, string | number>;
+    collection_slug: z.ZodString;
+    target_lng: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    collection_slug: string;
+    collection_id: string;
+    target_lng: string;
+}, {
+    collection_slug: string;
+    collection_id: string | number;
+    target_lng: string;
+}>;
+/**
+ * Per-locale staleness for one document (snake_case for client compatibility, matching the other
+ * translation endpoints). One entry per target locale that has a provenance record.
+ */
+export type StalenessLocaleOutput = {
+    target_lng: string;
+    source_lng: string;
+    is_stale: boolean;
+    translated_at: string;
+};
+/**
+ * Handler configuration. `provenanceStoreFactory` is absent when provenance is disabled — the
+ * handlers then report no staleness (empty), so the endpoint contract stays stable either way.
+ */
+export type StalenessConfig = {
+    availableCollections: Set<CollectionSlug>;
+    schemaMap: CollectionSchemaMap;
+    provenanceStoreFactory?: ProvenanceStoreFactory;
+};

package/dist/server/features/staleness/model.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { JobIdSchema } from "../../shared";
+/**
+ * Route params for reading a document's per-locale staleness.
+ *
+ * `collection_id` accepts any shape Payload allows as a document id — see {@link JobIdSchema}.
+ */ export const GetDocumentStalenessInputSchema = z.object({
+    collection_id: JobIdSchema,
+    collection_slug: z.string().nonempty()
+});
+/** Body for dismissing (acknowledging) staleness of one target locale. */ export const DismissStalenessInputSchema = z.object({
+    collection_id: JobIdSchema,
+    collection_slug: z.string().nonempty(),
+    target_lng: z.string().nonempty()
+});
+
+//# sourceMappingURL=model.js.map

package/dist/server/features/staleness/route.d.ts

@@ -0,0 +1,7 @@
+import type { Endpoint } from "payload";
+import type { AccessGuard } from "../../shared";
+import type { StalenessConfig } from "./model";
+/** GET per-locale staleness for one document. */
+export declare function createGetDocumentStalenessRoute(config: StalenessConfig, access?: AccessGuard, basePath?: string): Endpoint;
+/** POST to dismiss (acknowledge) staleness of one target locale. */
+export declare function createDismissStalenessRoute(config: StalenessConfig, access?: AccessGuard, basePath?: string): Endpoint;

package/dist/server/features/staleness/route.js

@@ -0,0 +1,21 @@
+import { withErrorHandler, withAccessCheck } from "../../shared";
+import { GetDocumentStalenessHandler } from "./getDocumentStaleness.handler";
+import { DismissStalenessHandler } from "./dismissStaleness.handler";
+/** GET per-locale staleness for one document. */ export function createGetDocumentStalenessRoute(config, access, basePath = "/translate") {
+    const handler = new GetDocumentStalenessHandler(config);
+    return {
+        path: `${basePath}/stale/:collection_slug/:collection_id`,
+        method: "get",
+        handler: withAccessCheck(withErrorHandler(handler.handle.bind(handler)), access)
+    };
+}
+/** POST to dismiss (acknowledge) staleness of one target locale. */ export function createDismissStalenessRoute(config, access, basePath = "/translate") {
+    const handler = new DismissStalenessHandler(config);
+    return {
+        path: `${basePath}/stale/dismiss`,
+        method: "post",
+        handler: withAccessCheck(withErrorHandler(handler.handle.bind(handler)), access)
+    };
+}
+
+//# sourceMappingURL=route.js.map

package/dist/server/features/staleness/service.d.ts

@@ -0,0 +1,15 @@
+import type { CollectionSlug, Payload } from "payload";
+import type { StalenessConfig, StalenessLocaleOutput } from "./model";
+/**
+ * Per-locale staleness for one document: read every provenance record, recompute the current source
+ * fingerprint, and mark each locale stale when the source drifted and the drift was not dismissed.
+ * Returns `[]` when provenance is disabled or the collection has no schema — a normal condition, not
+ * an error (genuine store/fetch failures propagate for the caller to log).
+ */
+export declare function computeDocumentStaleness(payload: Payload, config: StalenessConfig, collection: CollectionSlug, documentId: string): Promise<StalenessLocaleOutput[]>;
+/**
+ * Acknowledge the current source drift for one target locale: recompute the current source
+ * fingerprint (write-path-identical) and persist it as the dismissed fingerprint, so the indicator
+ * hides until the source changes again. No-op when provenance is disabled or the locale has no record.
+ */
+export declare function dismissLocaleStaleness(payload: Payload, config: StalenessConfig, collection: CollectionSlug, documentId: string, targetLocale: string): Promise<void>;

package/dist/server/features/staleness/service.js

@@ -0,0 +1,78 @@
+import { computeSourceFingerprint } from "../../../core/content-projection/computeSourceFingerprint";
+import { isRecordStale } from "../../../core/provenance";
+import { fetchSourceDocument } from "../_lib/sourceDocument";
+/**
+ * Recompute the current source fingerprint the **same way the write path does**. Both sides fetch via
+ * the shared {@link fetchSourceDocument} (identical `depth`/locale shape) and hash with the shared
+ * {@link computeSourceFingerprint} + the same `schemaMap` entry, so an untouched document can never
+ * report stale. Cached per source locale so a document translated from one source into N locales
+ * fetches the source once.
+ */ function makeCurrentFingerprint(payload, collection, documentId, schema) {
+    const cache = new Map();
+    return async (sourceLocale)=>{
+        const cached = cache.get(sourceLocale);
+        if (cached !== undefined) return cached;
+        const sourceData = await fetchSourceDocument(payload, collection, documentId, sourceLocale);
+        const fingerprint = computeSourceFingerprint(sourceData, schema);
+        cache.set(sourceLocale, fingerprint);
+        return fingerprint;
+    };
+}
+/**
+ * Per-locale staleness for one document: read every provenance record, recompute the current source
+ * fingerprint, and mark each locale stale when the source drifted and the drift was not dismissed.
+ * Returns `[]` when provenance is disabled or the collection has no schema — a normal condition, not
+ * an error (genuine store/fetch failures propagate for the caller to log).
+ */ export async function computeDocumentStaleness(payload, config, collection, documentId) {
+    const schema = config.schemaMap.get(collection);
+    if (!config.provenanceStoreFactory || !schema) return [];
+    const store = config.provenanceStoreFactory(payload);
+    const records = await store.findByDocument(collection, documentId);
+    if (records.length === 0) return [];
+    const currentFingerprint = makeCurrentFingerprint(payload, collection, documentId, schema);
+    const locales = [];
+    for (const record of records){
+        try {
+            const current = await currentFingerprint(record.sourceLocale);
+            locales.push({
+                target_lng: record.targetLocale,
+                source_lng: record.sourceLocale,
+                is_stale: isRecordStale(record, current),
+                translated_at: record.translatedAt
+            });
+        } catch (error) {
+            // Isolate per-locale failures (e.g. the record's source locale was removed from Payload's
+            // localization config): skip just this locale so one bad record can't blank the staleness of
+            // every other, still-valid locale on the document.
+            payload.logger.error({
+                err: error,
+                collection,
+                documentId,
+                targetLocale: record.targetLocale,
+                sourceLocale: record.sourceLocale,
+                msg: "translator: failed to compute staleness for locale"
+            });
+        }
+    }
+    return locales;
+}
+/**
+ * Acknowledge the current source drift for one target locale: recompute the current source
+ * fingerprint (write-path-identical) and persist it as the dismissed fingerprint, so the indicator
+ * hides until the source changes again. No-op when provenance is disabled or the locale has no record.
+ */ export async function dismissLocaleStaleness(payload, config, collection, documentId, targetLocale) {
+    const schema = config.schemaMap.get(collection);
+    if (!config.provenanceStoreFactory || !schema) return;
+    const store = config.provenanceStoreFactory(payload);
+    const key = {
+        collectionSlug: collection,
+        documentId,
+        targetLocale
+    };
+    const record = await store.find(key);
+    if (!record) return;
+    const currentFingerprint = makeCurrentFingerprint(payload, collection, documentId, schema);
+    await store.dismiss(key, await currentFingerprint(record.sourceLocale));
+}
+
+//# sourceMappingURL=service.js.map

package/dist/server/features/translate-document/handler.js

@@ -1,6 +1,7 @@
 import { APIError } from "payload";
 import { translateContent } from "../../../core/translation-pipeline";
 import { computeSourceFingerprint } from "../../../core/content-projection/computeSourceFingerprint";
+import { fetchSourceDocument } from "../_lib/sourceDocument";
 /**
  * Translates a single document from source language to target language
  */ export class TranslateDocumentHandler {
@@ -17,12 +18,25 @@ import { computeSourceFingerprint } from "../../../core/content-projection/compu
         // Get original schema (preserves localized: true on nested fields)
         const schema = this.schemaMap.get(collection);
         if (!schema) throw new APIError(`Collection "${collection}" not found in schemaMap`, 400);
-        const sourceData = await payload.findByID({
-            collection,
-            id: collectionId,
-            locale: sourceLng,
-            depth: 0
-        });
+        const sourceData = await fetchSourceDocument(payload, collection, collectionId, sourceLng);
+        // Capture the staleness baseline from the PRISTINE source NOW, before the pipeline runs. The
+        // pipeline translates in place and shares object-valued source leaves (e.g. richText nodes) by
+        // reference with `sourceData`, so fingerprinting after `translateContent` would hash the target
+        // translation — making every fresh translation look immediately stale. Best-effort: a fingerprint
+        // failure logs and skips provenance rather than breaking the translation.
+        let sourceFingerprint = null;
+        if (this.provenanceStoreFactory) {
+            try {
+                sourceFingerprint = computeSourceFingerprint(sourceData, schema);
+            } catch (error) {
+                payload.logger.error({
+                    err: error,
+                    collection,
+                    documentId: String(collectionId),
+                    msg: "translator: failed to fingerprint source for provenance"
+                });
+            }
+        }
         const targetData = await payload.findByID({
             collection,
             id: collectionId,
@@ -44,7 +58,7 @@ import { computeSourceFingerprint } from "../../../core/content-projection/compu
         };
         const collectionConfig = payload.collections[collection].config;
         await this.saveTranslatedDocument(payload, collection, collectionId, translatedData, targetLng, sourceLng, collectionConfig, publishOnTranslation);
-        if (this.provenanceStoreFactory) {
+        if (this.provenanceStoreFactory && sourceFingerprint !== null) {
             const store = this.provenanceStoreFactory(payload);
             try {
                 await store.upsert({
@@ -52,7 +66,7 @@ import { computeSourceFingerprint } from "../../../core/content-projection/compu
                     documentId: String(collectionId),
                     targetLocale: targetLng,
                     sourceLocale: sourceLng,
-                    sourceFingerprint: computeSourceFingerprint(sourceData, schema),
+                    sourceFingerprint,
                     translatedAt: new Date().toISOString(),
                     dismissedFingerprint: null
                 });

package/dist/server/modules/provenance/PayloadProvenanceStore.d.ts

@@ -16,6 +16,8 @@ export declare class PayloadProvenanceStore implements ProvenanceStore {
     constructor(payload: Payload, slug: string);
     upsert(record: TranslationProvenanceRecord): Promise<void>;
     find(key: ProvenanceKey): Promise<TranslationProvenanceRecord | null>;
+    findByDocument(collectionSlug: string, documentId: string): Promise<TranslationProvenanceRecord[]>;
+    dismiss(key: ProvenanceKey, dismissedFingerprint: string): Promise<void>;
     deleteByDocument(collectionSlug: string, documentId: string): Promise<void>;
     private findDoc;
 }

package/dist/server/modules/provenance/PayloadProvenanceStore.js

@@ -1,3 +1,19 @@
+function documentWhere(collectionSlug, documentId) {
+    return {
+        and: [
+            {
+                collectionSlug: {
+                    equals: collectionSlug
+                }
+            },
+            {
+                documentId: {
+                    equals: documentId
+                }
+            }
+        ]
+    };
+}
 function keyWhere(key) {
     return {
         and: [
@@ -75,23 +91,30 @@ function toRecord(doc) {
         const doc = await this.findDoc(key);
         return doc === null ? null : toRecord(doc);
     }
+    async findByDocument(collectionSlug, documentId) {
+        const result = await this.payload.find({
+            collection: this.collection,
+            where: documentWhere(collectionSlug, documentId),
+            depth: 0,
+            pagination: false
+        });
+        return result.docs.map(toRecord);
+    }
+    async dismiss(key, dismissedFingerprint) {
+        const existing = await this.findDoc(key);
+        if (existing === null) return;
+        await this.payload.update({
+            collection: this.collection,
+            id: existing.id,
+            data: {
+                dismissedFingerprint
+            }
+        });
+    }
     async deleteByDocument(collectionSlug, documentId) {
         await this.payload.delete({
             collection: this.collection,
-            where: {
-                and: [
-                    {
-                        collectionSlug: {
-                            equals: collectionSlug
-                        }
-                    },
-                    {
-                        documentId: {
-                            equals: documentId
-                        }
-                    }
-                ]
-            }
+            where: documentWhere(collectionSlug, documentId)
         });
     }
     async findDoc(key) {

package/dist/server/modules/translation-levels/PluginConfigBuilder.d.ts

@@ -4,6 +4,7 @@ import type { RawPayloadComponentExport } from "../../../types/PayloadComponentE
 import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
 import type { TranslationProvider } from "../../../core/translation-providers";
 import type { TaskRunnerFactory } from "../task-runner";
+import type { ProvenanceStoreFactory } from "../provenance";
 import type { CollectionAdminSlot, LevelContext } from "./types";
 type ConfigModifier = (config: Config) => Config;
 export type PluginConfigBuilderDeps = {
@@ -13,6 +14,7 @@ export type PluginConfigBuilderDeps = {
     taskRunnerFactory: TaskRunnerFactory;
     schemaMap: CollectionSchemaMap;
     translationProvider: TranslationProvider;
+    provenanceStoreFactory?: ProvenanceStoreFactory;
 };
 /**
  * The single place that mutates the Payload `config`. Levels (through the narrow
@@ -32,6 +34,7 @@ export declare class PluginConfigBuilder implements LevelContext {
     readonly taskRunnerFactory: TaskRunnerFactory;
     readonly schemaMap: CollectionSchemaMap;
     readonly translationProvider: TranslationProvider;
+    readonly provenanceStoreFactory?: ProvenanceStoreFactory;
     private readonly endpoints;
     private readonly collectionComponents;
     private readonly adminProviders;

package/dist/server/modules/translation-levels/PluginConfigBuilder.js

@@ -34,6 +34,7 @@ function attachToSlot(collection, slot, component) {
     taskRunnerFactory;
     schemaMap;
     translationProvider;
+    provenanceStoreFactory;
     endpoints = [];
     collectionComponents = [];
     adminProviders = [];
@@ -45,6 +46,7 @@ function attachToSlot(collection, slot, component) {
         this.taskRunnerFactory = deps.taskRunnerFactory;
         this.schemaMap = deps.schemaMap;
         this.translationProvider = deps.translationProvider;
+        this.provenanceStoreFactory = deps.provenanceStoreFactory;
     }
     addEndpoints(endpoints) {
         this.endpoints.push(...endpoints);

package/dist/server/modules/translation-levels/types.d.ts

@@ -4,6 +4,7 @@ import type { RawPayloadComponentExport } from "../../../types/PayloadComponentE
 import type { CollectionSchemaMap } from "../../../types/CollectionSchemaMap";
 import type { TranslationProvider } from "../../../core/translation-providers";
 import type { TaskRunnerFactory } from "../task-runner";
+import type { ProvenanceStoreFactory } from "../provenance";
 export type CollectionAdminSlot = "beforeDocumentControls" | "beforeListTable";
 /**
  * A composable translation surface (document / collection / field).
@@ -40,6 +41,8 @@ export interface LevelContext {
     readonly schemaMap: CollectionSchemaMap;
     /** The configured translation backend (used by the synchronous field level). */
     readonly translationProvider: TranslationProvider;
+    /** Builds a provenance store; absent when provenance is disabled (staleness then reports empty). */
+    readonly provenanceStoreFactory?: ProvenanceStoreFactory;
     /** Register endpoints. Deduplicated by method + path when applied. */
     addEndpoints(endpoints: Endpoint[]): void;
     /** Attach an admin component to a slot on every managed collection. */

package/dist/server/shared/http/index.d.ts

@@ -1,3 +1,4 @@
 export { ServerResponse } from "./ServerResponse";
 export { withErrorHandler } from "./withErrorHandler";
 export { withAccessCheck } from "./withAccessCheck";
+export { toClientErrorMessage, GENERIC_TRANSLATION_ERROR } from "./toClientErrorMessage";

package/dist/server/shared/http/index.js

@@ -1,5 +1,6 @@
 export { ServerResponse } from "./ServerResponse";
 export { withErrorHandler } from "./withErrorHandler";
 export { withAccessCheck } from "./withAccessCheck";
+export { toClientErrorMessage, GENERIC_TRANSLATION_ERROR } from "./toClientErrorMessage";
 
 //# sourceMappingURL=index.js.map

package/dist/server/shared/http/toClientErrorMessage.d.ts

@@ -0,0 +1,15 @@
+/** Shown to the browser instead of a raw provider/runtime error outside development. */
+export declare const GENERIC_TRANSLATION_ERROR = "Translation failed. See the server logs for details.";
+/**
+ * Collapse a server-side error message to something safe to send to the browser.
+ *
+ * Provider/runtime errors (e.g. `401 Incorrect API key provided: sk-proj-…`) leak implementation
+ * detail — and sometimes secrets — so the client must not see them in production. The full error
+ * still lives in the job record and server logs for debugging; only the client-facing copy is
+ * collapsed. Fail-safe: the raw message passes through solely in `development`/`test`; every other
+ * environment (including an unset `NODE_ENV`) returns {@link GENERIC_TRANSLATION_ERROR}.
+ *
+ * @param message - The raw server-side error message, if any.
+ * @returns The raw message in a debug environment, otherwise the generic text.
+ */
+export declare function toClientErrorMessage(message?: string): string;