@fgv/ts-extras 5.1.0-16 → 5.1.0-17

package/lib/packlets/ai-assist/streamingAdapters/proxy.js

@@ -0,0 +1,160 @@
+"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.
+var __await = (this && this.__await) || function (v) { return this instanceof __await ? (this.v = v, this) : new __await(v); }
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+var __asyncGenerator = (this && this.__asyncGenerator) || function (thisArg, _arguments, generator) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var g = generator.apply(thisArg, _arguments || []), i, q = [];
+    return i = Object.create((typeof AsyncIterator === "function" ? AsyncIterator : Object).prototype), verb("next"), verb("throw"), verb("return", awaitReturn), i[Symbol.asyncIterator] = function () { return this; }, i;
+    function awaitReturn(f) { return function (v) { return Promise.resolve(v).then(f, reject); }; }
+    function verb(n, f) { if (g[n]) { i[n] = function (v) { return new Promise(function (a, b) { q.push([n, v, a, b]) > 1 || resume(n, v); }); }; if (f) i[n] = f(i[n]); } }
+    function resume(n, v) { try { step(g[n](v)); } catch (e) { settle(q[0][3], e); } }
+    function step(r) { r.value instanceof __await ? Promise.resolve(r.value.v).then(fulfill, reject) : settle(q[0][2], r); }
+    function fulfill(value) { resume("next", value); }
+    function reject(value) { resume("throw", value); }
+    function settle(f, v) { if (f(v), q.shift(), q.length) resume(q[0][0], q[0][1]); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.callProxiedCompletionStream = callProxiedCompletionStream;
+/**
+ * Streaming adapter for a caller-provided proxy server. Unlike the
+ * provider-specific adapters, the proxy speaks our own unified vocabulary
+ * directly: each `data:` line is a JSON-serialized {@link AiAssist.IAiStreamEvent},
+ * so this adapter only validates the event-type discriminator and forwards.
+ *
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const sseParser_1 = require("../sseParser");
+const common_1 = require("./common");
+const proxyEventTypes = ['text-delta', 'tool-event', 'done', 'error'];
+const proxyEventEnvelope = ts_utils_1.Validators.object({
+    type: ts_utils_1.Validators.enumeratedValue(proxyEventTypes)
+});
+// ============================================================================
+// Stream translator
+// ============================================================================
+/**
+ * Translates a proxied SSE stream back into {@link AiAssist.IAiStreamEvent} objects.
+ * Validation is limited to the type discriminator; the proxy is contractually
+ * required to emit shape-correct unified events.
+ *
+ * @internal
+ */
+function translateProxyStream(response) {
+    return __asyncGenerator(this, arguments, function* translateProxyStream_1() {
+        var _a, e_1, _b, _c;
+        try {
+            /* c8 ignore next - body is non-null at this point per openSseConnection */
+            if (!response.body)
+                return yield __await(void 0);
+            try {
+                for (var _d = true, _e = __asyncValues((0, sseParser_1.readSseEvents)(response.body)), _f; _f = yield __await(_e.next()), _a = _f.done, !_a; _d = true) {
+                    _c = _f.value;
+                    _d = false;
+                    const message = _c;
+                    const json = (0, sseParser_1.parseSseEventJson)(message.data);
+                    if (json === undefined) {
+                        continue;
+                    }
+                    const envelope = (0, common_1.validateEventPayload)(json, proxyEventEnvelope);
+                    if (!envelope) {
+                        continue;
+                    }
+                    const event = json;
+                    yield yield __await(event);
+                    if (envelope.type === 'done' || envelope.type === 'error') {
+                        return yield __await(void 0);
+                    }
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (!_d && !_a && (_b = _e.return)) yield __await(_b.call(_e));
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+        }
+        catch (err) {
+            yield yield __await({ type: 'error', message: err instanceof Error ? err.message : String(err) });
+        }
+    });
+}
+// ============================================================================
+// Public entry point
+// ============================================================================
+/**
+ * Calls the streaming chat endpoint on a proxy server instead of calling
+ * the provider directly from the browser.
+ *
+ * @remarks
+ * Proxy contract:
+ * - Endpoint: `POST ${proxyUrl}/api/ai/completion-stream`
+ * - Request body: same JSON as `/api/ai/completion` plus `"stream": true`
+ * - Response: `Content-Type: text/event-stream`; body is the unified
+ *   {@link AiAssist.IAiStreamEvent} JSON-serialized one event per SSE `data:` line
+ *   (no `event:` line needed since the type discriminator is in the JSON).
+ * - Error response (when the proxy can't even start): JSON `{error: string}`
+ *   with a non-2xx status, surfaced as `proxy: ${error}`.
+ *
+ * The proxy server is responsible for opening the upstream SSE connection,
+ * translating provider-native events to the unified vocabulary, and
+ * forwarding events as they arrive (no buffering). The library does not
+ * ship a proxy implementation.
+ *
+ * @public
+ */
+async function callProxiedCompletionStream(proxyUrl, params) {
+    const { descriptor, apiKey, prompt, messagesBefore, temperature, modelOverride, logger, tools, signal } = params;
+    const promptBody = { system: prompt.system, user: prompt.user };
+    if (prompt.attachments.length > 0) {
+        promptBody.attachments = prompt.attachments;
+    }
+    const body = {
+        providerId: descriptor.id,
+        apiKey,
+        prompt: promptBody,
+        temperature: temperature !== null && temperature !== void 0 ? temperature : 0.7,
+        stream: true
+    };
+    if (messagesBefore && messagesBefore.length > 0) {
+        body.messagesBefore = messagesBefore;
+    }
+    if (modelOverride !== undefined) {
+        body.modelOverride = modelOverride;
+    }
+    if (tools && tools.length > 0) {
+        body.tools = tools;
+    }
+    /* c8 ignore next 1 - optional logger */
+    logger === null || logger === void 0 ? void 0 : logger.info(`AI streaming proxy request: provider=${descriptor.id}, proxy=${proxyUrl}`);
+    const url = `${proxyUrl}/api/ai/completion-stream`;
+    const conn = await (0, common_1.openSseConnection)(url, {}, body, logger, signal);
+    return conn.onSuccess((response) => (0, ts_utils_1.succeed)(translateProxyStream(response)));
+}
+//# sourceMappingURL=proxy.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * Streaming chat completion client. Public façade over the per-format
+ * adapters under `streamingAdapters/`: provider dispatch and pre-flight
+ * validation live here; format-specific request/translation logic and the
+ * typed event-payload validators live with each adapter.
+ *
+ * @packageDocumentation
+ */
+import { Result } from '@fgv/ts-utils';
+import { type IAiStreamEvent } from './model';
+import { type IProviderCompletionStreamParams } from './streamingAdapters/common';
+export { callProxiedCompletionStream } from './streamingAdapters/proxy';
+export type { IProviderCompletionStreamParams } from './streamingAdapters/common';
+/**
+ * Calls the appropriate streaming chat completion API for a given provider.
+ *
+ * @remarks
+ * Pre-flight rejection: when `descriptor.streamingCorsRestricted === true`
+ * and the call isn't being routed through a proxy, this returns
+ * `Result.fail` before fetch is invoked. Callers should route through
+ * {@link AiAssist.callProxiedCompletionStream} or surface the failure to the user.
+ *
+ * Connection-time failures (auth, network, non-2xx) surface as the outer
+ * `Result.fail`. Once iteration begins, errors mid-stream surface as a
+ * terminal error event ({@link AiAssist.IAiStreamError}) followed by the iterable
+ * ending. The final successful event is {@link AiAssist.IAiStreamDone}.
+ *
+ * @param params - Request parameters including descriptor, API key, prompt, and optional tools
+ * @returns A streaming iterable of unified events, or a Result.fail
+ * @public
+ */
+export declare function callProviderCompletionStream(params: IProviderCompletionStreamParams): Promise<Result<AsyncIterable<IAiStreamEvent>>>;
+//# sourceMappingURL=streamingClient.d.ts.map

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

@@ -0,0 +1,93 @@
+"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.callProxiedCompletionStream = void 0;
+exports.callProviderCompletionStream = callProviderCompletionStream;
+/**
+ * Streaming chat completion client. Public façade over the per-format
+ * adapters under `streamingAdapters/`: provider dispatch and pre-flight
+ * validation live here; format-specific request/translation logic and the
+ * typed event-payload validators live with each adapter.
+ *
+ * @packageDocumentation
+ */
+const ts_utils_1 = require("@fgv/ts-utils");
+const model_1 = require("./model");
+const anthropic_1 = require("./streamingAdapters/anthropic");
+const gemini_1 = require("./streamingAdapters/gemini");
+const openaiChat_1 = require("./streamingAdapters/openaiChat");
+const openaiResponses_1 = require("./streamingAdapters/openaiResponses");
+var proxy_1 = require("./streamingAdapters/proxy");
+Object.defineProperty(exports, "callProxiedCompletionStream", { enumerable: true, get: function () { return proxy_1.callProxiedCompletionStream; } });
+/**
+ * Calls the appropriate streaming chat completion API for a given provider.
+ *
+ * @remarks
+ * Pre-flight rejection: when `descriptor.streamingCorsRestricted === true`
+ * and the call isn't being routed through a proxy, this returns
+ * `Result.fail` before fetch is invoked. Callers should route through
+ * {@link AiAssist.callProxiedCompletionStream} or surface the failure to the user.
+ *
+ * Connection-time failures (auth, network, non-2xx) surface as the outer
+ * `Result.fail`. Once iteration begins, errors mid-stream surface as a
+ * terminal error event ({@link AiAssist.IAiStreamError}) followed by the iterable
+ * ending. The final successful event is {@link AiAssist.IAiStreamDone}.
+ *
+ * @param params - Request parameters including descriptor, API key, prompt, and optional tools
+ * @returns A streaming iterable of unified events, or a Result.fail
+ * @public
+ */
+async function callProviderCompletionStream(params) {
+    const { descriptor, apiKey, prompt, messagesBefore, temperature = 0.7, modelOverride, logger, tools, signal } = params;
+    if (!descriptor.baseUrl) {
+        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" has no API endpoint configured`);
+    }
+    if (descriptor.streamingCorsRestricted) {
+        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" requires a proxy for streaming; none is configured`);
+    }
+    if (prompt.attachments.length > 0 && !descriptor.acceptsImageInput) {
+        return (0, ts_utils_1.fail)(`provider "${descriptor.id}" does not accept image input`);
+    }
+    const hasTools = tools !== undefined && tools.length > 0;
+    const modelContext = hasTools ? 'tools' : undefined;
+    const config = {
+        baseUrl: descriptor.baseUrl,
+        apiKey,
+        model: (0, model_1.resolveModel)(modelOverride !== null && modelOverride !== void 0 ? modelOverride : descriptor.defaultModel, modelContext)
+    };
+    switch (descriptor.apiFormat) {
+        case 'openai':
+            if (hasTools) {
+                return (0, openaiResponses_1.callOpenAiResponsesStream)(config, prompt, tools, messagesBefore, temperature, logger, signal);
+            }
+            return (0, openaiChat_1.callOpenAiChatStream)(config, prompt, messagesBefore, temperature, logger, signal);
+        case 'anthropic':
+            return (0, anthropic_1.callAnthropicStream)(config, prompt, messagesBefore, temperature, tools, logger, signal);
+        case 'gemini':
+            return (0, gemini_1.callGeminiStream)(config, prompt, messagesBefore, temperature, tools, logger, signal);
+        /* c8 ignore next 4 - defensive coding: exhaustive switch guaranteed by TypeScript */
+        default: {
+            const _exhaustive = descriptor.apiFormat;
+            return (0, ts_utils_1.fail)(`unsupported API format: ${String(_exhaustive)}`);
+        }
+    }
+}
+//# sourceMappingURL=streamingClient.js.map

package/lib/packlets/conversion/converters.d.ts

@@ -30,7 +30,7 @@ export declare const isoDateTime: Converter<DateTime, unknown>;
  * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
  * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
  * @param converter - `Converter` used to convert each item in the array
- * @param ignoreErrors - Specifies treatment of unconvertible elements
+ * @param onError - Specifies treatment of unconvertible elements
  * @beta
  */
 export declare function extendedArrayOf<T, TC = undefined>(label: string, converter: Converter<T, TC>, onError?: Conversion.OnError): Converter<ExtendedArray<T>, TC>;

package/lib/packlets/conversion/converters.js

@@ -111,7 +111,7 @@ exports.isoDateTime = new ts_utils_1.Conversion.BaseConverter((from) => {
  * If `onError` is `'failOnError'` (default), then the entire conversion fails if any element cannot
  * be converted.  If `onError` is `'ignoreErrors'`, then failing elements are silently ignored.
  * @param converter - `Converter` used to convert each item in the array
- * @param ignoreErrors - Specifies treatment of unconvertible elements
+ * @param onError - Specifies treatment of unconvertible elements
  * @beta
  */
 function extendedArrayOf(label, converter, onError = 'failOnError') {

package/lib/packlets/zip-file-tree/zipFileTreeAccessors.d.ts

@@ -132,8 +132,8 @@ export declare class ZipFileTreeAccessors<TCT extends string = string> implement
     private constructor();
     /**
      * Default function to infer the content type of a file.
-     * @param filePath - The path of the file.
-     * @param provided - Optional supplied content type.
+     * @param __filePath - The path of the file.
+     * @param __provided - Optional supplied content type.
      * @returns `Success` with the content type of the file if successful, or
      * `Failure` with an error message otherwise.
      * @remarks This default implementation always returns `Success` with `undefined`.

package/lib/packlets/zip-file-tree/zipFileTreeAccessors.js

@@ -149,8 +149,8 @@ class ZipFileTreeAccessors {
     }
     /**
      * Default function to infer the content type of a file.
-     * @param filePath - The path of the file.
-     * @param provided - Optional supplied content type.
+     * @param __filePath - The path of the file.
+     * @param __provided - Optional supplied content type.
      * @returns `Success` with the content type of the file if successful, or
      * `Failure` with an error message otherwise.
      * @remarks This default implementation always returns `Success` with `undefined`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-extras",
-  "version": "5.1.0-16",
+  "version": "5.1.0-17",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "types": "dist/ts-extras.d.ts",
@@ -86,10 +86,10 @@
     "@types/js-yaml": "~4.0.9",
     "typedoc": "~0.28.16",
     "typedoc-plugin-markdown": "~4.9.0",
-    "@fgv/typedoc-compact-theme": "5.1.0-16",
-    "@fgv/heft-dual-rig": "5.1.0-16",
-    "@fgv/ts-utils-jest": "5.1.0-16",
-    "@fgv/ts-utils": "5.1.0-16"
+    "@fgv/ts-utils-jest": "5.1.0-17",
+    "@fgv/typedoc-compact-theme": "5.1.0-17",
+    "@fgv/ts-utils": "5.1.0-17",
+    "@fgv/heft-dual-rig": "5.1.0-17"
   },
   "dependencies": {
     "luxon": "^3.7.2",
@@ -97,10 +97,10 @@
     "papaparse": "^5.4.1",
     "fflate": "~0.8.2",
     "js-yaml": "~4.1.1",
-    "@fgv/ts-json-base": "5.1.0-16"
+    "@fgv/ts-json-base": "5.1.0-17"
   },
   "peerDependencies": {
-    "@fgv/ts-utils": "5.1.0-16"
+    "@fgv/ts-utils": "5.1.0-17"
   },
   "repository": {
     "type": "git",