tina4-nodejs 3.13.112 → 3.13.113

package/types/core/src/aiClient.d.ts

@@ -21,10 +21,52 @@ export interface ChatResponse {
     finishReason: string | null;
     raw: Record<string, unknown>;
 }
+/**
+ * A multimodal content part. `text` carries plain UTF-8 prose; `image`
+ * carries a `data:<media_type>;base64,<payload>` URI or an https:// URL
+ * (the client translates to each provider's shape). ADR-0060.
+ */
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    source: string;
+};
+/** The value a caller may pass for `message.content`. ADR-0060. */
+export type AiMessageContent = string | ContentPart[];
 export interface AiMessage {
     role: "system" | "user" | "assistant";
-    content: string;
+    content: AiMessageContent;
 }
+/**
+ * One event yielded by `Ai.chat(stream: true)`. The four variants
+ * discriminated by `type`. Text deltas arrive per chunk (typewriter UX);
+ * `tool_call` fires once per call, aggregated from provider fragments;
+ * `done` fires exactly once after all deltas; `error` replaces `done` on
+ * mid-stream failure. ADR-0060.
+ */
+export type AiEvent = {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "tool_call";
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: "done";
+    finishReason: string;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+} | {
+    type: "error";
+    message: string;
+    code?: string;
+};
 export interface AiChatOptions {
     model?: string;
     temperature?: number;
@@ -41,26 +83,53 @@ export interface AiEmbedOptions {
 export declare class Ai {
     static chat(messages: AiMessage[], options: AiChatOptions & {
         stream: true;
-    }): AsyncGenerator<string>;
+    }): AsyncGenerator<AiEvent>;
     static chat(messages: AiMessage[], options?: AiChatOptions & {
         stream?: false;
     }): Promise<ChatResponse>;
     static complete(prompt: string, options?: Omit<AiChatOptions, "stream">): Promise<string>;
     static embed(textOrTexts: string | string[], options?: AiEmbedOptions): Promise<number[] | number[][]>;
+    /**
+     * Validate role + content shape. Content may be a string OR a non-empty
+     * list of {type:'text'|'image', ...} parts (ADR-0060). Malformed parts
+     * fail fast with AiConfigError, never reaching the wire.
+     */
     private static validateMessages;
+    private static validateContent;
     private static number;
     private static config;
     private static endpoint;
     private static headers;
+    /**
+     * Build the provider-specific request body from a Tina4-shaped message
+     * list. Multimodal parts are translated per provider (ADR-0060):
+     *   - OpenAI/local: {type:'image_url', image_url:{url}}
+     *   - Anthropic:    {type:'image', source:{type:'base64'|'url', ...}}
+     * String content is preserved verbatim in the OpenAI/local shape and
+     * likewise for Anthropic (both accept a bare string).
+     */
     private static chatBody;
+    /**
+     * Translate one message content value into the provider's on-wire shape.
+     * A plain string is passed through (both providers accept a string
+     * content). A parts array becomes provider-native content blocks.
+     */
+    private static translateContent;
+    private static parseDataUri;
+    private static contentToPlainText;
     private static open;
     private static readBody;
     private static retryDelay;
     private static requestJson;
     private static normalizeChat;
     private static chatResponse;
-    private static streamDelta;
-    private static streamData;
-    private static streamError;
+    /**
+     * Stream the response through the shared {@link parseSseStream} framer
+     * (ADR-0060 rule 5). Translates each SSE data payload into 0..N
+     * {@link AiEvent}s: text_delta per chunk, tool_call aggregated per
+     * index / block, exactly one done (or error) at the end.
+     */
     private static streamRequest;
+    private static responseChunks;
+    private static streamError;
 }

package/types/core/src/api.d.ts

@@ -4,6 +4,38 @@ export interface ApiResult {
     headers: Record<string, string>;
     error: string | null;
 }
+/**
+ * Options for the streaming primitives ({@link Api.streamBytes},
+ * {@link Api.streamLines}, {@link Api.streamSse}). All fields optional.
+ * `timeout` bounds the WHOLE stream (headers + body), matching
+ * `TINA4_API_TIMEOUT`; `connectTimeout` bounds only the connection +
+ * headers-arrival phase, matching `TINA4_API_CONNECT_TIMEOUT`.
+ */
+export interface StreamOptions {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    contentType?: string;
+    timeout?: number;
+    connectTimeout?: number;
+}
+/**
+ * One SSE event yielded by {@link Api.streamSse}. `data` is always present
+ * (multi-line `data:` fields are concatenated with `\n`). `event`, `id`,
+ * `retry` are set only when the corresponding SSE field appeared. `retry`
+ * is a number (milliseconds) per the SSE spec.
+ */
+export interface SseEvent {
+    data: string;
+    event?: string;
+    id?: string;
+    retry?: number;
+}
+/** Raised by the streaming primitives on a non-2xx status. */
+export declare class ApiStreamError extends Error {
+    readonly status: number | null;
+    constructor(message: string, status?: number | null);
+}
 /**
  * Result of {@link Api.download}. There is no `body` field — the response
  * body went to disk. `path` is the destination on success and `null` on any
@@ -90,6 +122,28 @@ export interface ApiOptions {
      */
     cookies?: boolean;
 }
