@yourgpt/llm-sdk 1.3.0 → 1.4.0

package/dist/index.js

@@ -1363,6 +1363,12 @@ function createSSEHeaders() {
     "X-Accel-Buffering": "no"
   };
 }
+function createTextStreamHeaders() {
+  return {
+    "Content-Type": "text/plain; charset=utf-8",
+    "Cache-Control": "no-cache"
+  };
+}
 function formatSSEData(event) {
   return `data: ${JSON.stringify(event)}
 
@@ -1390,11 +1396,407 @@ function createEventStream(generator) {
     }
   });
 }
-function createSSEResponse(generator) {
+function createSSEResponse(generator, options) {
   return new Response(createEventStream(generator), {
-    headers: createSSEHeaders()
+    headers: {
+      ...createSSEHeaders(),
+      ...options?.headers
+    }
   });
 }
+function createTextStreamResponse(generator, options) {
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    async start(controller) {
+      try {
+        for await (const event of generator) {
+          if (event.type === "message:delta") {
+            controller.enqueue(encoder.encode(event.content));
+          }
+        }
+      } catch (error) {
+        console.error("[Streaming] Text stream error:", error);
+      } finally {
+        controller.close();
+      }
+    }
+  });
+  return new Response(stream, {
+    headers: {
+      ...createTextStreamHeaders(),
+      ...options?.headers
+    }
+  });
+}
+async function pipeSSEToResponse(generator, res, options) {
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache, no-transform");
+  res.setHeader("Connection", "keep-alive");
+  res.setHeader("X-Accel-Buffering", "no");
+  if (options?.headers) {
+    for (const [key, value] of Object.entries(options.headers)) {
+      res.setHeader(key, value);
+    }
+  }
+  try {
+    for await (const event of generator) {
+      res.write(formatSSEData(event));
+    }
+  } catch (error) {
+    const errorEvent = {
+      type: "error",
+      message: error instanceof Error ? error.message : "Unknown error"
+    };
+    res.write(formatSSEData(errorEvent));
+  } finally {
+    res.write("data: [DONE]\n\n");
+    res.end();
+  }
+}
+async function pipeTextToResponse(generator, res, options) {
+  res.setHeader("Content-Type", "text/plain; charset=utf-8");
+  res.setHeader("Cache-Control", "no-cache");
+  if (options?.headers) {
+    for (const [key, value] of Object.entries(options.headers)) {
+      res.setHeader(key, value);
+    }
+  }
+  try {
+    for await (const event of generator) {
+      if (event.type === "message:delta") {
+        res.write(event.content);
+      }
+    }
+  } finally {
+    res.end();
+  }
+}
+
+// src/server/stream-result.ts
+var StreamResult = class {
+  constructor(generator) {
+    this.consumed = false;
+    this.eventHandlers = /* @__PURE__ */ new Map();
+    this.generator = generator;
+  }
+  // ============================================
+  // Async Iteration (base pattern)
+  // ============================================
+  /**
+   * 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]() {
+    this.ensureNotConsumed();
+    return this.generator;
+  }
+  // ============================================
+  // Web API Response Methods (Next.js, Cloudflare, Deno)
+  // ============================================
+  /**
+   * 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) {
+    this.ensureNotConsumed();
+    const headers = {
+      ...createSSEHeaders(),
+      ...options?.headers
+    };
+    return new Response(createEventStream(this.generator), { headers });
+  }
+  /**
+   * Alias for toResponse() - returns SSE Response
+   */
+  toSSEResponse(options) {
+    return this.toResponse(options);
+  }
+  /**
+   * Returns text-only Response (no SSE events, just text content)
+   *
+   * @example
+   * ```typescript
+   * // Simple text streaming
+   * return runtime.stream(body).toTextResponse();
+   * ```
+   */
+  toTextResponse(options) {
+    this.ensureNotConsumed();
+    const encoder = new TextEncoder();
+    const generator = this.generator;
+    const stream = new ReadableStream({
+      async start(controller) {
+        try {
+          for await (const event of generator) {
+            if (event.type === "message:delta") {
+              controller.enqueue(encoder.encode(event.content));
+            }
+          }
+        } catch (error) {
+          console.error("[StreamResult] Text stream error:", error);
+        } finally {
+          controller.close();
+        }
+      }
+    });
+    return new Response(stream, {
+      headers: {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Cache-Control": "no-cache",
+        ...options?.headers
+      }
+    });
+  }
+  /**
+   * Returns the underlying ReadableStream
+   *
+   * @example
+   * ```typescript
+   * const stream = runtime.stream(body).toReadableStream();
+   * // Use with custom handling
+   * ```
+   */
+  toReadableStream() {
+    this.ensureNotConsumed();
+    return createEventStream(this.generator);
+  }
+  // ============================================
+  // Node.js/Express Response Methods
+  // ============================================
+  /**
+   * 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);
+   * });
+   * ```
+   */
+  async pipeToResponse(res, options) {
+    this.ensureNotConsumed();
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    if (options?.headers) {
+      for (const [key, value] of Object.entries(options.headers)) {
+        res.setHeader(key, value);
+      }
+    }
+    const collected = this.createCollector();
+    try {
+      for await (const event of this.generator) {
+        this.collectEvent(event, collected);
+        this.callEventHandlers(event, collected);
+        res.write(formatSSEData(event));
+      }
+    } catch (error) {
+      const errorEvent = {
+        type: "error",
+        message: error instanceof Error ? error.message : "Unknown error"
+      };
+      res.write(formatSSEData(errorEvent));
+      const errorHandler = this.eventHandlers.get("error");
+      if (errorHandler) {
+        errorHandler(error instanceof Error ? error : new Error(String(error)));
+      }
+    } finally {
+      res.write("data: [DONE]\n\n");
+      res.end();
+    }
+    const doneHandler = this.eventHandlers.get("done");
+    if (doneHandler) {
+      doneHandler(collected);
+    }
+    return collected;
+  }
+  /**
+   * 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);
+   * });
+   * ```
+   */
+  async pipeTextToResponse(res, options) {
+    this.ensureNotConsumed();
+    res.setHeader("Content-Type", "text/plain; charset=utf-8");
+    res.setHeader("Cache-Control", "no-cache");
+    if (options?.headers) {
+      for (const [key, value] of Object.entries(options.headers)) {
+        res.setHeader(key, value);
+      }
+    }
+    const collected = this.createCollector();
+    try {
+      for await (const event of this.generator) {
+        this.collectEvent(event, collected);
+        this.callEventHandlers(event, collected);
+        if (event.type === "message:delta") {
+          res.write(event.content);
+        }
+      }
+    } catch (error) {
+      const errorHandler = this.eventHandlers.get("error");
+      if (errorHandler) {
+        errorHandler(error instanceof Error ? error : new Error(String(error)));
+      }
+    } finally {
+      res.end();
+    }
+    const doneHandler = this.eventHandlers.get("done");
+    if (doneHandler) {
+      doneHandler(collected);
+    }
+    return collected;
+  }
+  // ============================================
+  // Collection Methods
+  // ============================================
+  /**
+   * Collect all events and return final result
+   *
+   * @example
+   * ```typescript
+   * const { text, messages, toolCalls } = await runtime.stream(body).collect();
+   * console.log('Response:', text);
+   * ```
+   */
+  async collect() {
+    this.ensureNotConsumed();
+    const collected = this.createCollector();
+    for await (const event of this.generator) {
+      this.collectEvent(event, collected);
+      this.callEventHandlers(event, collected);
+    }
+    const doneHandler = this.eventHandlers.get("done");
+    if (doneHandler) {
+      doneHandler(collected);
+    }
+    return collected;
+  }
+  /**
+   * Get final text (convenience method)
+   *
+   * @example
+   * ```typescript
+   * const text = await runtime.stream(body).text();
+   * ```
+   */
+  async text() {
+    const result = await this.collect();
+    return result.text;
+  }
+  on(event, handler) {
+    this.eventHandlers.set(event, handler);
+    return this;
+  }
+  // ============================================
+  // Internal Methods
+  // ============================================
+  /**
+   * Ensure stream hasn't been consumed
+   */
+  ensureNotConsumed() {
+    if (this.consumed) {
+      throw new Error(
+        "StreamResult has already been consumed. Each StreamResult can only be consumed once."
+      );
+    }
+    this.consumed = true;
+  }
+  /**
+   * Create empty collector object
+   */
+  createCollector() {
+    return {
+      text: "",
+      messages: [],
+      toolCalls: [],
+      requiresAction: false,
+      events: []
+    };
+  }
+  /**
+   * Collect event into result
+   */
+  collectEvent(event, collected) {
+    collected.events.push(event);
+    switch (event.type) {
+      case "message:delta":
+        collected.text += event.content;
+        break;
+      case "tool_calls":
+        collected.toolCalls.push(...event.toolCalls);
+        break;
+      case "done":
+        if (event.messages) {
+          collected.messages.push(...event.messages);
+        }
+        if (event.requiresAction) {
+          collected.requiresAction = true;
+        }
+        break;
+    }
+  }
+  /**
+   * Call registered event handlers
+   */
+  callEventHandlers(event, collected) {
+    switch (event.type) {
+      case "message:delta": {
+        const textHandler = this.eventHandlers.get("text");
+        if (textHandler) {
+          textHandler(event.content);
+        }
+        break;
+      }
+      case "tool_calls": {
+        const toolCallHandler = this.eventHandlers.get(
+          "toolCall"
+        );
+        if (toolCallHandler) {
+          for (const toolCall of event.toolCalls) {
+            toolCallHandler(toolCall);
+          }
+        }
+        break;
+      }
+      case "error": {
+        const errorHandler = this.eventHandlers.get("error");
+        if (errorHandler) {
+          errorHandler(new Error(event.message));
+        }
+        break;
+      }
+    }
+  }
+};
+function createStreamResult(generator) {
+  return new StreamResult(generator);
+}
 
 // src/server/runtime.ts
 function buildToolResultForAI(tool2, result, args) {
@@ -2464,6 +2866,89 @@ var Runtime = class {
     }
     return parameters;
   }
