@deltakit/react 0.2.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # @deltakit/react
 
-React hook for building streaming chat UIs over Server-Sent Events (SSE). Manages the entire lifecycle -- state, network requests, SSE parsing, cancellation, and event handling -- in a single `useStreamChat` hook.
+React hook for building streaming chat UIs with pluggable transport strategies. `useStreamChat` manages message state, event handling, loading state, and transport lifecycle for direct SSE, resumable/background SSE, and WebSocket chat backends.
 
 ## Installation
 
@@ -8,7 +8,7 @@ React hook for building streaming chat UIs over Server-Sent Events (SSE). Manage
 npm install @deltakit/react
 ```
 
-Requires React 18+ and a backend endpoint that streams SSE.
+Requires React 18+.
 
 ## Quick Start
 
@@ -59,14 +59,17 @@ const {
   messages,    // Message[]           -- live-updating conversation
   isLoading,   // boolean             -- true while streaming
   error,       // Error | null        -- latest error
+  runId,       // string | null       -- resumable transport run id
   sendMessage, // (text: string) => void -- send and start streaming
-  stop,        // () => void          -- abort current stream
+  stop,        // () => void          -- request cancellation if supported
   setMessages, // React setState      -- direct state control
 } = useStreamChat({
-  api: "/api/chat",           // Required. SSE endpoint URL
+  api: "/api/chat",           // Backward-compatible direct SSE shorthand
   initialMessages: [],        // Pre-populate conversation (e.g. from DB)
   headers: {},                // Extra fetch headers (e.g. Authorization)
   body: {},                   // Extra POST body fields
+  transport: "sse",           // "sse" | "background-sse" | "websocket" | custom adapter
+  transportOptions: {},       // Grouped config for built-in transports
   onEvent: (event, helpers) => {},  // Custom event handler (replaces default)
   onFinish: (messages) => {},       // Stream ended
   onMessage: (message) => {},       // New message added
@@ -74,6 +77,115 @@ const {
 });
 ```
 
+### Transport Strategies
+
+### Direct SSE
+
+Existing callers continue to work:
+
+```tsx
+const chat = useStreamChat({
+  api: "/api/chat",
+});
+```
+
+Or use the grouped transport config:
+
+```tsx
+const chat = useStreamChat({
+  transport: "sse",
+  transportOptions: {
+    sse: {
+      api: "/api/chat",
+      headers: { Authorization: "Bearer token" },
+      body: { conversationId: "demo" },
+    },
+  },
+});
+```
+
+### Background / Resumable SSE
+
+Use this when the backend starts a job first, then exposes a reconnectable SSE stream by `runId`.
+
+```tsx
+const [activeRunId, setActiveRunId] = useState<string | null>(null);
+
+const chat = useStreamChat({
+  transport: "background-sse",
+  transportOptions: {
+    backgroundSSE: {
+      startApi: "/api/chat/jobs",
+      eventsApi: (runId) => `/api/chat/jobs/${runId}/events`,
+      statusApi: (runId) => `/api/chat/jobs/${runId}`,
+      runId: activeRunId,
+      onRunIdChange: setActiveRunId,
+    },
+  },
+});
+```
+
+If the component unmounts, the local stream disconnects. When the user returns, provide the stored `runId` again and the hook can reconnect with `resume`.
+
+### WebSocket
+
+Use this when the backend streams events over a socket instead of HTTP SSE.
+
+```tsx
+type ChatEvent =
+  | { type: "text_delta"; delta: string }
+  | { type: "tool_call"; tool_name: string; argument: string; call_id?: string };
+
+const chat = useStreamChat<ContentPart, ChatEvent>({
+  transport: "websocket",
+  transportOptions: {
+    websocket: {
+      url: "ws://localhost:8000/ws/chat",
+      body: { room: "demo" },
+      parseMessage: (data) => {
+        if (typeof data !== "string") return null;
+        return JSON.parse(data) as ChatEvent;
+      },
+    },
+  },
+});
+```
+
+### Custom Transport Adapters
+
+If your backend needs a different lifecycle, pass a custom `transport` object. The adapter only handles connection mechanics; the hook still owns message state, event helpers, loading state, and callbacks.
+
+```tsx
+const chat = useStreamChat({
+  transport: {
+    start: ({ context, message }) => {
+      const socket = new WebSocket("ws://localhost:8000/ws/chat");
+
+      socket.onopen = () => {
+        context.ensureAssistantMessage();
+        socket.send(JSON.stringify({ message }));
+      };
+
+      socket.onmessage = (event) => {
+        context.emit(JSON.parse(event.data));
+      };
+
+      socket.onerror = () => {
+        context.fail(new Error("Socket error"));
+      };
+
+      socket.onclose = () => {
+        context.finish();
+      };
+
+      return {
+        close: () => socket.close(),
+      };
+    },
+  },
+});
+```
+
 ### Event Helpers
 
 When using `onEvent`, you receive helpers for mutating message state during streaming: