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

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

@@ -1,144 +1,56 @@
-import OpenAI from "openai";
-import { isObject } from "../../core/kernel/utils/isObject";
-/** @deprecated Use `createOpenAIProvider` function instead */ export class OpenAITranslationProvider {
-    openAiClient;
-    config;
-    constructor(config){
-        // `timeout`/`maxRetries` are passed through to the OpenAI SDK; `undefined` keeps the SDK
-        // defaults (10 min timeout, 2 retries). A blocking translation job rarely wants the full 10 min.
-        this.openAiClient = new OpenAI({
-            apiKey: config.apiKey,
-            timeout: config.timeout,
-            maxRetries: config.maxRetries
-        });
-        this.config = config;
-    }
-    async translate(content, souceLng, targetLng) {
-        if (this.config.dryRun) {
-            console.info("[DRY RUN] Translation simulation:", {
-                content,
-                sourceLang: souceLng,
-                targetLang: targetLng,
-                provider: "OpenAI"
-            });
-            const timeout = this.getDryRunTimeout();
-            if (timeout > 0) await new Promise((resolve)=>setTimeout(resolve, timeout));
-            const transformer = this.getDryRunTransformer();
-            return this.createMockTranslation(content, transformer);
-        }
-        const systemPrompt = this.buildSystemPrompt(souceLng, targetLng);
-        const chatCompletion = await this.openAiClient.chat.completions.create({
-            messages: [
-                {
-                    role: "system",
-                    content: systemPrompt
-                },
-                {
-                    role: "user",
-                    content: JSON.stringify(content)
-                }
-            ],
-            model: this.config.model ?? "gpt-4o",
-            temperature: 0,
-            top_p: 1,
-            frequency_penalty: 0,
-            presence_penalty: 0,
-            response_format: {
-                type: "json_object"
-            }
-        });
-        // Guard `choices[0]`: an empty `choices` array (e.g. content-filtered response) would otherwise
-        // throw a TypeError instead of the intended graceful `null`.
-        const translatedContent = chatCompletion.choices[0]?.message?.content;
-        if (!translatedContent) return null;
-        try {
-            return JSON.parse(translatedContent);
-        } catch  {
-            return null;
-        }
-    }
-    /**
-   * Builds the system prompt for translation.
-   */ buildSystemPrompt(sourceLang, targetLang) {
-        const defaultPrompt = `Translate the values from the JSON that the user will send you${sourceLang ? ` from ${sourceLang}` : ""} into ${targetLang}. 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 (this.config.systemPrompt) {
-            return this.config.systemPrompt({
-                sourceLang,
-                targetLang,
-                defaultPrompt
-            });
-        }
-        return defaultPrompt;
-    }
-    /**
-   * Returns the transformer function for dry run mode.
-   * If dryRun is an object with transform, returns it.
-   * If dryRun is true, returns the default transformer that reverses text.
-   */ getDryRunTransformer() {
-        if (typeof this.config.dryRun === "object" && this.config.dryRun.transform) {
-            return this.config.dryRun.transform;
-        }
-        return (text)=>text.split("").reverse().join("");
-    }
-    /**
-   * Returns the timeout for dry run mode.
-   * If dryRun is an object with timeout, returns it.
-   * Otherwise returns 0 (no delay).
-   */ getDryRunTimeout() {
-        if (typeof this.config.dryRun === "object" && this.config.dryRun.timeout) {
-            return this.config.dryRun.timeout;
-        }
-        return 0;
-    }
-    async createMockTranslation(content, transformer) {
-        try {
-            const mockTranslation = await this.transformObjectValues(content, async (value)=>{
-                if (typeof value === "string" && value.trim()) return transformer(value);
-                return value;
-            });
-            return mockTranslation;
-        } catch  {
-            return null;
-        }
-    }
-    /**
-   * Recursively transforms the values of an object or array using the provided transformer function.
-   * @param obj The object or value to transform.
-   * @param transformer The function to apply to each value.
-   * @returns The transformed object, array, or value.
-   */ async transformObjectValues(obj, transformer) {
-        if (Array.isArray(obj)) {
-            return Promise.all(obj.map((item)=>this.transformObjectValues(item, transformer)));
-        }
-        if (isObject(obj)) {
-            const result = {};
-            for (const [key, value] of Object.entries(obj)){
-                result[key] = await this.transformObjectValues(value, transformer);
-            }
-            return result;
-        }
-        return transformer(obj);
-    }
-}
+import { createTranslationProvider } from "../shared";
+import { loadOpenAIClient } from "./loadOpenAIClient";
+import { openAIComplete } from "./openAIComplete";
+const DEFAULT_MODEL = "gpt-4o";
+/** 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.
  *
- * @example
- * ```ts
- * // Basic usage
- * createOpenAIProvider({ apiKey: process.env.OPENAI_API_KEY })
- *
- * // With options
- * createOpenAIProvider({
- *   apiKey: process.env.OPENAI_API_KEY,
- *   model: 'gpt-4o-mini',
- *   systemPrompt: ({ defaultPrompt }) => `${defaultPrompt}\nUse formal language.`,
- * })
- * ```
+ * @deprecated What this adds over `openAIComplete` is building the SDK client for you, and
+ * carrying `openai` as an optional dependency to do it. Construct the client yourself instead:
+ * `createTranslationProvider({ complete: openAIComplete({ client, model }) })`. Remove in next
+ * major. See the recipe in the README and docs/DEPRECATIONS.md#openai-client-construction
  */ export function createOpenAIProvider(config) {
-    return new OpenAITranslationProvider(config);
+    const { model = DEFAULT_MODEL, systemPrompt, dryRun, sampling, structuredOutput } = config;
+    // The promise, not the client: two concurrent first calls would otherwise each start their own
+    // import. Per instance, never module-level — one consumer's client must not reach a differently
+    // configured provider in the same process.
+    let clientPromise;
+    const loadClientAndForgetOnFailure = async ()=>{
+        try {
+            // `apiKey` goes through unchanged — never defaulted to "". The SDK checks for `undefined`, so an
+            // empty string would build a client that 401s on every request instead of saying the key is
+            // missing.
+            return await loadOpenAIClient({
+                apiKey: config.apiKey,
+                timeout: config.timeout ?? DEFAULT_TIMEOUT_MS,
+                maxRetries: config.maxRetries
+            });
+        } catch (error) {
+            // A cached rejected promise makes one bad first call permanent — the job runner's retries
+            // would replay the same stale error.
+            clientPromise = undefined;
+            throw error;
+        }
+    };
+    const resolveClient = ()=>{
+        if (config.client) return Promise.resolve(config.client);
+        clientPromise ??= loadClientAndForgetOnFailure();
+        return clientPromise;
+    };
+    return createTranslationProvider({
+        systemPrompt,
+        dryRun,
+        complete: async (request)=>{
+            const client = await resolveClient();
+            return openAIComplete({
+                client,
+                model,
+                sampling,
+                structuredOutput
+            })(request);
+        }
+    });
 }
 
 //# sourceMappingURL=OpenAITranslation.provider.js.map

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

@@ -0,0 +1,11 @@
+import type { TranslationInput, TranslationOutput, TranslationProvider } from "../../core/domain/translation-providers";
+import type { OpenAIProviderConfig } from "./OpenAITranslation.provider";
+/**
+ * @deprecated Use {@link createOpenAIProvider} instead.
+ * See docs/DEPRECATIONS.md#openai-translation-provider-class
+ */
+export declare class OpenAITranslationProvider implements TranslationProvider {
+    private readonly inner;
+    constructor(config: OpenAIProviderConfig);
+    translate(input: TranslationInput, sourceLng: string, targetLng: string): Promise<TranslationOutput | null>;
+}

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

@@ -0,0 +1,15 @@
+import { createOpenAIProvider } from "./OpenAITranslation.provider";
+/**
+ * @deprecated Use {@link createOpenAIProvider} instead.
+ * See docs/DEPRECATIONS.md#openai-translation-provider-class
+ */ export class OpenAITranslationProvider {
+    inner;
+    constructor(config){
+        this.inner = createOpenAIProvider(config);
+    }
+    translate(input, sourceLng, targetLng) {
+        return this.inner.translate(input, sourceLng, targetLng);
+    }
+}
+
+//# sourceMappingURL=OpenAITranslationLegacy.provider.js.map

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

@@ -1 +1,6 @@
-export { OpenAITranslationProvider, createOpenAIProvider, type OpenAIProviderConfig, type DryRunConfig, type SystemPromptContext, } from "./OpenAITranslation.provider";
+export { createOpenAIProvider } from "./OpenAITranslation.provider";
+export { OpenAITranslationProvider } from "./OpenAITranslationLegacy.provider";
+export type { OpenAIProviderConfig } from "./OpenAITranslation.provider";
+export type { OpenAIClientShape } from "./OpenAI.shapes";
+export { openAIComplete } from "./openAIComplete";
+export type { OpenAISamplingParams, OpenAIStructuredOutput } from "./openAIComplete";

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

@@ -1,5 +1,5 @@
-// OpenAI translation provider — one vendor implementation of the core `TranslationProvider`
-// port. Payload-free; pulls the `openai` SDK (opt-in).
-export { OpenAITranslationProvider, createOpenAIProvider } from "./OpenAITranslation.provider";
+export { createOpenAIProvider } from "./OpenAITranslation.provider";
+export { OpenAITranslationProvider } from "./OpenAITranslationLegacy.provider";
+export { openAIComplete } from "./openAIComplete";
 
 //# sourceMappingURL=index.js.map

package/dist/translation-providers/openai/loadOpenAIClient.d.ts

@@ -0,0 +1,24 @@
+import type { OpenAIClientShape } from "./OpenAI.shapes";
+export type OpenAIClientOptions = {
+    apiKey?: string;
+    timeout?: number;
+    maxRetries?: number;
+};
+type OpenAISdkModule = {
+    default: new (opts: OpenAIClientOptions) => unknown;
+};
+export type OpenAISdkImporter = () => Promise<OpenAISdkModule>;
+/**
+ * Was `moduleSpecifier` itself missing, or one of its dependencies? Exported for its own test; not
+ * public API.
+ */
+export declare function isModuleNotFound(cause: unknown, moduleSpecifier: string): boolean;
+/**
+ * Constructs an OpenAI SDK client, importing the `openai` package on every call — callers memoize.
+ * Reached only when a consumer passed `apiKey`; a consumer who injects a `client` never runs this
+ * module.
+ *
+ * @throws ProviderConfigurationError for a missing package, a broken install, or rejected options.
+ */
+export declare function loadOpenAIClient(options: OpenAIClientOptions, importSdk?: OpenAISdkImporter): Promise<OpenAIClientShape>;
+export {};

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

@@ -0,0 +1,79 @@
+import { errorMessageLower, ProviderConfigurationError } from "../shared";
+/**
+ * A literal `import("openai")` is type-resolved like a static import and would put the SDK into the
+ * emitted .d.ts, forcing every consumer to install it. Through a constant it resolves at runtime only.
+ */ const OPENAI_MODULE = "openai";
+const MODULE_NOT_FOUND_CODES = new Set([
+    "ERR_MODULE_NOT_FOUND",
+    "MODULE_NOT_FOUND"
+]);
+/**
+ * Bundlers and test runners re-throw resolution failures in their own shapes, and several drop the
+ * `code` on the way. The wording is the more portable signal, so both are checked.
+ */ const MODULE_NOT_FOUND_MESSAGES = {
+    nodeCjs: "cannot find module",
+    nodeEsm: "cannot find package",
+    viteRollup: "failed to resolve",
+    viteDev: "failed to load url",
+    webpack: "module not found"
+};
+/**
+ * Each runtime's message names two things: what was not found and who imported it. The importer half
+ * is a path inside node_modules/openai, so it must be cut off before searching for "openai".
+ */ const IMPORTER_CLAUSES = {
+    nodeEsm: " imported from ",
+    nodeCjs: "require stack:",
+    vite: " from ",
+    webpack: " in "
+};
+/**
+ * `@vercel/nft` (Vercel builds, Next `output: "standalone"`) resolves `import()` statically and can
+ * follow a module-level constant but not a parameter — silently, so a parameterised specifier gets
+ * `openai` pruned from the deployment and the first production translation reports it missing.
+ */ async function importOpenAISdk() {
+    return await import(OPENAI_MODULE);
+}
+function whatCouldNotBeFound(text) {
+    return Object.values(IMPORTER_CLAUSES).reduce((remaining, clause)=>remaining.split(clause)[0], text);
+}
+/**
+ * Was `moduleSpecifier` itself missing, or one of its dependencies? Exported for its own test; not
+ * public API.
+ */ export function isModuleNotFound(cause, moduleSpecifier) {
+    const text = errorMessageLower(cause);
+    if (text === null) return false;
+    if (!whatCouldNotBeFound(text).includes(moduleSpecifier.toLowerCase())) return false;
+    const code = cause.code;
+    if (typeof code === "string" && MODULE_NOT_FOUND_CODES.has(code)) return true;
+    return Object.values(MODULE_NOT_FOUND_MESSAGES).some((phrase)=>text.includes(phrase));
+}
+/**
+ * Constructs an OpenAI SDK client, importing the `openai` package on every call — callers memoize.
+ * Reached only when a consumer passed `apiKey`; a consumer who injects a `client` never runs this
+ * module.
+ *
+ * @throws ProviderConfigurationError for a missing package, a broken install, or rejected options.
+ */ export async function loadOpenAIClient(options, importSdk = importOpenAISdk) {
+    let sdk;
+    try {
+        sdk = await importSdk();
+    } catch (cause) {
+        if (isModuleNotFound(cause, OPENAI_MODULE)) {
+            throw new ProviderConfigurationError("createOpenAIProvider({ apiKey }) needs the optional `openai` package. Install it, or pass a ready-made `client` instead.", {
+                cause
+            });
+        }
+        throw new ProviderConfigurationError("The `openai` package is installed but failed to load. See this error's `cause`.", {
+            cause
+        });
+    }
+    try {
+        return new sdk.default(options);
+    } catch (cause) {
+        throw new ProviderConfigurationError("The OpenAI client could not be constructed from the given options. See this error's `cause`.", {
+            cause
+        });
+    }
+}
+
+//# sourceMappingURL=loadOpenAIClient.js.map

package/dist/translation-providers/openai/openAIComplete.d.ts

@@ -0,0 +1,39 @@
+import type { CompletionFn } from "../shared";
+import type { OpenAIChatParams, OpenAIClientShape } from "./OpenAI.shapes";
+/**
+ * Sampling parameters. Omitted from the request entirely unless set — several models reject them.
+ * Unset means the model's own defaults; pass `{ temperature: 0 }` for deterministic output.
+ *
+ * @since 0.11.0
+ */
+export type OpenAISamplingParams = Pick<OpenAIChatParams, "temperature" | "top_p" | "frequency_penalty" | "presence_penalty">;
+/**
+ * Which structured-output envelope to send.
+ *
+ * `json_schema` (the default): the reply must satisfy a schema, so a compliant model cannot drop a
+ * field. Older models and some gateways reject it with a 400, and the schema has a per-model
+ * property ceiling a large document can exceed.
+ *
+ * `json_object`: asks only for valid JSON. No ceiling, but a dropped key is then detected by
+ * key-set validation after the fact rather than prevented.
+ *
+ * The README weighs the two and explains how to size a document against the ceiling.
+ *
+ * @since 0.11.0
+ */
+export type OpenAIStructuredOutput = "json_schema" | "json_object";
+/**
+ * The vendor boundary: the only place OpenAI's response shape is read.
+ *
+ * Takes a client you constructed — it never loads the `openai` package — so pair it with
+ * `createTranslationProvider` to build a provider on an SDK version of your own choosing:
+ * `createTranslationProvider({ complete: openAIComplete({ client, model }) })`.
+ *
+ * @since 0.11.0
+ */
+export declare function openAIComplete(args: {
+    client: OpenAIClientShape;
+    model: string;
+    sampling?: OpenAISamplingParams;
+    structuredOutput?: OpenAIStructuredOutput;
+}): CompletionFn;

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

@@ -0,0 +1,84 @@
+import { errorMessageLower, NoContentError, ProviderConfigurationError } from "../shared";
+const SCHEMA_NAME = "translation";
+/**
+ * Did the service reject the request over the schema envelope, and if so, why? The match stays
+ * narrow: a proxy that echoes the request body into an error string would otherwise turn every rate
+ * limit into a configuration problem.
+ */ function classifySchemaRejection(cause) {
+    const text = errorMessageLower(cause);
+    if (text === null) return null;
+    if (!text.includes("response_format") && !text.includes("json_schema")) return null;
+    // "…'response_format' of type 'json_schema' is not supported with this model."
+    if (text.includes("not supported") || text.includes("unsupported")) {
+        return "model-does-not-support";
+    }
+    // "Invalid schema for response_format 'translation': object has too many properties."
+    if (text.includes("invalid schema")) return "schema-rejected";
+    return null;
+}
+/**
+ * The vendor boundary: the only place OpenAI's response shape is read.
+ *
+ * Takes a client you constructed — it never loads the `openai` package — so pair it with
+ * `createTranslationProvider` to build a provider on an SDK version of your own choosing:
+ * `createTranslationProvider({ complete: openAIComplete({ client, model }) })`.
+ *
+ * @since 0.11.0
+ */ export function openAIComplete(args) {
+    const { client, model, sampling, structuredOutput = "json_schema" } = args;
+    return async ({ systemPrompt, userContent, responseSchema, signal })=>{
+        if (structuredOutput === "json_object" && !/json/iu.test(systemPrompt)) {
+            throw new ProviderConfigurationError('With structuredOutput: "json_object", OpenAI requires the word "json" somewhere in the prompt. Your systemPrompt override does not contain it.');
+        }
+        const params = {
+            model,
+            messages: [
+                {
+                    role: "system",
+                    content: systemPrompt
+                },
+                {
+                    role: "user",
+                    content: userContent
+                }
+            ],
+            response_format: structuredOutput === "json_schema" ? {
+                type: "json_schema",
+                json_schema: {
+                    name: SCHEMA_NAME,
+                    strict: true,
+                    schema: responseSchema
+                }
+            } : {
+                type: "json_object"
+            },
+            ...sampling
+        };
+        let result;
+        try {
+            result = await client.chat.completions.create(params, {
+                signal
+            });
+        } catch (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.`, {
+                    cause
+                });
+            }
+            if (rejection === "schema-rejected") {
+                throw new ProviderConfigurationError(`OpenAI rejected the generated response schema. This usually means the document has more translatable fields than a strict schema allows. Pass structuredOutput: "json_object", or translate a smaller subtree.`, {
+                    cause
+                });
+            }
+            throw cause;
+        }
+        const content = result.choices[0]?.message?.content;
+        if (!content) {
+            throw new NoContentError("OpenAI returned no content. The reply may have been filtered, or the model produced nothing.");
+        }
+        return content;
+    };
+}
+
+//# sourceMappingURL=openAIComplete.js.map

