@focus-reactive/payload-plugin-translator 0.11.4 → 0.12.0

package/README.md

@@ -340,7 +340,7 @@ Pass **either** an `apiKey` **or** a ready-made `client` — never both; the typ
 | -------------- | ------------------------- | ------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------- |
 | `apiKey`       | `string`                  | Unless `client`    | —                    | OpenAI API key. The `openai` package is loaded on first translation, not at config load. _Since v0.11.0: optional when `client` is given._ |
 | `client`       | `OpenAIClientShape`       | Unless `apiKey`    | —                    | Your own client — Azure OpenAI, a corporate proxy, OpenRouter, anything with a matching `chat.completions.create`. On this path the `openai` package is never loaded. _Since v0.11.0._ |
-| `model`        | `string`                  | No                 | `'gpt-4o'`           | Model used for translation. **The default may change in a minor release** — pin it if you need reproducible output and cost. |
+| `model`        | `string`                  | No                 | `'gpt-5.4-mini'`     | Model used for translation. **The default may change in a minor release** — pin it if you need reproducible output and cost. |
 | `systemPrompt` | `SystemPromptBuilder`     | No                 | Built-in prompt      | Custom system-prompt builder.                                                                                   |
 | `dryRun`       | `boolean \| DryRunConfig` | No                 | `false`              | **Deprecated** — see the note below. Simulates translations without API calls, but still writes, publishes and records provenance. |
 | `sampling`     | `OpenAISamplingParams`    | No                 | not sent             | `temperature`, `top_p`, `frequency_penalty`, `presence_penalty`. Omitted entirely unless set — several models reject them. **Before v0.11.0 this package always sent `temperature: 0, top_p: 1, frequency_penalty: 0, presence_penalty: 0`**, so translations were deterministic; they now follow the model's defaults. Set `{ temperature: 0 }` to restore that. _Since v0.11.0._ |

package/dist/core/domain/translation-providers/failureReason.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Payload's job queue keeps only the message: it rethrows a handler failure as
+ * `new TaskError({ message: err.message })` and persists `{ name, cancelled, message, stack }`,
+ * so the error's class, `code` and `cause` are gone before anything is stored (Payload 3.x).
+ * That is why a reason travels inside the string rather than as an error subclass or a field.
+ */
+/** A failure cause safe to name to an end user. Every member obliges admin-facing copy for it. */
+export type UserFacingFailureReason = "model-unavailable";
+/** `detail` is for logs and the job record; it is never shown to a user. */
+export declare function markFailureReason(reason: UserFacingFailureReason, detail: string): string;
+/** Anchored: a marked message quoted inside another error's text is not that error's own reason. */
+export declare function readFailureReason(message: string): UserFacingFailureReason | null;

package/dist/core/domain/translation-providers/failureReason.js

@@ -0,0 +1,21 @@
+/**
+ * Payload's job queue keeps only the message: it rethrows a handler failure as
+ * `new TaskError({ message: err.message })` and persists `{ name, cancelled, message, stack }`,
+ * so the error's class, `code` and `cause` are gone before anything is stored (Payload 3.x).
+ * That is why a reason travels inside the string rather than as an error subclass or a field.
+ */ /** A failure cause safe to name to an end user. Every member obliges admin-facing copy for it. */ const MARKER_PREFIX = "translator:";
+const MARKER = new RegExp(`^\\[${MARKER_PREFIX}([a-z-]+)\\] `, "u");
+const REASONS = new Set([
+    "model-unavailable"
+]);
+const isUserFacingFailureReason = (value)=>REASONS.has(value);
+/** `detail` is for logs and the job record; it is never shown to a user. */ export function markFailureReason(reason, detail) {
+    return `[${MARKER_PREFIX}${reason}] ${detail}`;
+}
+/** Anchored: a marked message quoted inside another error's text is not that error's own reason. */ export function readFailureReason(message) {
+    const match = MARKER.exec(message);
+    const reason = match?.[1];
+    return reason !== undefined && isUserFacingFailureReason(reason) ? reason : null;
+}
+
+//# sourceMappingURL=failureReason.js.map

package/dist/core/translation-pipeline/stages/field-collector/FieldChunkCollector.js

@@ -116,8 +116,11 @@ const asObject = (value)=>isObject(value) ? value : {};
             target: this.targetData,
             path: []
         }, walker);
+        // A detached copy, because write-back mutates an object-valued leaf (a rich-text tree) in
+        // place: seating the caller's own object here would translate their source document. Scalars
+        // are immutable, so they are seated as they are.
         for (const { dataRef, key, sourceValue } of selected){
-            dataRef[key] = sourceValue;
+            dataRef[key] = isObject(sourceValue) ? structuredClone(sourceValue) : sourceValue;
         }
         return chunks;
     }

