chat-nest-server 1.0.1 → 1.1.0

package/README.md

@@ -1,9 +1,10 @@
 # chat-nest-server
 
-> Streaming AI backend server for Chat Nest with built-in cost protection and cancellation propagation.
+> Streaming AI backend server for Chat Nest with built-in cost protection and cancellation propagation using Server-Side Events (SSE).
 
 This package exposes an Express-compatible request handler that:
-- Streams AI responses
+- Streams AI responses using Server-Side Events (SSE)
+- Sends real-time tokens via SSE protocol
 - Enforces rate limits and budgets
 - Supports abort propagation
 - Protects against runaway usage
@@ -12,7 +13,10 @@ This package exposes an Express-compatible request handler that:
 
 ## ✨ Features
 
-- Streaming responses over HTTP
+- Server-Side Events (SSE) streaming over HTTP
+- Real-time token streaming via SSE protocol
+- SSE event types: `start`, `token`, `done`, `error`, `ping`
+- Heartbeat pings to keep connection alive
 - End-to-end cancellation support
 - Daily token budget enforcement
 - Rate limiting
@@ -31,6 +35,8 @@ npm install chat-nest-server
 ## 🚀 Usage
 Express Integration
 
+The handler automatically uses Server-Side Events (SSE) for streaming responses:
+
 ```
 import express from "express";
 import cors from "cors";
@@ -53,6 +59,13 @@ app.listen(3001, () => {
 });
 ```
 
+The handler sends SSE-formatted events:
+- `event: start\ndata: \n\n` - Stream started
+- `event: token\ndata: <token>\n\n` - Each token chunk
+- `event: done\ndata: \n\n` - Stream completed
+- `event: error\ndata: <error_json>\n\n` - Error occurred
+- `event: ping\ndata: \n\n` - Heartbeat (every 15s)
+
 ---
 
 ## 🔐 Environment Variables
@@ -63,21 +76,27 @@ app.listen(3001, () => {
 
 ## 💰 Cost Controls
 
-```
 The server enforces:
 
-Maximum tokens per request
+- Maximum tokens per request
+- Daily token budget
+- Request rate limiting
+- Prompt size trimming
+- Retry classification
 
-Daily token budget
+This prevents accidental overspending and abuse.
 
-Request rate limiting
+## 🔄 Server-Side Events (SSE)
 
-Prompt size trimming
+This package uses SSE protocol for efficient streaming:
 
-Retry classification
+- **Content-Type**: `text/event-stream`
+- **Connection**: `keep-alive`
+- **Cache-Control**: `no-cache`
+- **Heartbeat**: Ping every 15 seconds to keep connection alive
+- **Event Format**: `event: <type>\ndata: <data>\n\n`
 
-This prevents accidental overspending and abuse.
-```
+SSE provides better efficiency and real-time streaming compared to traditional polling or chunked responses.
 
 ---
 

package/dist/index.js

@@ -64,7 +64,19 @@ function createChatHandler(config) {
   return async function handler(req, res) {
     const abortController = new AbortController();
     let streamStarted = false;
+    let heartbeatInterval = null;
+    const writeSSE = (event, data) => {
+      if (abortController.signal.aborted) return;
+      res.write(`event: ${event}
+data: ${data}
+
+`);
+    };
     res.on("close", () => {
+      if (heartbeatInterval) {
+        clearInterval(heartbeatInterval);
+        heartbeatInterval = null;
+      }
       if (streamStarted && !abortController.signal.aborted) {
         abortController.abort();
       }
@@ -90,8 +102,16 @@ function createChatHandler(config) {
         });
         return;
       }
-      res.setHeader("Content-Type", "text/plain");
-      res.setHeader("Transfer-Encoding", "chunked");
+      res.setHeader("Content-Type", "text/event-stream");
+      res.setHeader("Cache-Control", "no-cache");
+      res.setHeader("Connection", "keep-alive");
+      res.flushHeaders();
+      writeSSE("start", "");
+      heartbeatInterval = setInterval(() => {
+        if (!abortController.signal.aborted) {
+          writeSSE("ping", "");
+        }
+      }, 15e3);
       const stream = await client.chat.completions.create(
         {
           model: AI_MODEL,
@@ -115,25 +135,45 @@ function createChatHandler(config) {
           }
           const token = chunk.choices[0]?.delta?.content;
           if (token) {
-            res.write(token);
+            writeSSE("token", JSON.stringify(token));
           }
         }
+        writeSSE("done", "");
       } catch (error) {
         if (abortController.signal.aborted) {
           console.log("Stream aborted by client");
         } else {
-          throw error;
+          const errorData = JSON.stringify({
+            message: error instanceof Error ? error.message : "Unknown error"
+          });
+          writeSSE("error", errorData);
         }
       } finally {
+        if (heartbeatInterval) {
+          clearInterval(heartbeatInterval);
+          heartbeatInterval = null;
+        }
         recordTokenUsage(estimatedTotalTokens);
         res.end();
       }
     } catch (error) {
       if (error?.name === "AbortError") {
+        if (heartbeatInterval) {
+          clearInterval(heartbeatInterval);
+          heartbeatInterval = null;
+        }
         return;
       }
       console.error("AI error:", error);
-      res.status(500).json({ error: "AI request failed" });
+      if (!res.headersSent) {
+        res.status(500).json({ error: "AI request failed" });
+      } else {
+        const errorData = JSON.stringify({
+          message: "AI request failed"
+        });
+        writeSSE("error", errorData);
+        res.end();
+      }
     }
   };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "chat-nest-server",
 	"description": "Streaming AI backend server with cost controls, rate limiting, and cancellation support.",
-	"version": "1.0.1",
+	"version": "1.1.0",
 	"type": "module",
 	"main": "dist/index.js",
 	"license": "ISC",