@yourgpt/llm-sdk 1.3.0 → 1.4.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { G as GenerateTextParams, a as GenerateTextResult, S as StreamTextParams, b as StreamTextResult, T as ToolContext, c as Tool } from './types-CdORv1Yu.js';
 export { A as AssistantMessage, C as CoreMessage, t as DEFAULT_CAPABILITIES, D as DoGenerateParams, d as DoGenerateResult, E as ErrorChunk, F as FilePart, q as FinishChunk, s as FinishReason, k as GenerateStep, I as ImagePart, L as LanguageModel, M as ModelCapabilities, R as ResponseOptions, m as StreamChunk, l as StreamPart, e as SystemMessage, n as TextDeltaChunk, h as TextPart, r as TokenUsage, i as ToolCall, o as ToolCallChunk, f as ToolMessage, j as ToolResult, p as ToolResultChunk, g as UserContentPart, U as UserMessage } from './types-CdORv1Yu.js';
 import { z } from 'zod';
-import { ActionDefinition, ToolDefinition, AgentLoopConfig, KnowledgeBaseConfig, DoneEventMessage, StreamEvent, Message, AIProvider as AIProvider$1, ToolResponse } from '@yourgpt/copilot-sdk/core';
+import { ActionDefinition, ToolDefinition, AgentLoopConfig, KnowledgeBaseConfig, DoneEventMessage, StreamEvent, ToolCallInfo, Message, AIProvider as AIProvider$1, ToolResponse } from '@yourgpt/copilot-sdk/core';
 export { ActionDefinition, AgentLoopConfig, LLMConfig, Message, StreamEvent, ToolDefinition, ToolExecution, ToolLocation, ToolResponse, UnifiedToolCall, UnifiedToolResult } from '@yourgpt/copilot-sdk/core';
 import { A as AIProvider } from './types-0uwUGKFS.js';
 export { a as AnthropicProviderConfig, e as AnthropicTool, g as AnthropicToolResult, f as AnthropicToolUse, b as AzureProviderConfig, B as BaseProviderConfig, l as GeminiFunctionCall, k as GeminiFunctionDeclaration, m as GeminiFunctionResponse, G as GoogleProviderConfig, c as OllamaProviderConfig, O as OpenAIProviderConfig, h as OpenAITool, i as OpenAIToolCall, j as OpenAIToolResult, P as ProviderCapabilities, d as ProviderFormatter, X as XAIProviderConfig } from './types-0uwUGKFS.js';
@@ -418,6 +418,223 @@ interface HandleRequestOptions {
     onFinish?: (result: HandleRequestResult) => Promise<void> | void;
 }
 
