@focus-reactive/payload-plugin-translator 0.10.4 → 0.11.0

package/dist/translation-providers/shared/buildSystemPrompt.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Context handed to a {@link SystemPromptBuilder}.
+ *
+ * @since 0.11.0
+ */
+export type SystemPromptContext = {
+    /** Source language code (e.g. 'en', 'de'). Empty when the provider should auto-detect. */
+    sourceLang: string;
+    targetLang: string;
+    defaultPrompt: string;
+};
+/**
+ * Builds a custom system prompt for translation.
+ *
+ * @since 0.11.0
+ */
+export type SystemPromptBuilder = (context: SystemPromptContext) => string;
+/**
+ * Produces the system prompt sent with a translation request.
+ *
+ * The default wording is handed to `systemPrompt` builders as `defaultPrompt`, so consumers extend
+ * this exact string — changing it changes every custom prompt built on it.
+ */
+export declare function buildSystemPrompt(args: {
+    sourceLng: string;
+    targetLng: string;
+    override?: SystemPromptBuilder;
+}): string;

package/dist/translation-providers/shared/buildSystemPrompt.js

@@ -0,0 +1,25 @@
+/**
+ * Context handed to a {@link SystemPromptBuilder}.
+ *
+ * @since 0.11.0
+ */ /**
+ * Produces the system prompt sent with a translation request.
+ *
+ * The default wording is handed to `systemPrompt` builders as `defaultPrompt`, so consumers extend
+ * this exact string — changing it changes every custom prompt built on it.
+ */ export function buildSystemPrompt(args) {
+    const { sourceLng, targetLng, override } = args;
+    const defaultPrompt = `Translate the values from the JSON that the user will send you${sourceLng ? ` from ${sourceLng}` : ""} into ${targetLng}. Keep all JSON keys exactly as they are, only translate the values.
+The response should be a valid JSON object with the same structure and keys as the input, but with translated values.
+Maintain any special formatting, placeholders, or variables within the values if they exist.`;
+    if (override) {
+        return override({
+            sourceLang: sourceLng,
+            targetLang: targetLng,
+            defaultPrompt
+        });
+    }
+    return defaultPrompt;
+}
+
+//# sourceMappingURL=buildSystemPrompt.js.map

package/dist/translation-providers/shared/errors/KeySetMismatchError.d.ts

@@ -0,0 +1,15 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * Nothing in the reply could be applied — either its keys did not overlap the input's, or they did
+ * and none of the values was a string. A partial gap is not an error; see `parseAndValidateReply`.
+ *
+ * @since 0.11.0
+ */
+export declare class KeySetMismatchError extends TranslationProviderError {
+    readonly code: "key-set-mismatch";
+    /** Input keys left without a usable translation. */
+    readonly missingInputKeys: number[];
+    /** Keys the reply carried but nobody asked for — model output, so untrusted text. */
+    readonly unrequestedReplyKeys: string[];
+    constructor(message: string, missingInputKeys: number[], unrequestedReplyKeys: string[], options?: ErrorOptions);
+}

package/dist/translation-providers/shared/errors/KeySetMismatchError.js

@@ -0,0 +1,26 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * Nothing in the reply could be applied — either its keys did not overlap the input's, or they did
+ * and none of the values was a string. A partial gap is not an error; see `parseAndValidateReply`.
+ *
+ * @since 0.11.0
+ */ export class KeySetMismatchError extends TranslationProviderError {
+    code = "key-set-mismatch";
+    /** Input keys left without a usable translation. */ missingInputKeys;
+    /** Keys the reply carried but nobody asked for — model output, so untrusted text. */ unrequestedReplyKeys;
+    constructor(message, missingInputKeys, unrequestedReplyKeys, options){
+        super(message, options);
+        this.missingInputKeys = missingInputKeys;
+        this.unrequestedReplyKeys = unrequestedReplyKeys;
+        // Model-invented strings: enumerable, they would land in `JSON.stringify(error)` and every
+        // structured logger.
+        Object.defineProperty(this, "missingInputKeys", {
+            enumerable: false
+        });
+        Object.defineProperty(this, "unrequestedReplyKeys", {
+            enumerable: false
+        });
+    }
+}
+
+//# sourceMappingURL=KeySetMismatchError.js.map

package/dist/translation-providers/shared/errors/NoContentError.d.ts