package/dist/translation-providers/shared/CompletionProvider.provider.d.ts

@@ -0,0 +1,65 @@
+import type { TranslationProvider } from "../../core/domain/translation-providers";
+import type { JsonSchemaObject } from "./buildResponseSchema";
+import type { SystemPromptBuilder } from "./buildSystemPrompt";
+import type { DryRunConfig } from "./runDryRun";
+/**
+ * Everything a transport needs in order to make one translation request.
+ *
+ * @since 0.11.0
+ */
+export type CompletionRequest = {
+    /** Already includes any `systemPrompt` override — send it verbatim, do not rebuild it. */
+    systemPrompt: string;
+    /** The user message: the input serialized as JSON. */
+    userContent: string;
+    /** A JSON Schema requiring exactly the input's keys. Feed it to the service's structured-output mechanism. */
+    responseSchema: JsonSchemaObject;
+    /** Reserved: the port carries no cancellation yet, so this is always `undefined` today. */
+    signal?: AbortSignal;
+};
+/**
+ * Sends one translation request and returns the service's reply as **raw text**.
+ *
+ * Returning text rather than a parsed object is deliberate: parsing and key-set validation stay on
+ * this side of the boundary, so a provider built on this factory cannot accidentally skip them.
+ *
+ * @since 0.11.0
+ */
+export type CompletionFn = (request: CompletionRequest) => Promise<string>;
+/**
+ * Configuration for {@link createTranslationProvider}.
+ *
+ * @since 0.11.0
+ */
+export type TranslationProviderConfig = {
+    complete: CompletionFn;
+    systemPrompt?: SystemPromptBuilder;
+    /**
+     * Simulate translations without calling anything. `true` reverses the text; an object supplies a
+     * transformer and an optional delay.
+     *
+     * @deprecated Supply your own fake `complete` instead. Remove in next major.
+     * See docs/DEPRECATIONS.md#provider-dry-run
+     */
+    dryRun?: boolean | DryRunConfig;
+};
+/**
+ * Builds a complete {@link TranslationProvider} from a single request function.
+ *
+ * Use it when you need a service this package does not ship an adapter for, or when you need full
+ * control of the request body. For OpenAI, `openAIComplete({ client, model })` is a ready-made
+ * `complete` — construct the client yourself.
+ *
+ * @example
+ * ```ts
+ * const provider = createTranslationProvider({
+ *   complete: async ({ systemPrompt, userContent, responseSchema }) => {
+ *     const reply = await myService.chat({ systemPrompt, userContent, schema: responseSchema })
+ *     return reply.text
+ *   },
+ * })
+ * ```
+ *
+ * @since 0.11.0
+ */
+export declare function createTranslationProvider(config: TranslationProviderConfig): TranslationProvider;