+/**
+ * StreamResult - Industry-standard streaming result object
+ *
+ * Provides multiple ways to consume streaming responses:
+ * - Web API: toResponse(), toTextResponse()
+ * - Node.js/Express: pipeToResponse(), pipeTextToResponse()
+ * - Collection: collect(), text()
+ * - Iteration: for await...of
+ *
+ * @example
+ * ```typescript
+ * // Express - one-liner
+ * app.post('/chat', async (req, res) => {
+ *   await runtime.stream(req.body).pipeToResponse(res);
+ * });
+ *
+ * // Next.js
+ * export async function POST(req: Request) {
+ *   const body = await req.json();
+ *   return runtime.stream(body).toResponse();
+ * }
+ *
+ * // Collect full response
+ * const { text, messages } = await runtime.stream(body).collect();
+ * ```
+ */
+
+/**
+ * Options for response methods
+ */
+interface StreamResultOptions {
+    /** Additional headers to include in response */
+    headers?: Record<string, string>;
+}
+/**
+ * Collected result after consuming the stream
+ */
+interface CollectedResult {
+    /** Accumulated text content */
+    text: string;
+    /** All messages from the stream (for persistence) */
+    messages: DoneEventMessage[];
+    /** Tool calls that were made */
+    toolCalls: ToolCallInfo[];
+    /** Whether client action is required (client-side tools) */
+    requiresAction: boolean;
+    /** Raw events (for debugging) */
+    events: StreamEvent[];
+}
+/**
+ * Node.js ServerResponse interface (minimal subset)
+ * Note: Return types are `unknown` to support both Node.js (returns `this`)
+ * and Express (returns `void`) response objects.
+ */
+interface NodeServerResponse$1 {
+    setHeader(name: string, value: string | number | readonly string[]): unknown;
+    write(chunk: string | Buffer): boolean;
+    end(): unknown;
+}
+/**
+ * Event handler types for the on() method
+ */
+type TextHandler = (text: string) => void;
+type ToolCallHandler = (toolCall: ToolCallInfo) => void;
+type DoneHandler = (result: CollectedResult) => void;
+type ErrorHandler = (error: Error) => void;
+/**
+ * StreamResult provides multiple ways to consume a streaming response.
+ *
+ * This follows the industry-standard pattern used by Vercel AI SDK,
+ * OpenAI SDK, and Anthropic SDK.
+ */
+declare class StreamResult {
+    private generator;
+    private consumed;
+    private eventHandlers;
+    constructor(generator: AsyncGenerator<StreamEvent>);
+    /**
+     * Iterate over stream events
+     *
+     * @example
+     * ```typescript
+     * const result = runtime.stream(body);
+     * for await (const event of result) {
+     *   if (event.type === 'message:delta') {
+     *     console.log(event.content);
+     *   }
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncIterator<StreamEvent>;
+    /**
+     * Returns SSE Response for Web API frameworks
+     *
+     * @example
+     * ```typescript
+     * // Next.js App Router
+     * export async function POST(req: Request) {
+     *   const body = await req.json();
+     *   return runtime.stream(body).toResponse();
+     * }
+     * ```
+     */
+    toResponse(options?: StreamResultOptions): Response;
+    /**
+     * Alias for toResponse() - returns SSE Response
+     */
+    toSSEResponse(options?: StreamResultOptions): Response;
+    /**
+     * Returns text-only Response (no SSE events, just text content)
+     *
+     * @example
+     * ```typescript
+     * // Simple text streaming
+     * return runtime.stream(body).toTextResponse();
+     * ```
+     */
+    toTextResponse(options?: StreamResultOptions): Response;
+    /**
+     * Returns the underlying ReadableStream
+     *
+     * @example
+     * ```typescript
+     * const stream = runtime.stream(body).toReadableStream();
+     * // Use with custom handling
+     * ```
+     */
+    toReadableStream(): ReadableStream<Uint8Array>;
+    /**
+     * Pipe SSE stream to Node.js ServerResponse
+     *
+     * @example
+     * ```typescript
+     * // Express - one-liner
+     * app.post('/chat', async (req, res) => {
+     *   await runtime.stream(req.body).pipeToResponse(res);
+     * });
+     * ```
+     */
+    pipeToResponse(res: NodeServerResponse$1, options?: StreamResultOptions): Promise<CollectedResult>;
+    /**
+     * Pipe text-only stream to Node.js ServerResponse
+     *
+     * @example
+     * ```typescript
+     * // Express - text-only streaming
+     * app.post('/chat', async (req, res) => {
+     *   await runtime.stream(req.body).pipeTextToResponse(res);
+     * });
+     * ```
+     */
+    pipeTextToResponse(res: NodeServerResponse$1, options?: StreamResultOptions): Promise<CollectedResult>;
+    /**
+     * Collect all events and return final result
+     *
+     * @example
+     * ```typescript
+     * const { text, messages, toolCalls } = await runtime.stream(body).collect();
+     * console.log('Response:', text);
+     * ```
+     */
+    collect(): Promise<CollectedResult>;
+    /**
+     * Get final text (convenience method)
+     *
+     * @example
+     * ```typescript
+     * const text = await runtime.stream(body).text();
+     * ```
+     */
+    text(): Promise<string>;
+    /**
+     * Register event handler for streaming events
+     *
+     * @example
+     * ```typescript
+     * const result = runtime.stream(body)
+     *   .on('text', (text) => console.log('Text:', text))
+     *   .on('toolCall', (call) => console.log('Tool:', call.name))
+     *   .on('done', (result) => console.log('Final:', result.text))
+     *   .on('error', (err) => console.error('Error:', err));
+     *
+     * await result.pipeToResponse(res);
+     * ```
+     */
+    on(event: "text", handler: TextHandler): this;
+    on(event: "toolCall", handler: ToolCallHandler): this;
+    on(event: "done", handler: DoneHandler): this;
+    on(event: "error", handler: ErrorHandler): this;
+    /**
+     * Ensure stream hasn't been consumed
+     */
+    private ensureNotConsumed;
+    /**
+     * Create empty collector object
+     */
+    private createCollector;
+    /**
+     * Collect event into result
+     */
+    private collectEvent;
+    /**
+     * Call registered event handlers
+     */
+    private callEventHandlers;
+}
+/**
+ * Create a StreamResult from an async generator
+ *
+ * @example
+ * ```typescript
+ * const result = createStreamResult(generator);
+ * await result.pipeToResponse(res);
+ * ```
+ */
+declare function createStreamResult(generator: AsyncGenerator<StreamEvent>): StreamResult;
+
 /**
  * Copilot SDK Runtime
  *
@@ -538,16 +755,107 @@ declare class Runtime {
      * Convert JSON Schema to legacy parameters format
      */
     private convertInputSchemaToParameters;