@@ -0,0 +1,9 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The provider produced no usable text — an empty reply, or a response the vendor filtered.
+ *
+ * @since 0.11.0
+ */
+export declare class NoContentError extends TranslationProviderError {
+    readonly code: "no-content";
+}

package/dist/translation-providers/shared/errors/NoContentError.js

@@ -0,0 +1,10 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The provider produced no usable text — an empty reply, or a response the vendor filtered.
+ *
+ * @since 0.11.0
+ */ export class NoContentError extends TranslationProviderError {
+    code = "no-content";
+}
+
+//# sourceMappingURL=NoContentError.js.map

package/dist/translation-providers/shared/errors/ProviderConfigurationError.d.ts

@@ -0,0 +1,10 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The provider is configured in a way that cannot work — most often an optional SDK that is not
+ * installed.
+ *
+ * @since 0.11.0
+ */
+export declare class ProviderConfigurationError extends TranslationProviderError {
+    readonly code: "config";
+}

package/dist/translation-providers/shared/errors/ProviderConfigurationError.js

@@ -0,0 +1,11 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The provider is configured in a way that cannot work — most often an optional SDK that is not
+ * installed.
+ *
+ * @since 0.11.0
+ */ export class ProviderConfigurationError extends TranslationProviderError {
+    code = "config";
+}
+
+//# sourceMappingURL=ProviderConfigurationError.js.map

package/dist/translation-providers/shared/errors/TranslationProviderError.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Failure causes a translation provider can report.
+ *
+ * @since 0.11.0
+ */
+export type TranslationFailureCode = "no-content" | "unparseable-reply" | "key-set-mismatch" | "transport" | "config";
+/**
+ * Base class for every failure a built-in translation provider reports.
+ *
+ * The original failure travels on `cause` and is never interpolated into `message`: a vendor SDK
+ * error can carry an API key, and `message` reaches an HTTP response body.
+ *
+ * @since 0.11.0
+ */
+export declare abstract class TranslationProviderError extends Error {
+    abstract readonly code: TranslationFailureCode;
+    constructor(message: string, options?: ErrorOptions);
+}

package/dist/translation-providers/shared/errors/TranslationProviderError.js

@@ -0,0 +1,21 @@
+/**
+ * Failure causes a translation provider can report.
+ *
+ * @since 0.11.0
+ */ /**
+ * Base class for every failure a built-in translation provider reports.
+ *
+ * The original failure travels on `cause` and is never interpolated into `message`: a vendor SDK
+ * error can carry an API key, and `message` reaches an HTTP response body.
+ *
+ * @since 0.11.0
+ */ export class TranslationProviderError extends Error {
+    constructor(message, options){
+        // Never `this.cause = cause`: an assigned property is enumerable, so JSON.stringify and pino
+        // serialize the vendor error whole — headers and API key with it. `super` installs it non-enumerably.
+        super(message, options);
+        this.name = new.target.name;
+    }
+}
+
+//# sourceMappingURL=TranslationProviderError.js.map

package/dist/translation-providers/shared/errors/TransportError.d.ts

@@ -0,0 +1,10 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The call to the provider failed — network, auth, rate limit, timeout. The vendor's own error is on
+ * `cause`.
+ *
+ * @since 0.11.0
+ */
+export declare class TransportError extends TranslationProviderError {
+    readonly code: "transport";
+}

package/dist/translation-providers/shared/errors/TransportError.js

@@ -0,0 +1,11 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The call to the provider failed — network, auth, rate limit, timeout. The vendor's own error is on
+ * `cause`.
+ *
+ * @since 0.11.0
+ */ export class TransportError extends TranslationProviderError {
+    code = "transport";
+}
+
+//# sourceMappingURL=TransportError.js.map

package/dist/translation-providers/shared/errors/UnparseableReplyError.d.ts

@@ -0,0 +1,9 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The reply was not JSON, or parsed to something that is not an object — arrays included.
+ *
+ * @since 0.11.0
+ */
+export declare class UnparseableReplyError extends TranslationProviderError {
+    readonly code: "unparseable-reply";
+}

package/dist/translation-providers/shared/errors/UnparseableReplyError.js

@@ -0,0 +1,10 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * The reply was not JSON, or parsed to something that is not an object — arrays included.
+ *
+ * @since 0.11.0
+ */ export class UnparseableReplyError extends TranslationProviderError {
+    code = "unparseable-reply";
+}
+
+//# sourceMappingURL=UnparseableReplyError.js.map

package/dist/translation-providers/shared/errors/errorMessageLower.d.ts

