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

package/dist/packlets/ai-assist/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"endpoint.js","sourceRoot":"","sources":["../../../src/packlets/ai-assist/endpoint.ts"],"names":[],"mappings":"AAAA,kCAAkC;AAClC,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,wEAAwE;AACxE,2DAA2D;AAC3D,EAAE;AACF,iFAAiF;AACjF,kDAAkD;AAClD,EAAE;AACF,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,yEAAyE;AACzE,gFAAgF;AAChF,gFAAgF;AAChF,YAAY;AAEZ;;;;;GAKG;AAEH,OAAO,EAAE,IAAI,EAAU,OAAO,EAAE,MAAM,eAAe,CAAC;AAItD;;;;;;;GAOG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAc;IACjD,OAAO;QACL,WAAW,EAAE,MAAM;QACnB,mBAAmB,EAAE,YAAY;QACjC,2CAA2C,EAAE,MAAM;KACpD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,MAAc;IAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;AACtC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,uBAAuB,CACrC,UAAiC,EACjC,QAAiB;IAEjB,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC,aAAa,UAAU,CAAC,EAAE,kCAAkC,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,OAAO,IAAI,CAAC,aAAa,UAAU,CAAC,EAAE,6CAA6C,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,MAAW,CAAC;IAChB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7B,CAAC;IAAC,WAAM,CAAC;QACP,OAAO,IAAI,CAAC,aAAa,UAAU,CAAC,EAAE,gCAAgC,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAChE,OAAO,IAAI,CAAC,aAAa,UAAU,CAAC,EAAE,2CAA2C,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC;IACvG,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvD,OAAO,IAAI,CAAC,aAAa,UAAU,CAAC,EAAE,yDAAyD,CAAC,CAAC;IACnG,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7D,OAAO,IAAI,CACT,aAAa,UAAU,CAAC,EAAE,4EAA4E,CACvG,CAAC;IACJ,CAAC;IACD,uEAAuE;IACvE,wEAAwE;IACxE,sCAAsC;IACtC,OAAO,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3E,CAAC","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 * Helper for resolving a request's effective base URL from a provider\n * descriptor and an optional caller-supplied endpoint override.\n *\n * @packageDocumentation\n */\n\nimport { fail, Result, succeed } from '@fgv/ts-utils';\n\nimport { type IAiProviderDescriptor } from './model';\n\n/**\n * Builds an OpenAI-style `Authorization: Bearer ${key}` header, or an empty\n * record when the key is empty. Self-hosted/local OpenAI-compatible servers\n * (Ollama, LM Studio, llama.cpp) often reject `Authorization: Bearer ` with\n * an empty key, so we omit the header entirely in that case.\n *\n * @internal\n */\nexport function bearerAuthHeader(apiKey: string): Record<string, string> {\n  return apiKey.length > 0 ? { Authorization: `Bearer ${apiKey}` } : {};\n}\n\n/**\n * The Anthropic Messages API auth + protocol headers.\n *\n * @remarks\n * `anthropic-version` is a **wire-protocol pin**, and single-sourcing it here is\n * the point of this helper: it was previously replicated across the completion\n * client, the list-models client and the streaming adapter, so bumping it was a\n * three-file edit with nothing to catch a miss.\n *\n * `anthropic-dangerous-direct-browser-access` is required for browser callers;\n * it is sent unconditionally because the same client code serves both runtimes.\n *\n * @internal\n */\nexport function anthropicAuthHeaders(apiKey: string): Record<string, string> {\n  return {\n    'x-api-key': apiKey,\n    'anthropic-version': '2023-06-01',\n    'anthropic-dangerous-direct-browser-access': 'true'\n  };\n}\n\n/**\n * The Gemini API auth header. Gemini keys ride in `x-goog-api-key` rather than\n * an `Authorization` bearer.\n * @internal\n */\nexport function geminiAuthHeader(apiKey: string): Record<string, string> {\n  return { 'x-goog-api-key': apiKey };\n}\n\n/**\n * Resolves the effective base URL for a request, validating the optional\n * `endpoint` override when present. Returns the URL with any trailing slash\n * stripped so per-route suffix concatenation (e.g. `/chat/completions`)\n * produces the same shape regardless of whether the caller supplied an\n * override or the descriptor's default is used.\n *\n * @internal\n */\nexport function resolveEffectiveBaseUrl(\n  descriptor: IAiProviderDescriptor,\n  endpoint?: string\n): Result<string> {\n  if (endpoint === undefined) {\n    if (!descriptor.baseUrl) {\n      return fail(`provider \"${descriptor.id}\" has no API endpoint configured`);\n    }\n    return succeed(descriptor.baseUrl.replace(/\\/+$/, ''));\n  }\n  if (typeof endpoint !== 'string' || endpoint.length === 0) {\n    return fail(`provider \"${descriptor.id}\": endpoint must be a non-empty http(s) URL`);\n  }\n  let parsed: URL;\n  try {\n    parsed = new URL(endpoint);\n  } catch {\n    return fail(`provider \"${descriptor.id}\": endpoint is not a valid URL`);\n  }\n  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n    return fail(`provider \"${descriptor.id}\": endpoint must use http or https (got ${parsed.protocol})`);\n  }\n  if (parsed.search.length > 0 || parsed.hash.length > 0) {\n    return fail(`provider \"${descriptor.id}\": endpoint must not include a query string or fragment`);\n  }\n  if (parsed.username.length > 0 || parsed.password.length > 0) {\n    return fail(\n      `provider \"${descriptor.id}\": endpoint must not include userinfo; pass credentials via apiKey instead`\n    );\n  }\n  // Reconstruct from origin + pathname so the returned URL is normalized\n  // (no userinfo, no query, no fragment) and the suffix concat in callers\n  // produces a well-formed request URL.\n  return succeed(`${parsed.origin}${parsed.pathname}`.replace(/\\/+$/, ''));\n}\n"]}

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