+    /**
+     * Stream chat and return StreamResult with helper methods
+     *
+     * This is the recommended API for new projects. It returns a StreamResult
+     * object with multiple ways to consume the response:
+     * - `pipeToResponse(res)` for Express/Node.js
+     * - `toResponse()` for Next.js/Web API
+     * - `collect()` for non-streaming use cases
+     *
+     * @example
+     * ```typescript
+     * // Express - one-liner
+     * app.post('/chat', async (req, res) => {
+     *   await runtime.stream(req.body).pipeToResponse(res);
+     * });
+     *
+     * // Next.js App Router
+     * export async function POST(req: Request) {
+     *   const body = await req.json();
+     *   return runtime.stream(body).toResponse();
+     * }
+     *
+     * // With event handlers
+     * const result = runtime.stream(body)
+     *   .on('text', (text) => console.log(text))
+     *   .on('done', (result) => console.log('Done:', result.text));
+     * await result.pipeToResponse(res);
+     * ```
+     */
+    stream(request: ChatRequest, options?: {
+        signal?: AbortSignal;
+    }): StreamResult;
+    /**
+     * Chat and collect the full response (non-streaming)
+     *
+     * Convenience method that calls stream().collect() for you.
+     * Use this when you need the complete response before responding.
+     *
+     * @example
+     * ```typescript
+     * const { text, messages, toolCalls } = await runtime.chat(body);
+     * console.log('Response:', text);
+     * res.json({ response: text });
+     * ```
+     */
+    chat(request: ChatRequest, options?: {
+        signal?: AbortSignal;
+    }): Promise<CollectedResult>;
+    /**
+     * Create Express-compatible handler middleware
+     *
+     * Returns a function that can be used directly as Express middleware.
+     *
+     * @example
+     * ```typescript
+     * // Simple usage
+     * app.post('/chat', runtime.expressHandler());
+     *
+     * // With options
+     * app.post('/chat', runtime.expressHandler({ format: 'text' }));
+     * ```
+     */
+    expressHandler(options?: {
+        /** Response format: 'sse' (default) or 'text' */
+        format?: "sse" | "text";
+        /** Additional headers to include */
+        headers?: Record<string, string>;
+    }): (req: {
+        body: ChatRequest;
+    }, res: {
+        setHeader(name: string, value: string): void;
+        write(chunk: string): boolean;
+        end(): void;
+        status(code: number): {
+            json(data: unknown): void;
+        };
+    }) => Promise<void>;
 }
 /**
  * Create runtime instance
  */
 declare function createRuntime(config: RuntimeConfig): Runtime;
 