@@ -0,0 +1 @@
+export declare function errorMessageLower(cause: unknown): string | null;

package/dist/translation-providers/shared/errors/errorMessageLower.js

@@ -0,0 +1,8 @@
+import { isObject } from "../../../core/kernel/utils/isObject";
+export function errorMessageLower(cause) {
+    if (!isObject(cause)) return null;
+    const message = cause.message;
+    return typeof message === "string" ? message.toLowerCase() : null;
+}
+
+//# sourceMappingURL=errorMessageLower.js.map

package/dist/translation-providers/shared/errors/index.d.ts

@@ -0,0 +1,9 @@
+export { TranslationProviderError } from "./TranslationProviderError";
+export type { TranslationFailureCode } from "./TranslationProviderError";
+export { NoContentError } from "./NoContentError";
+export { UnparseableReplyError } from "./UnparseableReplyError";
+export { KeySetMismatchError } from "./KeySetMismatchError";
+export { TransportError } from "./TransportError";
+export { ProviderConfigurationError } from "./ProviderConfigurationError";
+export { wrapTransportError } from "./wrapTransportError";
+export { errorMessageLower } from "./errorMessageLower";

package/dist/translation-providers/shared/errors/index.js

@@ -0,0 +1,10 @@
+export { TranslationProviderError } from "./TranslationProviderError";
+export { NoContentError } from "./NoContentError";
+export { UnparseableReplyError } from "./UnparseableReplyError";
+export { KeySetMismatchError } from "./KeySetMismatchError";
+export { TransportError } from "./TransportError";
+export { ProviderConfigurationError } from "./ProviderConfigurationError";
+export { wrapTransportError } from "./wrapTransportError";
+export { errorMessageLower } from "./errorMessageLower";
+
+//# sourceMappingURL=index.js.map

package/dist/translation-providers/shared/errors/wrapTransportError.d.ts

@@ -0,0 +1,7 @@
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * Turns anything a transport threw into a {@link TransportError}, keeping the original on `cause`.
+ * A value that is already one of ours passes through: re-wrapping would bury a specific cause under
+ * a generic transport failure.
+ */
+export declare function wrapTransportError(cause: unknown): TranslationProviderError;

package/dist/translation-providers/shared/errors/wrapTransportError.js

@@ -0,0 +1,14 @@
+import { TransportError } from "./TransportError";
+import { TranslationProviderError } from "./TranslationProviderError";
+/**
+ * Turns anything a transport threw into a {@link TransportError}, keeping the original on `cause`.
+ * A value that is already one of ours passes through: re-wrapping would bury a specific cause under
+ * a generic transport failure.
+ */ export function wrapTransportError(cause) {
+    if (cause instanceof TranslationProviderError) return cause;
+    return new TransportError("The translation request failed before a reply could be read. The provider's own error is on this error's `cause` property.", {
+        cause
+    });
+}
+
+//# sourceMappingURL=wrapTransportError.js.map

package/dist/translation-providers/shared/index.d.ts

@@ -0,0 +1,8 @@
+export { createTranslationProvider } from "./CompletionProvider.provider";
+export type { CompletionFn, CompletionRequest, TranslationProviderConfig, } from "./CompletionProvider.provider";
+export type { JsonSchemaObject } from "./buildResponseSchema";
+export type { SystemPromptBuilder, SystemPromptContext } from "./buildSystemPrompt";
+export type { DryRunConfig, DryRunTransformer } from "./runDryRun";
+export { errorMessageLower } from "./errors";
+export { TranslationProviderError, NoContentError, UnparseableReplyError, KeySetMismatchError, TransportError, ProviderConfigurationError, } from "./errors";
+export type { TranslationFailureCode } from "./errors";

package/dist/translation-providers/shared/index.js

@@ -0,0 +1,5 @@
+export { createTranslationProvider } from "./CompletionProvider.provider";
+export { errorMessageLower } from "./errors";
+export { TranslationProviderError, NoContentError, UnparseableReplyError, KeySetMismatchError, TransportError, ProviderConfigurationError } from "./errors";
+
+//# sourceMappingURL=index.js.map

package/dist/translation-providers/shared/parseAndValidateReply.d.ts

