@fgv/ts-extras 5.1.0-5 → 5.1.0-50

package/lib/packlets/ai-assist/http.js

@@ -0,0 +1,109 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fetchJson = fetchJson;
+exports.fetchGetJson = fetchGetJson;
+exports.fetchMultipart = fetchMultipart;
+/**
+ * Shared low-level HTTP helpers for the AI-assist provider clients (completion,
+ * image generation, embedding). Internal to the packlet.
+ * @packageDocumentation
+ */
+const ts_json_base_1 = require("@fgv/ts-json-base");
+const ts_utils_1 = require("@fgv/ts-utils");
+/**
+ * Issue one request and parse a JSON object body, or fail.
+ *
+ * @remarks
+ * The single implementation behind {@link fetchJson}, {@link fetchGetJson} and
+ * {@link fetchMultipart} — the three differed *only* in how they built their
+ * `RequestInit` and what they logged, and carried byte-identical copies of
+ * everything after the `fetch` call. Non-2xx responses, network errors, invalid
+ * JSON and non-object JSON bodies are all surfaced as `Result.fail`.
+ * @internal
+ */
+async function _fetchAndParseJson(url, init, requestLabel, logger) {
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API request: ${requestLabel}`);
+    // `captureAsyncResult` normalizes both a synchronous throw and a rejected
+    // promise, and its `_errorMessage` is the same `instanceof Error` shaping this
+    // used to spell out by hand — so the failure text is unchanged and the
+    // defensive `c8 ignore` on the non-Error branch is no longer needed here.
+    const fetched = await (0, ts_utils_1.captureAsyncResult)(() => fetch(url, init)).withErrorFormat((msg) => `AI API request failed: ${msg}`);
+    if (fetched.isFailure()) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(fetched.message);
+        return (0, ts_utils_1.fail)(fetched.message);
+    }
+    const response = fetched.value;
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => 'unknown error');
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error(`AI API returned ${response.status}: ${errorText}`);
+        return (0, ts_utils_1.fail)(`AI API returned ${response.status}: ${errorText}`);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.detail(`AI API response: ${response.status}`);
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch (_a) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned invalid JSON response');
+        return (0, ts_utils_1.fail)('AI API returned invalid JSON response');
+    }
+    if (!(0, ts_json_base_1.isJsonObject)(json)) {
+        /* c8 ignore next 1 - optional logger */
+        logger === null || logger === void 0 ? void 0 : logger.error('AI API returned non-object JSON response');
+        return (0, ts_utils_1.fail)('AI API returned non-object JSON response');
+    }
+    return (0, ts_utils_1.succeed)(json);
+}
+/**
+ * Makes a JSON POST request and returns the parsed object body, or a failure.
+ * @internal
+ */
+async function fetchJson(url, headers, body, logger, signal) {
+    return _fetchAndParseJson(url, {
+        method: 'POST',
+        headers: Object.assign({ 'Content-Type': 'application/json' }, headers),
+        body: JSON.stringify(body),
+        signal
+    }, `POST ${url}`, logger);
+}
+/**
+ * Makes an HTTP GET request and returns the parsed JSON, or a failure.
+ * @internal
+ */
+async function fetchGetJson(url, headers, logger, signal) {
+    return _fetchAndParseJson(url, { method: 'GET', headers, signal }, `GET ${url}`, logger);
+}
+/**
+ * Makes a multipart/form-data POST request and returns the parsed JSON, or a
+ * failure. The Content-Type header (with boundary) is set automatically by
+ * `fetch` from the `FormData` body — callers must NOT pass it explicitly.
+ * @internal
+ */
+async function fetchMultipart(url, headers, body, logger, signal) {
+    return _fetchAndParseJson(url, { method: 'POST', headers, body, signal }, `POST ${url} (multipart)`, logger);
+}
+//# sourceMappingURL=http.js.map

package/lib/packlets/ai-assist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/http.ts"],"names":[],"mappings":"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","sourcesContent":["// Copyright (c) 2026 Erik Fortune\n//\n// Permission is hereby granted, free of charge, to any person obtaining a copy\n// of this software and associated documentation files (the \"Software\"), to deal\n// in the Software without restriction, including without limitation the rights\n// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n// copies of the Software, and to permit persons to whom the Software is\n// furnished to do so, subject to the following conditions:\n//\n// The above copyright notice and this permission notice shall be included in all\n// copies or substantial portions of the Software.\n//\n// THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n// SOFTWARE.\n\n/**\n * Shared low-level HTTP helpers for the AI-assist provider clients (completion,\n * image generation, embedding). Internal to the packlet.\n * @packageDocumentation\n */\n\nimport { isJsonObject, type JsonObject } from '@fgv/ts-json-base';\nimport { captureAsyncResult, fail, type Logging, Result, succeed } from '@fgv/ts-utils';\n\n/**\n * Internal API configuration built from a provider descriptor.\n * @internal\n */\nexport interface IAiApiConfig {\n  readonly baseUrl: string;\n  readonly apiKey: string;\n  readonly model: string;\n}\n\n/**\n * Issue one request and parse a JSON object body, or fail.\n *\n * @remarks\n * The single implementation behind {@link fetchJson}, {@link fetchGetJson} and\n * {@link fetchMultipart} — the three differed *only* in how they built their\n * `RequestInit` and what they logged, and carried byte-identical copies of\n * everything after the `fetch` call. Non-2xx responses, network errors, invalid\n * JSON and non-object JSON bodies are all surfaced as `Result.fail`.\n * @internal\n */\nasync function _fetchAndParseJson(\n  url: string,\n  init: RequestInit,\n  requestLabel: string,\n  logger?: Logging.ILogger\n): Promise<Result<JsonObject>> {\n  /* c8 ignore next 1 - optional logger */\n  logger?.detail(`AI API request: ${requestLabel}`);\n\n  // `captureAsyncResult` normalizes both a synchronous throw and a rejected\n  // promise, and its `_errorMessage` is the same `instanceof Error` shaping this\n  // used to spell out by hand — so the failure text is unchanged and the\n  // defensive `c8 ignore` on the non-Error branch is no longer needed here.\n  const fetched: Result<Response> = await captureAsyncResult(() => fetch(url, init)).withErrorFormat(\n    (msg) => `AI API request failed: ${msg}`\n  );\n  if (fetched.isFailure()) {\n    /* c8 ignore next 1 - optional logger */\n    logger?.error(fetched.message);\n    return fail(fetched.message);\n  }\n  const response: Response = fetched.value;\n\n  if (!response.ok) {\n    const errorText = await response.text().catch(() => 'unknown error');\n    /* c8 ignore next 1 - optional logger */\n    logger?.error(`AI API returned ${response.status}: ${errorText}`);\n    return fail(`AI API returned ${response.status}: ${errorText}`);\n  }\n\n  /* c8 ignore next 1 - optional logger */\n  logger?.detail(`AI API response: ${response.status}`);\n\n  let json: unknown;\n  try {\n    json = await response.json();\n  } catch {\n    /* c8 ignore next 1 - optional logger */\n    logger?.error('AI API returned invalid JSON response');\n    return fail('AI API returned invalid JSON response');\n  }\n\n  if (!isJsonObject(json)) {\n    /* c8 ignore next 1 - optional logger */\n    logger?.error('AI API returned non-object JSON response');\n    return fail('AI API returned non-object JSON response');\n  }\n  return succeed(json);\n}\n\n/**\n * Makes a JSON POST request and returns the parsed object body, or a failure.\n * @internal\n */\nexport async function fetchJson(\n  url: string,\n  headers: Record<string, string>,\n  body: unknown,\n  logger?: Logging.ILogger,\n  signal?: AbortSignal\n): Promise<Result<JsonObject>> {\n  return _fetchAndParseJson(\n    url,\n    {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json', ...headers },\n      body: JSON.stringify(body),\n      signal\n    },\n    `POST ${url}`,\n    logger\n  );\n}\n\n/**\n * Makes an HTTP GET request and returns the parsed JSON, or a failure.\n * @internal\n */\nexport async function fetchGetJson(\n  url: string,\n  headers: Record<string, string>,\n  logger?: Logging.ILogger,\n  signal?: AbortSignal\n): Promise<Result<JsonObject>> {\n  return _fetchAndParseJson(url, { method: 'GET', headers, signal }, `GET ${url}`, logger);\n}\n\n/**\n * Makes a multipart/form-data POST request and returns the parsed JSON, or a\n * failure. The Content-Type header (with boundary) is set automatically by\n * `fetch` from the `FormData` body — callers must NOT pass it explicitly.\n * @internal\n */\nexport async function fetchMultipart(\n  url: string,\n  headers: Record<string, string>,\n  body: FormData,\n  logger?: Logging.ILogger,\n  signal?: AbortSignal\n): Promise<Result<JsonObject>> {\n  return _fetchAndParseJson(\n    url,\n    { method: 'POST', headers, body, signal },\n    `POST ${url} (multipart)`,\n    logger\n  );\n}\n"]}

package/lib/packlets/ai-assist/imageGenerationClient.d.ts

@@ -0,0 +1,46 @@
+import { type Logging, Result } from '@fgv/ts-utils';
+import { type IAiImageGenerationParams, type IAiImageGenerationResponse, type IAiProviderDescriptor, type ModelSpec } from './model';
+/**
+ * Parameters for an image-generation request.
+ * @public
+ */
+export interface IProviderImageGenerationParams {
+    /** The provider descriptor */
+    readonly descriptor: IAiProviderDescriptor;
+    /** API key for authentication */
+    readonly apiKey: string;
+    /** The image-generation request */
+    readonly params: IAiImageGenerationParams;
+    /** Optional model override — string or context-aware map (uses descriptor.defaultModel.image otherwise) */
+    readonly modelOverride?: ModelSpec;
+    /** Optional logger for request/response observability. */
+    readonly logger?: Logging.ILogger;
+    /** Optional abort signal for cancelling the in-flight request. */
+    readonly signal?: AbortSignal;
+    /** Optional override of the descriptor's base URL; per-route suffix is appended unchanged. */
+    readonly endpoint?: string;
+}
+/**
+ * Calls the appropriate image-generation API for a given provider. Routes by the
+ * `format` field of the resolved {@link IAiImageModelCapability}:
+ * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, or
+ * `'gemini-image-out'`. Rejects up front if `referenceImages` is set but the
+ * capability does not declare `acceptsImageReferenceInput`.
+ * @param params - Request parameters including descriptor, API key, and prompt
+ * @public
+ */
+export declare function callProviderImageGeneration(params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
+/**
+ * Calls the image-generation endpoint on a proxy server instead of calling
+ * the provider API directly from the browser.
+ * Endpoint: `POST ${proxyUrl}/api/ai/image-generation`. Request body:
+ * `{providerId, apiKey, params, modelOverride?}`. The proxy handles descriptor
+ * lookup, model resolution, provider dispatch, and response normalization
+ * (including repackaging `referenceImages` for the upstream wire format).
+ * Error body `{error: string}` is surfaced as `proxy: ${error}`.
+ * @param proxyUrl - Base URL of the proxy server
+ * @param params - Same parameters as {@link callProviderImageGeneration}
+ * @public
+ */
+export declare function callProxiedImageGeneration(proxyUrl: string, params: IProviderImageGenerationParams): Promise<Result<IAiImageGenerationResponse>>;
+//# sourceMappingURL=imageGenerationClient.d.ts.map

package/lib/packlets/ai-assist/imageGenerationClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageGenerationClient.d.ts","sourceRoot":"","sources":["../../../src/packlets/ai-assist/imageGenerationClient.ts"],"names":[],"mappings":"AA8BA,OAAO,EAAQ,KAAK,OAAO,EAAc,MAAM,EAAuC,MAAM,eAAe,CAAC;AAE5G,OAAO,EAGL,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAE/B,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAEf,MAAM,SAAS,CAAC;AAmEjB;;;GAGG;AACH,MAAM,WAAW,8BAA8B;IAC7C,8BAA8B;IAC9B,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAC;IAC3C,iCAAiC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;IAC1C,2GAA2G;IAC3G,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,CAAC;IACnC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AA6YD;;;;;;;;GAQG;AACH,wBAAsB,2BAA2B,CAC/C,MAAM,EAAE,8BAA8B,GACrC,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC,CA+D7C;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,8BAA8B,GACrC,OAAO,CAAC,MAAM,CAAC,0BAA0B,CAAC,CAAC,CA6B7C"}

package/lib/packlets/ai-assist/imageGenerationClient.js

@@ -0,0 +1,458 @@
+"use strict";
+// Copyright (c) 2026 Erik Fortune
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in all
+// copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+// SOFTWARE.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callProviderImageGeneration = callProviderImageGeneration;
+exports.callProxiedImageGeneration = callProxiedImageGeneration;
+const ts_utils_1 = require("@fgv/ts-utils");
+const model_1 = require("./model");
+const endpoint_1 = require("./endpoint");
+const http_1 = require("./http");
+const registry_1 = require("./registry");
+const imageOptionsResolver_1 = require("./imageOptionsResolver");
+// ============================================================================
+// Image attachment helpers
+// ============================================================================
+/**
+ * Decodes a base64-encoded image attachment into a `Blob` suitable for use as
+ * a multipart file field. On Node hands the `Buffer` straight to `Blob`
+ * (Buffer extends Uint8Array) to skip an intermediate copy; falls back to
+ * `atob` in browsers. Inputs come from `FileReader` or prior provider
+ * responses, which are trusted to be valid. Note that Node's
+ * `Buffer.from(..., 'base64')` silently strips invalid characters rather
+ * than throwing, so failures are only observable in the browser path.
+ * @internal
+ */
+function attachmentToBlob(attachment) {
+    if (typeof Buffer !== 'undefined') {
+        return (0, ts_utils_1.succeed)(new Blob([Buffer.from(attachment.base64, 'base64')], { type: attachment.mimeType }));
+    }
+    /* c8 ignore start - Browser-only fallback cannot be tested in Node.js environment */
+    try {
+        const binary = atob(attachment.base64);
+        const bytes = new Uint8Array(binary.length);
+        for (let i = 0; i < binary.length; i++) {
+            bytes[i] = binary.charCodeAt(i);
+        }
+        return (0, ts_utils_1.succeed)(new Blob([bytes], { type: attachment.mimeType }));
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return (0, ts_utils_1.fail)(`Invalid base64: ${message}`);
+    }
+    /* c8 ignore stop */
+}
+/**
+ * Maps a MIME type to a sensible file extension for multipart filenames.
+ * @internal
+ */
+function extensionForMimeType(mimeType) {
+    switch (mimeType) {
+        case 'image/png':
+            return 'png';
+        case 'image/jpeg':
+        case 'image/jpg':
+            return 'jpg';
+        case 'image/webp':
+            return 'webp';
+        case 'image/gif':
+            return 'gif';
+        default:
+            return 'bin';
+    }
+}
+const openAiImageItem = ts_utils_1.Validators.object({
+    b64_json: ts_utils_1.Validators.string,
+    revised_prompt: ts_utils_1.Validators.string.optional()
+});
+const openAiImageResponse = ts_utils_1.Validators.object({
+    data: ts_utils_1.Validators.arrayOf(openAiImageItem).withConstraint((arr) => arr.length > 0)
+});
+const geminiImageInlineData = ts_utils_1.Validators.object({
+    mimeType: ts_utils_1.Validators.string,
+    data: ts_utils_1.Validators.string
+});
+const geminiImageOutPart = ts_utils_1.Validators.object({
+    text: ts_utils_1.Validators.string.optional(),
+    inlineData: geminiImageInlineData.optional()
+});
+const geminiImageOutContent = ts_utils_1.Validators.object({
+    parts: ts_utils_1.Validators.arrayOf(geminiImageOutPart)
+});
+const geminiImageOutCandidate = ts_utils_1.Validators.object({
+    content: geminiImageOutContent.optional(),
+    finishReason: ts_utils_1.Validators.string.optional(),
+    finishMessage: ts_utils_1.Validators.string.optional()
+});
+const geminiImageOutResponse = ts_utils_1.Validators.object({
+    candidates: ts_utils_1.Validators.arrayOf(geminiImageOutCandidate).withConstraint((arr) => arr.length > 0)
+});
+// ---- Proxied image generation response ----
+const proxiedGeneratedImage = ts_utils_1.Validators.object({
+    mimeType: ts_utils_1.Validators.string,
+    base64: ts_utils_1.Validators.string,
+    revisedPrompt: ts_utils_1.Validators.string.optional()
+});
+const proxiedImageGenerationResponse = ts_utils_1.Validators.object({
+    images: ts_utils_1.Validators.arrayOf(proxiedGeneratedImage).withConstraint((arr) => arr.length > 0)
+});
+// ============================================================================
+// Image generation — adapters
+// ============================================================================
+/** Routes to /images/generations or /images/edits; handles outputParamStyle. @internal */
+async function callOpenAiImageGeneration(config, request, capability, resolved, logger, signal) {
+    var _a, _b;
+    const refs = (_a = request.referenceImages) !== null && _a !== void 0 ? _a : [];
+    const headers = (0, endpoint_1.bearerAuthHeader)(config.apiKey);
+    const effectiveMimeType = resolved.outputFormat !== undefined
+        ? `image/${resolved.outputFormat}`
+        : (_b = capability.defaultOutputMimeType) !== null && _b !== void 0 ? _b : 'image/png';
+    const fetched = refs.length > 0
+        ? await callOpenAiImagesEdits(config, capability, request, headers, resolved, logger, signal)
+        : await callOpenAiImagesGenerations(config, request, headers, resolved, capability, logger, signal);
+    return fetched.onSuccess((json) => openAiImageResponse
+        .validate(json)
+        .withErrorFormat((msg) => `OpenAI images API response: ${msg}`)
+        .onSuccess((response) => (0, ts_utils_1.succeed)({
+        images: response.data.map((item) => (Object.assign({ mimeType: effectiveMimeType, base64: item.b64_json }, (item.revised_prompt !== undefined ? { revisedPrompt: item.revised_prompt } : {}))))
+    })));
+}
+/** Builds the JSON /images/generations request; handles outputParamStyle. @internal */
+function callOpenAiImagesGenerations(config, request, headers, resolved, capability, logger, signal) {
+    var _a;
+    const body = {
+        model: config.model,
+        prompt: request.prompt,
+        n: resolved.n
+    };
+    // Output format param — conditional on model capability
+    if (capability.outputParamStyle === 'response-format') {
+        body.response_format = 'b64_json';
+    }
+    else if (capability.outputParamStyle === 'output-format') {
+        body.output_format = (_a = resolved.outputFormat) !== null && _a !== void 0 ? _a : 'png';
+    }
+    if (resolved.size !== undefined) {
+        body.size = resolved.size;
+    }
+    if (capability.supportsQualityParam && resolved.quality !== undefined) {
+        body.quality = resolved.quality;
+    }
+    if (resolved.seed !== undefined) {
+        body.seed = resolved.seed;
+    }
+    if (resolved.background !== undefined) {
+        body.background = resolved.background;
+    }
+    if (resolved.moderation !== undefined) {
+        body.moderation = resolved.moderation;
+    }
+    if (resolved.outputCompression !== undefined) {
+        body.output_compression = resolved.outputCompression;
+    }
+    if (resolved.otherParams !== undefined) {
+        Object.assign(body, resolved.otherParams);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Image generation: model=${config.model}, n=${resolved.n}`);
+    return (0, http_1.fetchJson)(`${config.baseUrl}/images/generations`, headers, body, logger, signal);
+}
+/** Builds the multipart /images/edits request with ref images. @internal */
+async function callOpenAiImagesEdits(config, capability, request, headers, resolved, logger, signal) {
+    const refs = request.referenceImages; // callers verify refs.length > 0 before calling this function
+    const blobsResult = (0, ts_utils_1.mapResults)(refs.map((ref, i) => attachmentToBlob(ref).withErrorFormat((msg) => `reference image ${i}: ${msg}`)));
+    /* c8 ignore next 3 - decode failure unreachable via Node's Buffer.from (silently strips invalid input) */
+    if (blobsResult.isFailure()) {
+        return (0, ts_utils_1.fail)(blobsResult.message);
+    }
+    const form = new FormData();
+    form.append('model', config.model);
+    form.append('prompt', request.prompt);
+    form.append('n', String(resolved.n));
+    if (capability.outputParamStyle !== 'output-format') {
+        form.append('response_format', 'b64_json');
+    }
+    if (resolved.size !== undefined) {
+        form.append('size', resolved.size);
+    }
+    blobsResult.value.forEach((blob, i) => {
+        form.append('image[]', blob, `ref-${i}.${extensionForMimeType(refs[i].mimeType)}`);
+    });
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Image edit: model=${config.model}, n=${resolved.n}, refs=${refs.length}`);
+    return (0, http_1.fetchMultipart)(`${config.baseUrl}/images/edits`, headers, form, logger, signal);
+}
+/** Calls xAI /images/edits with JSON body (not multipart); up to 3 source images. @internal */
+async function callXaiImagesEdits(config, request, resolved, logger, signal) {
+    var _a;
+    /* c8 ignore next 1 - defensive: referenceImages always defined when this function is called */
+    const refs = (_a = request.referenceImages) !== null && _a !== void 0 ? _a : [];
+    if (refs.length > 3) {
+        return (0, ts_utils_1.fail)(`xAI image edits supports at most 3 reference images; got ${refs.length}`);
+    }
+    const images = refs.map((ref) => ({
+        type: 'image_url',
+        url: `data:${ref.mimeType};base64,${ref.base64}`
+    }));
+    const body = {
+        model: config.model,
+        prompt: request.prompt,
+        n: resolved.n,
+        response_format: 'b64_json',
+        image: images
+    };
+    if (resolved.aspectRatio !== undefined) {
+        body.aspect_ratio = resolved.aspectRatio;
+    }
+    if (resolved.resolution !== undefined) {
+        body.resolution = resolved.resolution;
+    }
+    if (resolved.otherParams !== undefined) {
+        Object.assign(body, resolved.otherParams);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`xAI image edit: model=${config.model}, n=${resolved.n}, refs=${refs.length}`);
+    return (0, http_1.fetchJson)(`${config.baseUrl}/images/edits`, (0, endpoint_1.bearerAuthHeader)(config.apiKey), body, logger, signal);
+}
+/**
+ * Normalizes an xAI images API response (OpenAI-shaped) into the provider-neutral
+ * generated-image result.
+ *
+ * @remarks
+ * Shared by the generations path and the edits path. These were two independent
+ * copies 160 lines apart — identical but for the receiver name — so the
+ * `defaultOutputMimeType` fallback and the error prefix each existed twice, and a
+ * fix to one would silently have missed the other.
+ * @internal
+ */
+function normalizeXaiImageResponse(json, capability) {
+    return openAiImageResponse
+        .validate(json)
+        .withErrorFormat((msg) => `xAI images API response: ${msg}`)
+        .onSuccess((response) => (0, ts_utils_1.succeed)({
+        images: response.data.map((item) => {
+            var _a;
+            return ({
+                mimeType: (_a = capability.defaultOutputMimeType) !== null && _a !== void 0 ? _a : 'image/jpeg',
+                base64: item.b64_json
+            });
+        })
+    }));
+}
+/** Calls xAI /images/generations; uses aspect_ratio instead of size. @internal */
+async function callXaiImageGeneration(config, request, capability, resolved, logger, signal) {
+    const headers = (0, endpoint_1.bearerAuthHeader)(config.apiKey);
+    const body = {
+        model: config.model,
+        prompt: request.prompt,
+        n: resolved.n,
+        response_format: 'b64_json'
+    };
+    if (resolved.aspectRatio !== undefined) {
+        body.aspect_ratio = resolved.aspectRatio;
+    }
+    if (resolved.resolution !== undefined) {
+        body.resolution = resolved.resolution;
+    }
+    if (resolved.otherParams !== undefined) {
+        Object.assign(body, resolved.otherParams);
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`xAI image generation: model=${config.model}, n=${resolved.n}`);
+    const fetched = await (0, http_1.fetchJson)(`${config.baseUrl}/images/generations`, headers, body, logger, signal);
+    return fetched.onSuccess((json) => normalizeXaiImageResponse(json, capability));
+}
+/**
+ * Gemini `finishReason` values that indicate a normal terminal completion rather
+ * than a refusal. `STOP` is set on every successful generation (and on completions
+ * that return a text part instead of an image); `MAX_TOKENS` is a benign truncation.
+ * A candidate carrying only one of these is NOT a decline — treating it as one would
+ * mislabel an ordinary no-image outcome as a policy refusal. @internal
+ */
+const benignGeminiImageFinishReasons = new Set(['STOP', 'MAX_TOKENS']);
+/** Calls Gemini :generateContent for image output; accepts ref images as inlineData. @internal */
+async function callGeminiImageOutGeneration(config, request, resolved, logger, signal) {
+    var _a;
+    const url = `${config.baseUrl}/models/${config.model}:generateContent`;
+    const refs = (_a = request.referenceImages) !== null && _a !== void 0 ? _a : [];
+    const parts = [{ text: request.prompt }];
+    for (const ref of refs) {
+        parts.push({ inlineData: { mimeType: ref.mimeType, data: ref.base64 } });
+    }
+    const generationConfig = {};
+    if (resolved.geminiAspectRatio !== undefined) {
+        generationConfig.imageConfig = { aspectRatio: resolved.geminiAspectRatio };
+    }
+    if (resolved.otherParams !== undefined) {
+        Object.assign(generationConfig, resolved.otherParams);
+    }
+    const body = { contents: [{ role: 'user', parts }] };
+    if (Object.keys(generationConfig).length > 0) {
+        body.generationConfig = generationConfig;
+    }
+    const headers = (0, endpoint_1.geminiAuthHeader)(config.apiKey);
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`Gemini image-out: model=${config.model}, refs=${refs.length}`);
+    return (await (0, http_1.fetchJson)(url, headers, body, logger, signal)).onSuccess((json) => geminiImageOutResponse
+        .validate(json)
+        .withErrorFormat((msg) => `Gemini image API response: ${msg}`)
+        .onSuccess((response) => {
+        var _a, _b;
+        const images = [];
+        for (const candidate of response.candidates) {
+            for (const part of (_b = (_a = candidate.content) === null || _a === void 0 ? void 0 : _a.parts) !== null && _b !== void 0 ? _b : []) {
+                if (part.inlineData) {
+                    images.push({
+                        mimeType: part.inlineData.mimeType,
+                        base64: part.inlineData.data
+                    });
+                }
+            }
+        }
+        if (images.length === 0) {
+            // A candidate with no image parts is a *decline* only when it carries a
+            // refusal-shaped finishReason — i.e. present and not a benign terminal reason
+            // (`STOP`/`MAX_TOKENS`). A normal completion that emitted text-instead-of-image
+            // carries `finishReason: 'STOP'` and must fall through to the no-image message.
+            const declined = response.candidates.find((candidate) => candidate.finishReason !== undefined &&
+                !benignGeminiImageFinishReasons.has(candidate.finishReason));
+            if ((declined === null || declined === void 0 ? void 0 : declined.finishReason) !== undefined) {
+                // Truthiness (not `!== undefined`) so an empty-string finishMessage is treated
+                // as "no message" and produces no dangling ` — ` separator.
+                const suffix = declined.finishMessage ? ` — ${declined.finishMessage}` : '';
+                return (0, ts_utils_1.fail)(`Gemini image generation declined: ${declined.finishReason}${suffix}`);
+            }
+            return (0, ts_utils_1.fail)('Gemini image API response: no image parts in response');
+        }
+        return (0, ts_utils_1.succeed)({ images });
+    }));
+}
+// ============================================================================
+// Image generation — dispatcher
+// ============================================================================
+/**
+ * Calls the appropriate image-generation API for a given provider. Routes by the
+ * `format` field of the resolved {@link IAiImageModelCapability}:
+ * `'openai-images'`, `'xai-images'`, `'xai-images-edits'`, or
+ * `'gemini-image-out'`. Rejects up front if `referenceImages` is set but the
+ * capability does not declare `acceptsImageReferenceInput`.
+ * @param params - Request parameters including descriptor, API key, and prompt
+ * @public
+ */
+async function callProviderImageGeneration(params) {
+    var _a, _b, _c;
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal, endpoint } = params;
+    if (!(0, registry_1.supportsImageGeneration)(descriptor)) {
+        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" does not support image generation`);
+    }
+    const baseUrlResult = (0, endpoint_1.resolveEffectiveBaseUrl)(descriptor, endpoint);
+    if (baseUrlResult.isFailure()) {
+        return (0, ts_utils_1.fail)(baseUrlResult.message);
+    }
+    const modelResult = (0, model_1.resolveProviderModel)(descriptor, modelOverride, 'image');
+    if (modelResult.isFailure()) {
+        return (0, ts_utils_1.fail)(modelResult.message);
+    }
+    const model = modelResult.value;
+    const capability = (0, registry_1.resolveImageCapability)(descriptor, model);
+    if (capability === undefined) {
+        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" does not support image generation for model "${model}"`);
+    }
+    if (((_b = (_a = request.referenceImages) === null || _a === void 0 ? void 0 : _a.length) !== null && _b !== void 0 ? _b : 0) > 0 && !capability.acceptsImageReferenceInput) {
+        return (0, ts_utils_1.fail)(`model "${model}" does not support reference images`);
+    }
+    const resolved = (0, imageOptionsResolver_1.resolveImageOptions)(model, capability, request.options);
+    const validationResult = (0, imageOptionsResolver_1.validateResolvedOptions)(model, capability, resolved);
+    if (validationResult.isFailure()) {
+        return (0, ts_utils_1.fail)(validationResult.message);
+    }
+    const config = {
+        baseUrl: baseUrlResult.value,
+        apiKey,
+        model
+    };
+    /* c8 ignore next 6 - optional logger diagnostic output */
+    if (logger) {
+        logger.info(`AI image generation: provider=${descriptor.id}, format=${capability.format}, ` +
+            `model=${config.model}`);
+    }
+    switch (capability.format) {
+        case 'openai-images':
+            return callOpenAiImageGeneration(config, request, capability, resolved, logger, signal);
+        case 'xai-images':
+            return callXaiImageGeneration(config, request, capability, resolved, logger, signal);
+        case 'xai-images-edits': {
+            const refs = (_c = request.referenceImages) !== null && _c !== void 0 ? _c : [];
+            if (refs.length > 0) {
+                const editsResult = await callXaiImagesEdits(config, request, resolved, logger, signal);
+                return editsResult.onSuccess((json) => normalizeXaiImageResponse(json, capability));
+            }
+            return callXaiImageGeneration(config, request, capability, resolved, logger, signal);
+        }
+        case 'gemini-image-out':
+            return callGeminiImageOutGeneration(config, request, resolved, logger, signal);
+        /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+        default: {
+            const _exhaustive = capability.format;
+            return (0, ts_utils_1.fail)(`unsupported image API format: ${String(_exhaustive)}`);
+        }
+    }
+}
+// ============================================================================
+// Proxied image generation
+// ============================================================================
+/**
+ * Calls the image-generation endpoint on a proxy server instead of calling
+ * the provider API directly from the browser.
+ * Endpoint: `POST ${proxyUrl}/api/ai/image-generation`. Request body:
+ * `{providerId, apiKey, params, modelOverride?}`. The proxy handles descriptor
+ * lookup, model resolution, provider dispatch, and response normalization
+ * (including repackaging `referenceImages` for the upstream wire format).
+ * Error body `{error: string}` is surfaced as `proxy: ${error}`.
+ * @param proxyUrl - Base URL of the proxy server
+ * @param params - Same parameters as {@link callProviderImageGeneration}
+ * @public
+ */
+async function callProxiedImageGeneration(proxyUrl, params) {
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal } = params;
+    const body = {
+        providerId: descriptor.id,
+        apiKey,
+        params: request
+    };
+    if (modelOverride !== undefined) {
+        body.modelOverride = modelOverride;
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI image proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
+    const url = `${proxyUrl}/api/ai/image-generation`;
+    const jsonResult = await (0, http_1.fetchJson)(url, {}, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return (0, ts_utils_1.fail)(jsonResult.message);
+    }
+    const response = jsonResult.value;
+    if (typeof response.error === 'string') {
+        return (0, ts_utils_1.fail)(`proxy: ${response.error}`);
+    }
+    return proxiedImageGenerationResponse
+        .validate(response)
+        .withErrorFormat((msg) => `proxy returned invalid response: ${msg}`);
+}
+//# sourceMappingURL=imageGenerationClient.js.map