@octavus/docs 0.0.7 → 0.0.8

package/content/01-getting-started/02-quickstart.md

@@ -72,6 +72,7 @@ Create an endpoint that handles triggers and streams responses:
 
 ```typescript
 // app/api/trigger/route.ts
+import { toSSEStream } from '@octavus/server-sdk';
 import { octavus } from '@/lib/octavus';
 
 export async function POST(request: Request) {
@@ -100,11 +101,11 @@ export async function POST(request: Request) {
     },
   });
 
-  // Trigger the action and get the stream
-  const { stream } = session.trigger(triggerName, input);
+  // Trigger the action and convert to SSE stream
+  const events = session.trigger(triggerName, input);
 
   // Return as streaming response
-  return new Response(stream, {
+  return new Response(toSSEStream(events), {
     headers: {
       'Content-Type': 'text/event-stream',
       'Cache-Control': 'no-cache',

package/content/02-server-sdk/01-overview.md

@@ -63,12 +63,15 @@ const session = client.agentSessions.attach(sessionId, {
 All responses stream in real-time:
 
 ```typescript
-const { stream } = session.trigger('user-message', {
+import { toSSEStream } from '@octavus/server-sdk';
+
+// trigger() returns an async generator of events
+const events = session.trigger('user-message', {
   USER_MESSAGE: 'Hello!',
 });
 
-// Use as a streaming response
-return new Response(stream, {
+// Convert to SSE stream for HTTP responses
+return new Response(toSSEStream(events), {
   headers: { 'Content-Type': 'text/event-stream' },
 });
 ```
@@ -138,15 +141,18 @@ Handles triggering and streaming for a specific session.
 
 ```typescript
 class AgentSession {
-  // Trigger an action and stream the response
+  // Trigger an action and stream parsed events
   trigger(
     triggerName: string,
     input?: Record<string, unknown>
-  ): { stream: ReadableStream<Uint8Array> };
+  ): AsyncGenerator<StreamEvent>;
 
   // Get the session ID
   getSessionId(): string;
 }
+
+// Helper to convert events to SSE stream
+function toSSEStream(events: AsyncIterable<StreamEvent>): ReadableStream<Uint8Array>;
 ```
 
 ## Next Steps

package/content/02-server-sdk/02-sessions.md

@@ -95,12 +95,15 @@ const session = client.agentSessions.attach(sessionId, {
 Once attached, trigger actions on the session:
 
 ```typescript
-const { stream } = session.trigger('user-message', {
+import { toSSEStream } from '@octavus/server-sdk';
+
+// trigger() returns an async generator of events
+const events = session.trigger('user-message', {
   USER_MESSAGE: 'How do I reset my password?',
 });
 
-// Return the stream to your frontend
-return new Response(stream, {
+// Convert to SSE stream for HTTP responses
+return new Response(toSSEStream(events), {
   headers: { 'Content-Type': 'text/event-stream' },
 });
 ```

package/content/02-server-sdk/03-tools.md

@@ -168,6 +168,8 @@ sequenceDiagram
 For request-specific data (auth, headers), create handlers dynamically:
 
 ```typescript
+import { toSSEStream } from '@octavus/server-sdk';
+
 // In your API route
 export async function POST(request: Request) {
   const authToken = request.headers.get('Authorization');
@@ -190,8 +192,8 @@ export async function POST(request: Request) {
     },
   });
   
-  const { stream } = session.trigger(triggerName, input);
-  return new Response(stream);
+  const events = session.trigger(triggerName, input);
+  return new Response(toSSEStream(events));
 }
 ```
 

package/content/02-server-sdk/04-streaming.md

@@ -9,21 +9,29 @@ All Octavus responses stream in real-time using Server-Sent Events (SSE). This e
 
 ## Stream Response
 
-When you trigger an action, you get a readable stream:
+When you trigger an action, you get an async generator of parsed events:
 
 ```typescript
-const { stream } = session.trigger('user-message', { 
+import { toSSEStream } from '@octavus/server-sdk';
+
+// trigger() returns an async generator of StreamEvent
+const events = session.trigger('user-message', { 
   USER_MESSAGE: 'Hello!' 
 });
 
-// Return to frontend as streaming response
-return new Response(stream, {
+// For HTTP endpoints, convert to SSE stream
+return new Response(toSSEStream(events), {
   headers: {
     'Content-Type': 'text/event-stream',
     'Cache-Control': 'no-cache',
     'Connection': 'keep-alive',
   },
 });
+
+// For sockets, iterate events directly
+for await (const event of events) {
+  conn.write(JSON.stringify(event));
+}
 ```
 
 ## Event Types

package/content/03-client-sdk/01-overview.md

@@ -36,10 +36,14 @@ npm install @octavus/client-sdk
 
 The Client SDK uses a **transport abstraction** to handle communication with your backend. This gives you flexibility in how events are delivered:
 
-| Transport | Use Case |
-|-----------|----------|
-| `createHttpTransport` | HTTP/SSE (Next.js, Express, etc.) |
-| `createSocketTransport` | WebSocket, SockJS, or other socket protocols |
+| Transport | Use Case | Docs |
+|-----------|----------|------|
+| `createHttpTransport` | HTTP/SSE (Next.js, Express, etc.) | [HTTP Transport](/docs/client-sdk/http-transport) |
+| `createSocketTransport` | WebSocket, SockJS, or other socket protocols | [Socket Transport](/docs/client-sdk/socket-transport) |
+
+When the transport changes (e.g., when `sessionId` changes), the `useOctavusChat` hook automatically reinitializes with the new transport.
+
+> **Recommendation**: Use HTTP transport unless you specifically need WebSocket features (custom real-time events, Meteor/Phoenix, etc.).
 
 ## React Usage
 
@@ -294,7 +298,9 @@ class OctavusChat {
 
 ## Next Steps
 
+- [HTTP Transport](/docs/client-sdk/http-transport) — HTTP/SSE integration (recommended)
+- [Socket Transport](/docs/client-sdk/socket-transport) — WebSocket and SockJS integration
 - [Messages](/docs/client-sdk/messages) — Working with message state
 - [Streaming](/docs/client-sdk/streaming) — Building streaming UIs
 - [Operations](/docs/client-sdk/execution-blocks) — Showing agent progress
-- [Socket Transport](/docs/client-sdk/socket-transport) — WebSocket and SockJS integration
+- [Examples](/docs/examples/overview) — Complete working examples