+/**
+ * Node.js ServerResponse interface (minimal subset for type safety)
+ * Note: Return types are `unknown` to support both Node.js (returns `this`)
+ * and Express (returns `void`) response objects.
+ */
+interface NodeServerResponse {
+    setHeader(name: string, value: string | number | readonly string[]): unknown;
+    write(chunk: string | Buffer): boolean;
+    end(): unknown;
+}
 /**
  * Create SSE response headers
  */
 declare function createSSEHeaders(): Record<string, string>;
+/**
+ * Create text stream response headers
+ */
+declare function createTextStreamHeaders(): Record<string, string>;
 /**
  * Format event as SSE data
  */
@@ -559,7 +867,55 @@ declare function createEventStream(generator: AsyncGenerator<StreamEvent>): Read
 /**
  * Create SSE Response object
  */
-declare function createSSEResponse(generator: AsyncGenerator<StreamEvent>): Response;
+declare function createSSEResponse(generator: AsyncGenerator<StreamEvent>, options?: {
+    headers?: Record<string, string>;
+}): Response;
+/**
+ * Create text-only stream Response (no SSE events, just text content)
+ *
+ * @example
+ * ```typescript
+ * const generator = runtime.processChatWithLoop(body);
+ * return createTextStreamResponse(generator);
+ * ```
+ */
+declare function createTextStreamResponse(generator: AsyncGenerator<StreamEvent>, options?: {
+    headers?: Record<string, string>;
+}): Response;
+/**
+ * Pipe SSE stream to Node.js ServerResponse
+ *
+ * Standalone helper for piping streaming events directly to Express/Node.js responses.
+ *
+ * @example
+ * ```typescript
+ * // Express
+ * app.post('/chat', async (req, res) => {
+ *   const generator = runtime.processChatWithLoop(req.body);
+ *   await pipeSSEToResponse(generator, res);
+ * });
+ * ```
+ */
+declare function pipeSSEToResponse(generator: AsyncGenerator<StreamEvent>, res: NodeServerResponse, options?: {
+    headers?: Record<string, string>;
+}): Promise<void>;
+/**
+ * Pipe text-only stream to Node.js ServerResponse
+ *
+ * Standalone helper for piping only text content to Express/Node.js responses.
+ *
+ * @example
+ * ```typescript
+ * // Express - text only
+ * app.post('/chat', async (req, res) => {
+ *   const generator = runtime.processChatWithLoop(req.body);
+ *   await pipeTextToResponse(generator, res);
+ * });
+ * ```
+ */
+declare function pipeTextToResponse(generator: AsyncGenerator<StreamEvent>, res: NodeServerResponse, options?: {
+    headers?: Record<string, string>;
+}): Promise<void>;
 
 /**
  * Create Hono app with chat endpoint
@@ -582,32 +938,87 @@ declare function createHonoApp(runtime: Runtime): Hono;
  */
 declare function createNextHandler(config: RuntimeConfig): (request: Request) => Promise<Response>;
 /**
- * Express middleware
+ * Express middleware (Simplified with StreamResult)
+ *
+ * Creates an Express-compatible middleware that uses the new StreamResult API.
+ * Much simpler internally - no more manual request/response conversion.
  *
  * @example
  * ```ts
  * import express from 'express';
  * import { createExpressMiddleware } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
  *
  * const app = express();
+ * app.use(express.json());
  *
- * app.use('/api/chat', createExpressMiddleware({
- *   llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY! },
+ * // Simple usage
+ * app.post('/api/chat', createExpressMiddleware({
+ *   provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+ *   model: 'gpt-4o',
  * }));
+ *
+ * // With options
+ * app.post('/api/chat', createExpressMiddleware({
+ *   provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+ *   model: 'gpt-4o',
+ * }, { format: 'text' }));
  * ```
  */