@@ -0,0 +1,104 @@
+// 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.
+/**
+ * Shared low-level HTTP helpers for the AI-assist provider clients (completion,
+ * image generation, embedding). Internal to the packlet.
+ * @packageDocumentation
+ */
+import { isJsonObject } from '@fgv/ts-json-base';
+import { captureAsyncResult, fail, succeed } from '@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 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 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 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 fail('AI API returned invalid JSON response');
+    }
+    if (!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 fail('AI API returned non-object JSON response');
+    }
+    return succeed(json);
+}
+/**
+ * Makes a JSON POST request and returns the parsed object body, or a failure.
+ * @internal
+ */
+export 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
+ */
+export 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
+ */
+export 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/dist/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/dist/packlets/ai-assist/imageGenerationClient.js

@@ -0,0 +1,454 @@
+// 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.
+import { fail, mapResults, succeed, Validators } from '@fgv/ts-utils';
+import { resolveProviderModel } from './model';
+import { bearerAuthHeader, geminiAuthHeader, resolveEffectiveBaseUrl } from './endpoint';
+import { fetchJson, fetchMultipart } from './http';
+import { resolveImageCapability, supportsImageGeneration } from './registry';
+import { resolveImageOptions, validateResolvedOptions } from './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 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 succeed(new Blob([bytes], { type: attachment.mimeType }));
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return 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 = Validators.object({
+    b64_json: Validators.string,
+    revised_prompt: Validators.string.optional()
+});
+const openAiImageResponse = Validators.object({
+    data: Validators.arrayOf(openAiImageItem).withConstraint((arr) => arr.length > 0)
+});
+const geminiImageInlineData = Validators.object({
+    mimeType: Validators.string,
+    data: Validators.string
+});
+const geminiImageOutPart = Validators.object({
+    text: Validators.string.optional(),
+    inlineData: geminiImageInlineData.optional()
+});
+const geminiImageOutContent = Validators.object({
+    parts: Validators.arrayOf(geminiImageOutPart)
+});
+const geminiImageOutCandidate = Validators.object({
+    content: geminiImageOutContent.optional(),
+    finishReason: Validators.string.optional(),
+    finishMessage: Validators.string.optional()
+});
+const geminiImageOutResponse = Validators.object({
+    candidates: Validators.arrayOf(geminiImageOutCandidate).withConstraint((arr) => arr.length > 0)
+});
+// ---- Proxied image generation response ----
+const proxiedGeneratedImage = Validators.object({
+    mimeType: Validators.string,
+    base64: Validators.string,
+    revisedPrompt: Validators.string.optional()
+});
+const proxiedImageGenerationResponse = Validators.object({
+    images: 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 = 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) => 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 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 = 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 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 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 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 fetchJson(`${config.baseUrl}/images/edits`, 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) => 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 = 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 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 = 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 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 fail(`Gemini image generation declined: ${declined.finishReason}${suffix}`);
+            }
+            return fail('Gemini image API response: no image parts in response');
+        }
+        return 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
+ */
+export async function callProviderImageGeneration(params) {
+    var _a, _b, _c;
+    const { descriptor, apiKey, params: request, modelOverride, logger, signal, endpoint } = params;
+    if (!supportsImageGeneration(descriptor)) {
+        return fail(`provider "${descriptor.id}" does not support image generation`);
+    }
+    const baseUrlResult = resolveEffectiveBaseUrl(descriptor, endpoint);
+    if (baseUrlResult.isFailure()) {
+        return fail(baseUrlResult.message);
+    }
+    const modelResult = resolveProviderModel(descriptor, modelOverride, 'image');
+    if (modelResult.isFailure()) {
+        return fail(modelResult.message);
+    }
+    const model = modelResult.value;
+    const capability = resolveImageCapability(descriptor, model);
+    if (capability === undefined) {
+        return 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 fail(`model "${model}" does not support reference images`);
+    }
+    const resolved = resolveImageOptions(model, capability, request.options);
+    const validationResult = validateResolvedOptions(model, capability, resolved);
+    if (validationResult.isFailure()) {
+        return 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 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
+ */
+export 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 fetchJson(url, {}, body, logger, signal);
+    if (jsonResult.isFailure()) {
+        return fail(jsonResult.message);
+    }
+    const response = jsonResult.value;
+    if (typeof response.error === 'string') {
+        return fail(`proxy: ${response.error}`);
+    }
+    return proxiedImageGenerationResponse
+        .validate(response)
+        .withErrorFormat((msg) => `proxy returned invalid response: ${msg}`);
+}
+//# sourceMappingURL=imageGenerationClient.js.map