+/**
+ * Split an async byte iterable into UTF-8 lines. Handles LF and CRLF; a
+ * multibyte codepoint that lands across a chunk boundary buffers across the
+ * split (TextDecoder({stream: true})). A trailing line without a terminator
+ * yields on EOF.
+ *
+ * Exported so {@link Api} instance methods AND `Ai.chat` streaming share
+ * one framer — ADR-0060's "no duplicate framing code" rule.
+ */
+export declare function parseLineStream(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<string>;
+/**
+ * Parse SSE (Server-Sent Events) framing from a line iterable. Yields
+ * one {@link SseEvent} per event boundary (blank line) or on EOF for a
+ * final trailing event. `:` comment lines are ignored. Fields are
+ * `data` (multi-line concatenated with `\n`), `event`, `id`, `retry`.
+ *
+ * Follows the WHATWG SSE parsing algorithm closely enough for every LLM
+ * provider (OpenAI, Anthropic, local): one leading space after the colon
+ * is stripped, unknown fields are ignored, malformed `retry:` values are
+ * ignored.
+ */
+export declare function parseSseStream(lines: AsyncIterable<string>): AsyncGenerator<SseEvent>;
 export declare class Api {
     private baseUrl;
     private headers;
@@ -209,6 +263,54 @@ export declare class Api {
      * not written on error.
      */
     download(path: string, destPath: string, params?: Record<string, string>): Promise<DownloadResult>;
+    /**
+     * Stream a response body as raw bytes. Yields the chunks the transport
+     * delivers, in order, never buffered whole. Ends cleanly on EOF and
+     * throws on a transport failure or a non-2xx status (body drained
+     * first). No JSON decoding, no line splitting, no framing —
+     * {@link streamLines} and {@link streamSse} build on this primitive.
+     *
+     * Closing the iterator before EOF (a `break` out of a `for await`)
+     * destroys the underlying socket, so a caller who takes only the
+     * first few chunks never leaks the connection.
+     *
+     * `opts.timeout` bounds the whole stream duration (default
+     * `TINA4_API_TIMEOUT` or the client `timeout`); `opts.connectTimeout`
+     * bounds just the connect + headers phase (default
+     * `TINA4_API_CONNECT_TIMEOUT` or 10s).
+     */
+    streamBytes(path: string, opts?: StreamOptions): AsyncGenerator<Uint8Array>;
+    /**
+     * Stream the response body as UTF-8 lines. Splits on LF or CRLF;
+     * buffers a multibyte codepoint that lands across a chunk boundary;
+     * yields a trailing line without a terminator on EOF. Built on
+     * {@link streamBytes} plus the shared {@link parseLineStream}.
+     */
+    streamLines(path: string, opts?: StreamOptions): AsyncGenerator<string>;
+    /**
+     * Stream the response as SSE (Server-Sent Events). Yields one
+     * {@link SseEvent} per event boundary (blank line) or on EOF for a
+     * trailing event. `data:[DONE]` is delivered as an ordinary event
+     * with `data === "[DONE]"` and the iterator ends on the next EOF.
+     * Built on {@link streamLines} plus the shared {@link parseSseStream}.
+     */
+    streamSse(path: string, opts?: StreamOptions): AsyncGenerator<SseEvent>;
+    /**
+     * Resolve a stream duration from (in order): explicit `opts` field,
+     * the named env var, then the fallback. Zero disables. A non-numeric
+     * or negative env value warns via a fallback rather than throwing —
+     * a bad env var must not brick every streaming call.
+     */
+    private streamSeconds;
+    /**
+     * Open a streaming HTTP request. Returns the raw
+     * {@link http.IncomingMessage} once headers arrive. Redirects are NOT
+     * followed on streams (a caller who needs a redirect should do a
+     * regular GET first). Connect phase is bounded by `connectSec`;
+     * body-phase timeout is applied by the caller (streamBytes) via
+     * `res.destroy()`.
+     */
+    private openStreamRequest;
     private buildUrl;
     /**
      * Build the request headers (default User-Agent + auth + cookie jar +

package/types/core/src/index.d.ts

@@ -39,8 +39,8 @@ export { ServiceRunner, Tina4Service, matchCronField, matchesCron } from "./serv
 export type { ServiceOptions, ServiceContext, ServiceHandler, ServiceInfo } from "./service.js";
 export { responseCache, clearCache, cacheStats, cacheGet, cacheSet, cacheDelete, cacheClear, cacheBackendStats, sweep, createBackend, _resetBackend } from "./cache.js";
 export type { ResponseCacheConfig, CacheBackend } from "./cache.js";
-export { Api } from "./api.js";
-export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions } from "./api.js";
+export { Api, ApiStreamError, parseLineStream, parseSseStream } from "./api.js";
+export type { ApiResult, ApiOptions, ApiTransport, DownloadResult, UploadOptions, StreamOptions, SseEvent } from "./api.js";
 export { Context, defaultContext, existingContext, fts5Supported, _sharedContexts } from "./context/index.js";
 export type { SearchHit } from "./context/index.js";
 export { Events } from "./events.js";
@@ -58,7 +58,7 @@ export type { AiTool } from "./ai.js";
 export { Sso, SSO, SsoError } from "./sso.js";
 export type { SsoOptions } from "./sso.js";
 export { Ai, AiError, AiConfigError, AiHTTPError, AiTimeoutError, AiParseError } from "./aiClient.js";
-export type { ChatResponse, AiMessage, AiChatOptions, AiEmbedOptions } from "./aiClient.js";
+export type { ChatResponse, AiMessage, AiChatOptions, AiEmbedOptions, AiEvent, ContentPart, AiMessageContent } from "./aiClient.js";
 export type { ImapMessage, ImapFullMessage, ImapAttachment } from "./messenger.js";
 export { LiteBackend } from "./queueBackends/liteBackend.js";
 export { RabbitMQBackend, parseAmqpUrl } from "./queueBackends/rabbitmqBackend.js";