-declare function createExpressMiddleware(config: RuntimeConfig): (req: {
-    method: string;
-    url: string;
-    headers: Record<string, string>;
+declare function createExpressMiddleware(config: RuntimeConfig, options?: {
+    /** Response format: 'sse' (default) or 'text' */
+    format?: "sse" | "text";
+    /** Additional headers to include */
+    headers?: Record<string, string>;
+}): (req: {
     body: unknown;
 }, res: {
     status: (code: number) => {
         json: (data: unknown) => void;
     };
-    setHeader: (name: string, value: string) => void;
-    write: (data: string) => void;
-    end: () => void;
+    setHeader: (name: string, value: string | number | readonly string[]) => unknown;
+    write: (data: string | Buffer) => boolean;
+    end: () => unknown;
+}) => Promise<void>;
+/**
+ * Create Express handler from existing Runtime instance
+ *
+ * Use this when you already have a Runtime instance and want to create
+ * an Express handler from it.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createRuntime, createExpressHandler } from '@yourgpt/llm-sdk';
+ * import { createOpenAI } from '@yourgpt/llm-sdk/openai';
+ *
+ * const runtime = createRuntime({
+ *   provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
+ *   model: 'gpt-4o',
+ * });
+ *
+ * const app = express();
+ * app.use(express.json());
+ *
+ * // Use with existing runtime
+ * app.post('/api/chat', createExpressHandler(runtime));
+ *
+ * // Or use runtime.expressHandler() directly
+ * app.post('/api/chat', runtime.expressHandler());
+ * ```
+ */
+declare function createExpressHandler(runtime: Runtime, options?: {
+    format?: "sse" | "text";
+    headers?: Record<string, string>;
+}): (req: {
+    body: ChatRequest;
+}, res: {
+    setHeader(name: string, value: string): void;
+    write(chunk: string): boolean;
+    end(): void;
+    status(code: number): {
+        json(data: unknown): void;
+    };
 }) => Promise<void>;
 /**
  * Node.js HTTP handler
@@ -681,4 +1092,4 @@ interface AgentLoopOptions {
  */
 declare function runAgentLoop(options: AgentLoopOptions): AsyncGenerator<StreamEvent>;
 
-export { AIProvider, type ActionRequest, type AgentLoopOptions, type ChatRequest, DEFAULT_MAX_ITERATIONS, GenerateTextParams, GenerateTextResult, LLMAdapter, type RequestContext, Runtime, type RuntimeConfig, StreamTextParams, StreamTextResult, Tool, ToolContext, createEventStream, createExpressMiddleware, createHonoApp, createNextHandler, createNodeHandler, createRuntime, createSSEHeaders, createSSEResponse, formatSSEData, formatToolsForAnthropic, formatToolsForGoogle, formatToolsForOpenAI, generateText, runAgentLoop, streamText, tool };
+export { AIProvider, type ActionRequest, type AgentLoopOptions, type ChatRequest, type CollectedResult, DEFAULT_MAX_ITERATIONS, GenerateTextParams, GenerateTextResult, LLMAdapter, type RequestContext, Runtime, type RuntimeConfig, StreamResult, type StreamResultOptions, StreamTextParams, StreamTextResult, Tool, ToolContext, createEventStream, createExpressHandler, createExpressMiddleware, createHonoApp, createNextHandler, createNodeHandler, createRuntime, createSSEHeaders, createSSEResponse, createStreamResult, createTextStreamHeaders, createTextStreamResponse, formatSSEData, formatToolsForAnthropic, formatToolsForGoogle, formatToolsForOpenAI, generateText, pipeSSEToResponse, pipeTextToResponse, runAgentLoop, streamText, tool };