@@ -0,0 +1,13 @@
+import type { TranslationInput, TranslationOutput } from "../../core/domain/translation-providers";
+export type ParsedReply = {
+    translations: TranslationOutput;
+    missingInputKeys: number[];
+    unrequestedReplyKeys: string[];
+};
+/**
+ * Parses an untrusted reply into a {@link TranslationOutput} and reports the key-set gap.
+ *
+ * A partial answer is applied, not rejected — the gap is returned so the caller can report it. Only
+ * a reply that answers nothing is a failure ({@link KeySetMismatchError}).
+ */
+export declare function parseAndValidateReply(input: TranslationInput, raw: string): ParsedReply;

package/dist/translation-providers/shared/parseAndValidateReply.js

@@ -0,0 +1,46 @@
+import { isObject } from "../../core/kernel/utils/isObject";
+import { KeySetMismatchError, UnparseableReplyError } from "./errors";
+/**
+ * Parses an untrusted reply into a {@link TranslationOutput} and reports the key-set gap.
+ *
+ * A partial answer is applied, not rejected — the gap is returned so the caller can report it. Only
+ * a reply that answers nothing is a failure ({@link KeySetMismatchError}).
+ */ export function parseAndValidateReply(input, raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (cause) {
+        throw new UnparseableReplyError("The provider's reply was not valid JSON.", {
+            cause
+        });
+    }
+    // `isObject` admits arrays: `["a"]` has key "0", so a 0-based input would accept it by coincidence.
+    if (!isObject(parsed) || Array.isArray(parsed)) {
+        throw new UnparseableReplyError("The provider's reply was JSON, but not an object.");
+    }
+    const expectedKeys = new Set(Object.keys(input));
+    const translations = {};
+    const missingInputKeys = [];
+    for (const key of expectedKeys){
+        const value = parsed[key];
+        if (typeof value === "string") {
+            translations[Number(key)] = value;
+        } else {
+            missingInputKeys.push(Number(key));
+        }
+    }
+    const unrequestedReplyKeys = Object.keys(parsed).filter((key)=>!expectedKeys.has(key));
+    if (expectedKeys.size > 0 && Object.keys(translations).length === 0) {
+        const answeredAnyKey = [
+            ...expectedKeys
+        ].some((key)=>Object.hasOwn(parsed, key));
+        throw new KeySetMismatchError(answeredAnyKey ? `The provider's reply carried the requested keys, but none of the ${expectedKeys.size} values was a string.` : `The provider's reply answered none of the ${expectedKeys.size} requested keys.`, missingInputKeys, unrequestedReplyKeys);
+    }
+    return {
+        translations,
+        missingInputKeys,
+        unrequestedReplyKeys
+    };
+}
+
+//# sourceMappingURL=parseAndValidateReply.js.map

package/dist/translation-providers/shared/runDryRun.d.ts

@@ -0,0 +1,20 @@
+import type { TranslationInput, TranslationOutput } from "../../core/domain/translation-providers";
+export type DryRunTransformer = (text: string) => string | Promise<string>;
+/**
+ * Dry-run configuration: a transformer, and optionally a delay that imitates network latency.
+ *
+ * @deprecated Supply your own fake `complete` instead. Remove in next major.
+ * See docs/DEPRECATIONS.md#provider-dry-run
+ */
+export type DryRunConfig = {
+    /** Applied to every non-blank value. */
+    transform: DryRunTransformer;
+    /** Milliseconds to wait before returning. */
+    timeout?: number;
+};
+/**
+ * Simulates a translation without calling anything. Blank values pass through untouched.
+ *
+ * Logs the field count and never field content: the log reaches shared infrastructure.
+ */
+export declare function runDryRun(input: TranslationInput, config: boolean | DryRunConfig): Promise<TranslationOutput>;

package/dist/translation-providers/shared/runDryRun.js

@@ -0,0 +1,17 @@
+const reverse = (text)=>text.split("").reverse().join("");
+/**
+ * Simulates a translation without calling anything. Blank values pass through untouched.
+ *
+ * Logs the field count and never field content: the log reaches shared infrastructure.
+ */ export async function runDryRun(input, config) {
+    console.info(`[payload-plugin-translator] Dry run: simulated ${Object.keys(input).length} field(s), no API call made.`);
+    const { transform = reverse, timeout = 0 } = typeof config === "object" ? config : {};
+    if (timeout > 0) await new Promise((resolve)=>setTimeout(resolve, timeout));
+    const output = {};
+    for (const [key, value] of Object.entries(input)){
+        output[Number(key)] = value.trim() ? await transform(value) : value;
+    }
+    return output;
+}
+
+//# sourceMappingURL=runDryRun.js.map

package/package.json

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