+  // ============================================
+  // StreamResult API (Industry Standard Pattern)
+  // ============================================
+  /**
+   * 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, options) {
+    const generator = this.processChatWithLoop(request, options?.signal);
+    return new StreamResult(generator);
+  }
+  /**
+   * 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 });
+   * ```
+   */
+  async chat(request, options) {
+    return this.stream(request, options).collect();
+  }
+  /**
+   * 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) {
+    return async (req, res) => {
+      try {
+        const result = this.stream(req.body);
+        if (options?.format === "text") {
+          await result.pipeTextToResponse(res, { headers: options?.headers });
+        } else {
+          await result.pipeToResponse(res, { headers: options?.headers });
+        }
+      } catch (error) {
+        console.error("[Runtime] Express handler error:", error);
+        res.status(500).json({
+          error: error instanceof Error ? error.message : "Unknown error"
+        });
+      }
+    };
+  }
 };
 function createRuntime(config) {
   return new Runtime(config);
@@ -2551,38 +3036,28 @@ function createNextHandler(config) {
     return runtime.handleRequest(request);
   };
 }
-function createExpressMiddleware(config) {
+function createExpressMiddleware(config, options) {
   const runtime = createRuntime(config);
-  createHonoApp(runtime);
   return async (req, res) => {
     try {
-      const url = new URL(req.url, "http://localhost");
-      const request = new Request(url, {
-        method: req.method,
-        headers: req.headers,
-        body: req.method !== "GET" ? JSON.stringify(req.body) : void 0
-      });
-      const response = await runtime.handleRequest(request);
-      response.headers.forEach((value, key) => {
-        res.setHeader(key, value);
-      });
-      if (response.body) {
-        const reader = response.body.getReader();
-        const decoder = new TextDecoder();
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          res.write(decoder.decode(value));
-        }
+      const result = runtime.stream(req.body);
+      const nodeRes = res;
+      if (options?.format === "text") {
+        await result.pipeTextToResponse(nodeRes, { headers: options?.headers });
+      } else {
+        await result.pipeToResponse(nodeRes, { headers: options?.headers });
       }
-      res.end();
     } catch (error) {
+      console.error("[Express Middleware] Error:", error);
       res.status(500).json({
         error: error instanceof Error ? error.message : "Unknown error"
       });
     }
   };
 }
+function createExpressHandler(runtime, options) {
+  return runtime.expressHandler(options);
+}
 function createNodeHandler(config) {
   const runtime = createRuntime(config);
   const app = createHonoApp(runtime);
@@ -3149,7 +3624,9 @@ async function executeToolCalls(toolCalls, tools, executeServerTool, waitForClie
 exports.DEFAULT_CAPABILITIES = DEFAULT_CAPABILITIES;
 exports.DEFAULT_MAX_ITERATIONS = DEFAULT_MAX_ITERATIONS;
 exports.Runtime = Runtime;
+exports.StreamResult = StreamResult;
 exports.createEventStream = createEventStream;
+exports.createExpressHandler = createExpressHandler;
 exports.createExpressMiddleware = createExpressMiddleware;
 exports.createHonoApp = createHonoApp;
 exports.createNextHandler = createNextHandler;
@@ -3157,11 +3634,16 @@ exports.createNodeHandler = createNodeHandler;
 exports.createRuntime = createRuntime;
 exports.createSSEHeaders = createSSEHeaders;
 exports.createSSEResponse = createSSEResponse;
+exports.createStreamResult = createStreamResult;
+exports.createTextStreamHeaders = createTextStreamHeaders;
+exports.createTextStreamResponse = createTextStreamResponse;
 exports.formatSSEData = formatSSEData;
 exports.formatToolsForAnthropic = formatToolsForAnthropic;
 exports.formatToolsForGoogle = formatToolsForGoogle;
 exports.formatToolsForOpenAI = formatToolsForOpenAI;
 exports.generateText = generateText;
+exports.pipeSSEToResponse = pipeSSEToResponse;
+exports.pipeTextToResponse = pipeTextToResponse;
 exports.runAgentLoop = runAgentLoop;
 exports.streamText = streamText;
 exports.tool = tool;