package/dist/server/modules/provenance/Provenance.service.d.ts

@@ -25,9 +25,12 @@ export declare class ProvenanceService {
     private readonly schemaMap;
     constructor(payload: Payload, store: ProvenanceStore, schemaMap: CollectionSchemaMap);
     /**
-     * Hash the PRISTINE source. The caller MUST pass source fetched **before** the translation pipeline
-     * runs — the pipeline mutates object-valued leaves (e.g. richText nodes) in place, so hashing after
-     * it would capture the target translation and make every fresh translation look instantly stale.
+     * Hash the source the translation was made from — the baseline staleness is later measured against.
+     *
+     * Ordering used to matter: the pipeline wrote into object-valued leaves it shared with the caller's
+     * source, so hashing afterwards captured the translation and reported every fresh translation as
+     * stale. It now detaches those leaves, so this may be called on either side of the pipeline.
+     *
      * Returns `null` on any failure (no schema, hashing error) so provenance is skipped, not the translation.
      */
     captureFingerprint(collection: CollectionSlug, sourceData: Record<string, unknown>): string | null;

package/dist/server/modules/provenance/Provenance.service.js

@@ -19,9 +19,12 @@ import { fetchSourceDocument } from "../../shared/payload/sourceDocument";
         this.schemaMap = schemaMap;
     }
     /**
-   * Hash the PRISTINE source. The caller MUST pass source fetched **before** the translation pipeline
-   * runs — the pipeline mutates object-valued leaves (e.g. richText nodes) in place, so hashing after
-   * it would capture the target translation and make every fresh translation look instantly stale.
+   * Hash the source the translation was made from — the baseline staleness is later measured against.
+   *
+   * Ordering used to matter: the pipeline wrote into object-valued leaves it shared with the caller's
+   * source, so hashing afterwards captured the translation and reported every fresh translation as
+   * stale. It now detaches those leaves, so this may be called on either side of the pipeline.
+   *
    * Returns `null` on any failure (no schema, hashing error) so provenance is skipped, not the translation.
    */ captureFingerprint(collection, sourceData) {
         const schema = this.schemaMap.get(collection);

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

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

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

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

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

@@ -1,3 +1,5 @@
+/** Call this on any message before it reaches a user — see {@link REASON_TEXT}. */
+export declare function failureReasonText(message?: string): string | null;
 /** 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.";
 /**
@@ -5,11 +7,12 @@ export declare const GENERIC_TRANSLATION_ERROR = "Translation failed. See the se
  *
  * 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}.
+ * still lives in the job record and server logs for debugging. Fail-safe: outside
+ * `development`/`test` (including an unset `NODE_ENV`) the raw message never leaves this function.
+ * A message carrying a failure reason is answered from this file's own catalogue instead, in every
+ * environment, and its tail is never shown.
  *
  * @param message - The raw server-side error message, if any.
- * @returns The raw message in a debug environment, otherwise the generic text.
+ * @returns The raw message in a debug environment, otherwise the generic text or a reason's copy.
  */
 export declare function toClientErrorMessage(message?: string): string;

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

@@ -1,3 +1,11 @@
+import { readFailureReason } from "../../../core/domain/translation-providers/failureReason";
+/** Re-authored here, never taken from the error: only text this file owns is free of vendor detail. */ const REASON_TEXT = {
+    "model-unavailable": "The configured translation model is not available to this API key. Set `model` in the provider configuration to one your key can use."
+};
+/** Call this on any message before it reaches a user — see {@link REASON_TEXT}. */ export function failureReasonText(message) {
+    const reason = message === undefined ? null : readFailureReason(message);
+    return reason === null ? null : REASON_TEXT[reason];
+}
 /** Shown to the browser instead of a raw provider/runtime error outside development. */ export const GENERIC_TRANSLATION_ERROR = "Translation failed. See the server logs for details.";
 // Only these environments get the raw message as a debug aid. Anything else — production, an unset
 // or misconfigured NODE_ENV — is treated as "not debug", so the default is the safe, generic text.
@@ -10,13 +18,16 @@ const DEBUG_ENVS = new Set([
  *
  * 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}.
+ * still lives in the job record and server logs for debugging. Fail-safe: outside
+ * `development`/`test` (including an unset `NODE_ENV`) the raw message never leaves this function.
+ * A message carrying a failure reason is answered from this file's own catalogue instead, in every
+ * environment, and its tail is never shown.
  *
  * @param message - The raw server-side error message, if any.
- * @returns The raw message in a debug environment, otherwise the generic text.
+ * @returns The raw message in a debug environment, otherwise the generic text or a reason's copy.
  */ export function toClientErrorMessage(message) {
+    const reasonText = failureReasonText(message);
+    if (reasonText !== null) return reasonText;
     if (DEBUG_ENVS.has(process.env.NODE_ENV ?? "")) {
         return message?.trim() || GENERIC_TRANSLATION_ERROR;
     }

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

@@ -1,5 +1,6 @@
 import { APIError } from "payload";
 import { ServerResponse } from "./ServerResponse";
+import { failureReasonText } from "./toClientErrorMessage";
 /**
  * Wraps async handler with error handling.
  * Catches APIError and generic Error, returns appropriate HTTP response.
@@ -13,7 +14,7 @@ import { ServerResponse } from "./ServerResponse";
                 return ServerResponse.custom(e.message, e.status);
             }
             if (e instanceof Error) {
-                return ServerResponse.internalServerError(e.message);
+                return ServerResponse.internalServerError(failureReasonText(e.message) ?? e.message);
             }
             return ServerResponse.internalServerError();
         }

package/dist/translation-providers/openai/OpenAITranslation.provider.d.ts

@@ -6,7 +6,7 @@ type OpenAIProviderBase = {
     /**
      * Model used for translation.
      *
-     * @default 'gpt-4o' — may move in a minor release; pin it if you need reproducibility.
+     * @default 'gpt-5.4-mini' — may move in a minor release; pin it if you need reproducibility.
      */
     model?: string;
     /**

package/dist/translation-providers/openai/OpenAITranslation.provider.js

@@ -1,7 +1,7 @@
 import { createTranslationProvider } from "../shared";
 import { loadOpenAIClient } from "./loadOpenAIClient";
 import { openAIComplete } from "./openAIComplete";
-const DEFAULT_MODEL = "gpt-4o";
+const DEFAULT_MODEL = "gpt-5.4-mini";
 /** The SDK's own default is ten minutes — far too long when a translation blocks a live editor request. */ const DEFAULT_TIMEOUT_MS = 60_000;
 /**
  * Creates an OpenAI translation provider.

package/dist/translation-providers/openai/openAIComplete.js

@@ -1,3 +1,5 @@
+import { markFailureReason } from "../../core/domain/translation-providers/failureReason";
+import { isObject } from "../../core/kernel/utils/isObject";
 import { errorMessageLower, NoContentError, ProviderConfigurationError } from "../shared";
 const SCHEMA_NAME = "translation";
 /**
@@ -16,6 +18,17 @@ const SCHEMA_NAME = "translation";
     if (text.includes("invalid schema")) return "schema-rejected";
     return null;
 }
+const MODEL_ACCESS_CODE = "model_not_found";
+/**
+ * Only for a gateway that forwards the text and no `code` — Azure, OpenRouter, a corporate proxy.
+ * A full phrase rather than the word `model`, which such a gateway also echoes in rate limits.
+ * Wording as observed 2026-09; the code above is what carries this when OpenAI rewords it.
+ */ const MODEL_ACCESS_PHRASE = "does not exist or you do not have access";
+function isModelAccessFailure(cause) {
+    if (isObject(cause) && cause.code === MODEL_ACCESS_CODE) return true;
+    const text = errorMessageLower(cause);
+    return text !== null && text.includes(MODEL_ACCESS_PHRASE);
+}
 /**
  * The vendor boundary: the only place OpenAI's response shape is read.
  *
@@ -60,6 +73,11 @@ const SCHEMA_NAME = "translation";
                 signal
             });
         } catch (cause) {
+            if (isModelAccessFailure(cause)) {
+                throw new ProviderConfigurationError(markFailureReason("model-unavailable", `The model "${model}" is not available to this API key. Pass \`model\` in the provider configuration to pin one your key can use.`), {
+                    cause
+                });
+            }
             const rejection = structuredOutput === "json_schema" ? classifySchemaRejection(cause) : null;
             if (rejection === "model-does-not-support") {
                 throw new ProviderConfigurationError(`The model "${model}" does not support the json_schema response format. Pass structuredOutput: "json_object", or choose a model that supports structured outputs.`, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@focus-reactive/payload-plugin-translator",
-  "version": "0.11.4",
+  "version": "0.12.0",
   "description": "Translation plugin for Payload CMS 3.x. Automatically translate your localized content using any translation provider.",
   "type": "module",
   "license": "MIT",