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

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

@@ -1,145 +1,84 @@
-import type { TranslationProvider, TranslationInput, TranslationOutput } from "../../core/domain/translation-providers/TranslationProvider.interface";
-import type { ChatModel } from "openai/resources/index.mjs";
-/**
- * Function to transform text in dry run mode.
- * Receives the original text and returns the transformed text.
- */
-type DryRunTransformer = (text: string) => string | Promise<string>;
-/**
- * Configuration for dry run mode with custom transformer.
- */
-export type DryRunConfig = {
-    /** Custom transformer function for text */
-    transform: DryRunTransformer;
-    /** Delay in milliseconds before returning mock translation (simulates API latency) */
-    timeout?: number;
-};
-/**
- * Context passed to the system prompt builder function.
- */
-export type SystemPromptContext = {
-    /** Source language code (e.g., 'en', 'de') */
-    sourceLang: string;
-    /** Target language code (e.g., 'fr', 'es') */
-    targetLang: string;
-    /** Default system prompt that can be extended or replaced */
-    defaultPrompt: string;
-};
-/**
- * Function to build a custom system prompt for translation.
- */
-type SystemPromptBuilder = (context: SystemPromptContext) => string;
-export type OpenAIProviderConfig = {
-    /** OpenAI API key (required). Read it from an env var — never hard-code it. */
-    apiKey: string;
+import type { TranslationProvider } from "../../core/domain/translation-providers";
+import type { DryRunConfig, SystemPromptBuilder } from "../shared";
+import type { OpenAIClientShape } from "./OpenAI.shapes";
+import type { OpenAISamplingParams, OpenAIStructuredOutput } from "./openAIComplete";
+type OpenAIProviderBase = {
     /**
-     * OpenAI model to use for translation.
+     * Model used for translation.
      *
-     * @default 'gpt-4o'
-     *
-     * @example
-     * model: 'gpt-4o-mini'
+     * @default 'gpt-4o' — may move in a minor release; pin it if you need reproducibility.
      */
-    model?: (string & {}) | ChatModel;
+    model?: string;
     /**
-     * Custom system prompt builder for translation.
-     * Receives context with source/target languages and the default prompt.
-     *
-     * @example
-     * // Add custom instructions
-     * systemPrompt: ({ sourceLang, targetLang, defaultPrompt }) =>
-     *   `${defaultPrompt}\nUse formal language. Keep brand names unchanged.`
-     *
-     * @example
-     * // Completely custom prompt
-     * systemPrompt: ({ sourceLang, targetLang }) =>
-     *   `Translate JSON values from ${sourceLang} to ${targetLang}. Be concise.`
+     * Custom system-prompt builder. Receives the source and target languages plus the prompt this
+     * package would otherwise send, so you can extend it rather than rewrite it.
      */
     systemPrompt?: SystemPromptBuilder;
     /**
-     * When enabled, simulates translations without making actual API calls to OpenAI.
-     *
-     * - `true` — uses default transformer that reverses the text
-     * - `{ transform, timeout? }` — custom transformer with optional delay
-     *
-     * @example
-     * // Default behavior (reverse text, no delay)
-     * dryRun: true
-     *
-     * @example
-     * // Custom transformer with delay
-     * dryRun: {
-     *   transform: (text) => `[TRANSLATED] ${text}`,
-     *   timeout: 1000, // 1 second delay
-     * }
+     * Simulate translations without calling OpenAI — see {@link DryRunConfig}.
      *
      * @default false
+     * @deprecated Pass your own `client`, or build a provider with `createTranslationProvider({
+     * complete })`. Remove in next major. See docs/DEPRECATIONS.md#provider-dry-run
      */
     dryRun?: boolean | DryRunConfig;
     /**
-     * Per-request timeout in milliseconds for the OpenAI client. A translation job blocks on this
-     * call, so the OpenAI SDK default (10 minutes) is usually too long. Omit to keep the SDK default.
+     * Per-request timeout in milliseconds for the client this package builds.
      *
-     * @example
-     * timeout: 60_000 // 60s
+     * Ignored when you pass your own `client` — then the timeout is whatever you configured on it.
      *
+     * @default 60000
      * @since 0.6.0
      */
     timeout?: number;
     /**
-     * Maximum automatic retries the OpenAI client performs on transient errors (429, 5xx, network).
-     * Omit to keep the SDK default (2). Set `0` to disable retries.
+     * Maximum automatic retries on transient errors (429, 5xx, network) for the client this package
+     * builds. Ignored when you pass your own `client`.
      *
+     * @default the SDK's own default (2)
      * @since 0.6.0
      */
     maxRetries?: number;
-};
-/** @deprecated Use `createOpenAIProvider` function instead */
-export declare class OpenAITranslationProvider implements TranslationProvider {
-    private openAiClient;
-    private readonly config;
-    constructor(config: OpenAIProviderConfig);
-    translate(content: TranslationInput, souceLng: string, targetLng: string): Promise<TranslationOutput | null>;
     /**
-     * Builds the system prompt for translation.
-     */
-    private buildSystemPrompt;
-    /**
-     * 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.
+     * Sampling parameters — see {@link OpenAISamplingParams}, which survives this option.
+     *
+     * @since 0.11.0
      */
-    private getDryRunTransformer;
+    sampling?: OpenAISamplingParams;
     /**
-     * Returns the timeout for dry run mode.
-     * If dryRun is an object with timeout, returns it.
-     * Otherwise returns 0 (no delay).
+     * Which structured-output envelope to send — see {@link OpenAIStructuredOutput}, which documents
+     * the trade-off and survives this option.
+     *
+     * @since 0.11.0
      */
-    private getDryRunTimeout;
-    private createMockTranslation;
+    structuredOutput?: OpenAIStructuredOutput;
+};
+/**
+ * Configuration for {@link createOpenAIProvider}: an API key **or** a ready-made client, never both.
+ *
+ * @deprecated Construct the client yourself and pass it to `openAIComplete`, which stays.
+ * Remove in next major. See docs/DEPRECATIONS.md#openai-client-construction
+ */
+export type OpenAIProviderConfig = OpenAIProviderBase & ({
+    apiKey: string;
+    client?: never;
+} | {
     /**
-     * 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.
+     * A ready-made client — the OpenAI SDK client, Azure, OpenRouter, a proxy. On this path the
+     * `openai` package is never loaded and `timeout` / `maxRetries` are yours, not ours.
+     *
+     * @since 0.11.0
      */
-    private transformObjectValues;
-}
+    client: OpenAIClientShape;
+    apiKey?: never;
+});
 /**
  * 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 declare function createOpenAIProvider(config: OpenAIProviderConfig): OpenAITranslationProvider;
+export declare function createOpenAIProvider(config: OpenAIProviderConfig): TranslationProvider;
 export {};

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