package/dist/translation-providers/shared/CompletionProvider.provider.js

@@ -0,0 +1,93 @@
+import { buildResponseSchema } from "./buildResponseSchema";
+import { buildSystemPrompt } from "./buildSystemPrompt";
+import { NoContentError, ProviderConfigurationError, wrapTransportError } from "./errors";
+import { parseAndValidateReply } from "./parseAndValidateReply";
+import { runDryRun } from "./runDryRun";
+const MAX_LOGGED_REPLY_KEYS = 10;
+/** Keys are model output: quoting them stops a newline inside a key from forging log entries. */ function describeReplyKeys(keys) {
+    const shown = keys.slice(0, MAX_LOGGED_REPLY_KEYS).map((key)=>JSON.stringify(key));
+    const rest = keys.length - shown.length;
+    return rest > 0 ? `${shown.join(", ")} and ${rest} more` : shown.join(", ");
+}
+function warnAboutPartialReply(missingInputKeys, unrequestedReplyKeys) {
+    const lead = missingInputKeys.length > 0 ? `The provider's reply did not cover every field. Untranslated indices: ${missingInputKeys.join(", ")}.` : "The provider's reply carried keys that were not requested.";
+    const extra = unrequestedReplyKeys.length > 0 ? ` Unexpected keys ignored: ${describeReplyKeys(unrequestedReplyKeys)}.` : "";
+    console.warn(`[payload-plugin-translator] ${lead}${extra}`);
+}
+async function asConfigurationFailure(what, run) {
+    try {
+        return await run();
+    } catch (cause) {
+        throw new ProviderConfigurationError(`The ${what} threw. See this error's \`cause\`.`, {
+            cause
+        });
+    }
+}
+/** Only the consumer's transform is wrapped — our own loop must not report its bugs as configuration failures. */ function guardTransformer(dryRun) {
+    if (typeof dryRun !== "object" || !dryRun.transform) return dryRun;
+    const { transform } = dryRun;
+    return {
+        ...dryRun,
+        transform: (text)=>asConfigurationFailure("dry-run transformer", ()=>transform(text))
+    };
+}
+/**
+ * Builds a complete {@link TranslationProvider} from a single request function.
+ *
+ * Use it when you need a service this package does not ship an adapter for, or when you need full
+ * control of the request body. For OpenAI, `openAIComplete({ client, model })` is a ready-made
+ * `complete` — construct the client yourself.
+ *
+ * @example
+ * ```ts
+ * const provider = createTranslationProvider({
+ *   complete: async ({ systemPrompt, userContent, responseSchema }) => {
+ *     const reply = await myService.chat({ systemPrompt, userContent, schema: responseSchema })
+ *     return reply.text
+ *   },
+ * })
+ * ```
+ *
+ * @since 0.11.0
+ */ export function createTranslationProvider(config) {
+    const { complete, systemPrompt, dryRun } = config;
+    if (dryRun) {
+        const guarded = guardTransformer(dryRun);
+        return {
+            translate: (input)=>runDryRun(input, guarded)
+        };
+    }
+    return {
+        async translate (input, sourceLng, targetLng) {
+            // A strict response schema with no properties is rejected by the service, so an empty
+            // document must not reach the transport at all.
+            if (Object.keys(input).length === 0) return {};
+            const systemPromptText = await asConfigurationFailure("systemPrompt builder", ()=>buildSystemPrompt({
+                    sourceLng,
+                    targetLng,
+                    override: systemPrompt
+                }));
+            const request = await asConfigurationFailure("serialization of the input", ()=>({
+                    systemPrompt: systemPromptText,
+                    userContent: JSON.stringify(input),
+                    responseSchema: buildResponseSchema(input)
+                }));
+            let raw;
+            try {
+                raw = await complete(request);
+            } catch (cause) {
+                throw wrapTransportError(cause);
+            }
+            if (!raw) {
+                throw new NoContentError("The provider returned an empty reply.");
+            }
+            const { translations, missingInputKeys, unrequestedReplyKeys } = parseAndValidateReply(input, raw);
+            if (missingInputKeys.length > 0 || unrequestedReplyKeys.length > 0) {
+                warnAboutPartialReply(missingInputKeys, unrequestedReplyKeys);
+            }
+            return translations;
+        }
+    };
+}
+
+//# sourceMappingURL=CompletionProvider.provider.js.map

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

@@ -0,0 +1,13 @@
+import type { TranslationInput } from "../../core/domain/translation-providers";
+/**
+ * A JSON Schema document, as a plain object — deliberately untyped beyond that, so it can be dropped
+ * into any vendor's response-format envelope.
+ *
+ * @since 0.11.0
+ */
+export type JsonSchemaObject = Record<string, unknown>;
+/**
+ * Builds the response schema for a translation request: exactly the input's keys, all required, no
+ * extras.
+ */
+export declare function buildResponseSchema(input: TranslationInput): JsonSchemaObject;

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

@@ -0,0 +1,22 @@
+/**
+ * Builds the response schema for a translation request: exactly the input's keys, all required, no
+ * extras.
+ */ export function buildResponseSchema(input) {
+    const keys = Object.keys(input);
+    const properties = {};
+    for (const key of keys){
+        properties[key] = {
+            type: "string"
+        };
+    }
+    // Strict structured-output modes reject a schema unless every property is listed in `required`
+    // and extras are forbidden.
+    return {
+        type: "object",
+        properties,
+        required: keys,
+        additionalProperties: false
+    };
+}
+
+//# sourceMappingURL=buildResponseSchema.js.map