@combycode/llm-sdk 1.1.0 → 1.3.0

package/dist/llm/providers/anthropic/messages.d.ts

@@ -26,5 +26,8 @@ export declare class AnthropicAdapter implements ProviderAdapter {
     private buildContentPart;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Stateless — every event is self-contained (code-execution result blocks
+     *  arrive complete in a single content_block_start). */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     private parseUsage;
 }

package/dist/llm/providers/google/generate.d.ts

@@ -23,5 +23,12 @@ export declare class GoogleAdapter implements ProviderAdapter {
     private buildContent;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Stateful — Google splits the code-execution marker (`executableCode` /
+     *  `codeExecutionResult`) and the produced file (`inlineData`) across parts and
+     *  often across SSE events. The closure remembers "code execution began in this
+     *  stream" so a later `inlineData` blob is routed to `files` (a code-exec
+     *  artifact) rather than `media` (conversational output). */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
+    private streamEvents;
     private parseUsage;
 }

package/dist/llm/providers/google/interactions.d.ts

@@ -26,5 +26,7 @@ export declare class GoogleInteractionsAdapter implements ProviderAdapter {
     enableStreaming(providerReq: ProviderHttpRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Stateless — the Interactions adapter surfaces no code-execution file outputs. */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     private parseUsage;
 }

package/dist/llm/providers/openai/completions.d.ts

@@ -21,5 +21,7 @@ export declare class OpenAIAdapter implements ProviderAdapter {
     enableStreaming(providerReq: ProviderHttpRequest, _req: NormalizedRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Stateless — Chat Completions has no hosted code-execution file outputs. */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     private parseUsage;
 }

package/dist/llm/providers/openai/responses.d.ts

@@ -25,5 +25,8 @@ export declare class OpenAIResponsesAdapter implements ProviderAdapter {
     enableStreaming(providerReq: ProviderHttpRequest): void;
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Stateless — each output item finalizes with all its file annotations in a
+     *  single response.output_item.done event. */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     protected parseUsage(u: Record<string, unknown> | undefined): Usage;
 }

package/dist/llm/types/provider.d.ts

@@ -25,8 +25,16 @@ export interface ProviderAdapter {
     buildRequest(req: NormalizedRequest): ProviderHttpRequest;
     /** Parse provider's raw HTTP response body to a normalized CompletionResponse. */
     parseResponse(raw: unknown, latencyMs: number): CompletionResponse;
-    /** Convert one SSE event from the provider stream into zero or more StreamEvents. */
+    /** Convert one SSE event from the provider stream into zero or more StreamEvents.
+     *  Stateless per-event primitive — see `createStreamParser` for the per-stream
+     *  entry point the client actually calls. */
     parseStreamEvent(event: SSEEvent): StreamEvent[];
+    /** Create a per-stream parser. Returns a function that converts each SSE event
+     *  into zero or more StreamEvents, holding any per-stream state (e.g. whether the
+     *  turn has begun hosted code execution) in its closure. The client calls this
+     *  once per `stream()` so each stream gets isolated state. Stateless adapters
+     *  return `parseStreamEvent` bound to themselves. */
+    createStreamParser(): (event: SSEEvent) => StreamEvent[];
     /** Auth headers (Bearer / x-api-key / etc.). */
     authHeaders(): Record<string, string>;
     /** Base URL — provider's domain root. */

package/dist/llm/types/response.d.ts

@@ -34,8 +34,15 @@ export interface FileOutput {
     mimeType?: string;
     /** Inline bytes (base64) when the provider returns the file inline; else absent. */
     data?: string;
+    /** URL to fetch the file when the provider returns one (e.g. OpenAI code-interpreter
+     *  image outputs); else absent. */
+    url?: string;
     /** What produced it (e.g. 'code_execution'). */
     source?: string;
+    /** Provider-specific retrieval hints, used by `retrieveFile`/`streamFile` when the
+     *  file is fetched by `id` (e.g. OpenAI container files set `{ containerId }`).
+     *  Absent for providers that don't need extra context. */
+    ref?: Record<string, unknown>;
 }
 export type FinishReason = 'stop' | 'tool_use' | 'length' | 'content_filter' | 'error';
 export interface Usage {

package/dist/llm/types/stream.d.ts

@@ -1,6 +1,6 @@
 /** Universal streaming event types. */
 import type { ModerationEntry } from '../moderation/types';
-import type { Usage } from './response';
+import type { FileOutput, Usage } from './response';
 export type MediaStreamType = 'image' | 'audio' | 'video';
 export type StreamEvent = {
     type: 'text';
@@ -41,6 +41,14 @@ export type StreamEvent = {
     type: 'media_end';
     mediaId?: string;
 }
+/** A hosted-tool output file (e.g. a code-execution chart/CSV) became available.
+ *  Carries the `FileOutput` descriptor (id / url / inline data + name / mimeType),
+ *  not the bytes — fetch those via `retrieveFile` / `streamFile`. The same file
+ *  is also collected onto the streamed final response's `files`. */
+ | {
+    type: 'file';
+    file: FileOutput;
+}
 /** A moderation result for the input or output. `source` distinguishes a
  *  provider-native result from a client-emulated one. Emitted by the moderation
  *  option (report-only). */

package/dist/network/types.d.ts

@@ -15,8 +15,10 @@ export interface HttpRequest {
     model: string;
     /** How to parse the response body. Default 'json' (LLM responses, image-gen
      *  with b64_json, video-status JSON). Use 'arraybuffer' for binary downloads
-     *  (TTS audio bytes, video file bytes). 'text' for plain-text responses. */
-    responseType?: 'json' | 'arraybuffer' | 'text';
+     *  (TTS audio bytes, video file bytes). 'text' for plain-text responses.
+     *  'stream' returns the raw `ReadableStream<Uint8Array>` body un-buffered (large
+     *  file downloads that pipe straight to a sink). */
+    responseType?: 'json' | 'arraybuffer' | 'text' | 'stream';
     /** When the request body is already a Uint8Array / ArrayBuffer (binary
      *  upload like multipart) the queue should NOT JSON.stringify it. Default
      *  false → body is JSON.stringify'd. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@combycode/llm-sdk",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Unified, pluggable AI SDK for accessing the LLMs of every major provider (Anthropic, OpenAI, Google, xAI, OpenRouter) through one API. Cross-environment: Node, Bun, and the browser.",
   "type": "module",
   "main": "./dist/index.js",