@octavus/docs 0.0.9 → 1.0.0

package/content/03-client-sdk/05-socket-transport.md

@@ -9,22 +9,80 @@ The socket transport enables real-time bidirectional communication using WebSock
 
 ## When to Use Socket Transport
 
-| Use Case | Recommended Transport |
-|----------|----------------------|
-| Standard web apps (Next.js, etc.) | HTTP (`createHttpTransport`) |
-| Real-time apps with custom events | Socket (`createSocketTransport`) |
-| Apps behind proxies that don't support SSE | Socket |
-| Need for typing indicators, presence, etc. | Socket |
-| Meteor, Phoenix, or socket-based frameworks | Socket |
+| Use Case                                    | Recommended Transport            |
+| ------------------------------------------- | -------------------------------- |
+| Standard web apps (Next.js, etc.)           | HTTP (`createHttpTransport`)     |
+| Real-time apps with custom events           | Socket (`createSocketTransport`) |
+| Apps behind proxies that don't support SSE  | Socket                           |
+| Need for typing indicators, presence, etc.  | Socket                           |
+| Meteor, Phoenix, or socket-based frameworks | Socket                           |
+
+## Connection Lifecycle
+
+By default, socket transport uses **lazy connection** — the socket connects only when you first call `send()`. This is efficient but can be surprising if you want to show connection status.
+
+For UI indicators, use **eager connection**:
+
+```typescript
+import { useEffect, useMemo } from 'react';
+import SockJS from 'sockjs-client';
+import { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';
+
+function Chat() {
+  const transport = useMemo(
+    () => createSocketTransport({
+      connect: () => new Promise((resolve, reject) => {
+        const sock = new SockJS('/octavus');
+        sock.onopen = () => resolve(sock);
+        sock.onerror = () => reject(new Error('Connection failed'));
+      }),
+    }),
+    [],
+  );
+
+  const {
+    messages,
+    status,
+    send,
+    // Socket-specific connection state
+    connectionState,   // 'disconnected' | 'connecting' | 'connected' | 'error'
+    connectionError,   // Error object if connectionState is 'error'
+    connect,           // () => Promise<void>
+    disconnect,        // () => void
+  } = useOctavusChat({ transport });
+
+  // Eagerly connect on mount
+  useEffect(() => {
+    connect?.();
+    return () => disconnect?.();
+  }, [connect, disconnect]);
+
+  return (
+    <div>
+      <ConnectionIndicator state={connectionState} />
+      {/* Chat UI */}
+    </div>
+  );
+}
+```
+
+### Connection States
+
+| State          | Description                                           |
+| -------------- | ----------------------------------------------------- |
+| `disconnected` | Not connected (initial state or after `disconnect()`) |
+| `connecting`   | Connection attempt in progress                        |
+| `connected`    | Socket is open and ready                              |
+| `error`        | Connection failed (check `connectionError`)           |
 
 ## Patterns Overview
 
 There are two main patterns for socket-based integrations:
 
-| Pattern | When to Use |
-|---------|-------------|
+| Pattern                                                         | When to Use                                                                     |
+| --------------------------------------------------------------- | ------------------------------------------------------------------------------- |
 | [Server-Managed Sessions](#server-managed-sessions-recommended) | **Recommended.** Server creates sessions lazily. Client doesn't need sessionId. |
-| [Client-Provided Session ID](#client-provided-session-id) | When client must control session creation or pass sessionId from URL. |
+| [Client-Provided Session ID](#client-provided-session-id)       | When client must control session creation or pass sessionId from URL.           |
 
 ## Server-Managed Sessions (Recommended)
 
@@ -33,7 +91,7 @@ The cleanest pattern is to have the server manage session lifecycle. The client
 ### Client Setup
 
 ```typescript
-import { useMemo } from 'react';
+import { useEffect, useMemo } from 'react';
 import SockJS from 'sockjs-client';
 import { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';
 
@@ -47,22 +105,23 @@ function connectSocket(): Promise<SocketLike> {
 
 function Chat() {
   // Transport is stable — no dependencies on sessionId
-  const transport = useMemo(
-    () => createSocketTransport({ connect: connectSocket }),
-    [],
-  );
+  const transport = useMemo(() => createSocketTransport({ connect: connectSocket }), []);
 
-  const { messages, status, send } = useOctavusChat({ transport });
+  const { messages, status, send, stop, connectionState, connect, disconnect } = useOctavusChat({
+    transport,
+  });
+
+  // Eagerly connect for UI status indicator
+  useEffect(() => {
+    connect?.();
+    return () => disconnect?.();
+  }, [connect, disconnect]);
 
   const sendMessage = async (text: string) => {
-    await send(
-      'user-message',
-      { USER_MESSAGE: text },
-      { userMessage: { content: text } },
-    );
+    await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });
   };
 
-  // ... render messages
+  // ... render chat UI
 }
 ```
 
@@ -113,11 +172,12 @@ function createSocketHandler() {
         abortController = new AbortController();
 
         // Iterate events directly — no SSE parsing needed
-        const events = session.trigger(msg.triggerName, msg.input);
+        const events = session.trigger(msg.triggerName, msg.input, {
+          signal: abortController.signal,
+        });
 
         try {
           for await (const event of events) {
-            if (abortController.signal.aborted) break;
             conn.write(JSON.stringify(event));
           }
         } catch {
@@ -136,6 +196,7 @@ sockServer.installHandlers(httpServer);
 ```
 
 **Benefits of this pattern:**
+
 - Client code is simple — no sessionId management
 - No transport caching issues
 - Session is created only when needed
@@ -194,7 +255,9 @@ sockServer.on('connection', (conn) => {
     // Handle session initialization
     if (msg.type === 'init') {
       session = client.agentSessions.attach(msg.sessionId, {
-        tools: { /* ... */ },
+        tools: {
+          /* ... */
+        },
       });
       return;
     }
@@ -206,10 +269,15 @@ sockServer.on('connection', (conn) => {
 
     // All other messages require initialized session
     if (!session) {
-      conn.write(JSON.stringify({
-        type: 'error',
-        errorText: 'Session not initialized. Send init message first.',
-      }));
+      conn.write(
+        JSON.stringify({
+          type: 'error',
+          errorType: 'validation_error',
+          message: 'Session not initialized. Send init message first.',
+          source: 'platform',
+          retryable: false,
+        }),
+      );
       return;
     }
 
@@ -233,7 +301,7 @@ function ChatPage() {
   const [sessionId, setSessionId] = useState<string | null>(null);
 
   useEffect(() => {
-    api.createSession().then(res => setSessionId(res.sessionId));
+    api.createSession().then((res) => setSessionId(res.sessionId));
   }, []);
 
   // Don't render until sessionId is ready
@@ -261,9 +329,7 @@ const transport = useMemo(
     createSocketTransport({
       connect: () =>
         new Promise((resolve, reject) => {
-          const ws = new WebSocket(
-            `wss://your-server.com/octavus?sessionId=${sessionId}`
-          );
+          const ws = new WebSocket(`wss://your-server.com/octavus?sessionId=${sessionId}`);
           ws.onopen = () => resolve(ws);
           ws.onerror = () => reject(new Error('WebSocket connection failed'));
         }),
@@ -306,6 +372,59 @@ const transport = createSocketTransport({
 
 ## Connection Management
 
+### Connection State API
+
+The socket transport provides full connection lifecycle control:
+
+```typescript
+const transport = createSocketTransport({
+  connect: () =>
+    new Promise((resolve, reject) => {
+      const sock = new SockJS('/octavus');
+      sock.onopen = () => resolve(sock);
+      sock.onerror = () => reject(new Error('Connection failed'));
+    }),
+});
+
+// Access connection state
+console.log(transport.connectionState); // 'disconnected' | 'connecting' | 'connected' | 'error'
+
+// Subscribe to state changes
+const unsubscribe = transport.onConnectionStateChange((state, error) => {
+  console.log('Connection state:', state);
+  if (error) console.error('Error:', error);
+});
+
+// Eager connection
+await transport.connect();
+
+// Manual disconnect
+transport.disconnect();
+```
+
+### Using with useOctavusChat
+
+The React hook exposes connection state automatically for socket transports:
+
+```typescript
+const {
+  messages,
+  status,
+  send,
+  // Socket-specific (undefined for HTTP transport)
+  connectionState,
+  connectionError,
+  connect,
+  disconnect,
+} = useOctavusChat({ transport });
+
+// Eagerly connect on mount
+useEffect(() => {
+  connect?.();
+  return () => disconnect?.();
+}, [connect, disconnect]);
+```
+
 ### Handling Disconnections
 
 ```typescript
@@ -314,7 +433,7 @@ const transport = createSocketTransport({
 
   onClose: () => {
     console.log('Socket disconnected');
-    setConnectionStatus('disconnected');
+    // Connection state is automatically updated to 'disconnected'
   },
 });
 ```
@@ -351,10 +470,7 @@ function useReconnectingTransport() {
     });
   }, []);
 
-  return useMemo(
-    () => createSocketTransport({ connect }),
-    [connect],
-  );
+  return useMemo(() => createSocketTransport({ connect }), [connect]);
 }
 ```
 
@@ -374,12 +490,12 @@ const SockJS: typeof import('sockjs-client') = require('sockjs-client');
 
 ### SockJS vs WebSocket
 
-| Feature | WebSocket | SockJS |
-|---------|-----------|--------|
-| Browser support | Modern browsers | All browsers (with fallbacks) |
-| Session ID | Via URL query params | Via init message |
-| Proxy compatibility | Varies | Excellent (polling fallback) |
-| Setup complexity | Lower | Higher (requires server library) |
+| Feature             | WebSocket            | SockJS                           |
+| ------------------- | -------------------- | -------------------------------- |
+| Browser support     | Modern browsers      | All browsers (with fallbacks)    |
+| Session ID          | Via URL query params | Via init message                 |
+| Proxy compatibility | Varies               | Excellent (polling fallback)     |
+| Setup complexity    | Lower                | Higher (requires server library) |
 
 ## Protocol Reference
 
@@ -406,7 +522,7 @@ The server sends Octavus `StreamEvent` objects as JSON. See [Streaming Events](/
 { type: 'text-delta', id: '...', delta: 'Hello' }
 { type: 'tool-input-start', toolCallId: '...', toolName: 'get-user' }
 { type: 'finish', finishReason: 'stop' }
-{ type: 'error', errorText: 'Something went wrong' }
+{ type: 'error', errorType: 'internal_error', message: 'Something went wrong', source: 'platform', retryable: false }
 ```
 
 ## Full Example

package/content/03-client-sdk/06-http-transport.md

@@ -9,12 +9,12 @@ The HTTP transport uses standard HTTP requests with Server-Sent Events (SSE) for
 
 ## When to Use HTTP Transport
 
-| Use Case | Recommendation |
-|----------|----------------|
-| Next.js, Remix, or similar frameworks | ✅ Use HTTP |
-| Standard web apps without special requirements | ✅ Use HTTP |
-| Serverless deployments (Vercel, etc.) | ✅ Use HTTP |
-| Need custom real-time events | Consider [Socket Transport](/docs/client-sdk/socket-transport) |
+| Use Case                                       | Recommendation                                                 |
+| ---------------------------------------------- | -------------------------------------------------------------- |
+| Next.js, Remix, or similar frameworks          | ✅ Use HTTP                                                    |
+| Standard web apps without special requirements | ✅ Use HTTP                                                    |
+| Serverless deployments (Vercel, etc.)          | ✅ Use HTTP                                                    |
+| Need custom real-time events                   | Consider [Socket Transport](/docs/client-sdk/socket-transport) |
 
 ## Basic Setup
 
@@ -28,11 +28,12 @@ function Chat({ sessionId }: { sessionId: string }) {
   const transport = useMemo(
     () =>
       createHttpTransport({
-        triggerRequest: (triggerName, input) =>
+        triggerRequest: (triggerName, input, options) =>
           fetch('/api/trigger', {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
             body: JSON.stringify({ sessionId, triggerName, input }),
+            signal: options?.signal,
           }),
       }),
     [sessionId],
@@ -41,11 +42,7 @@ function Chat({ sessionId }: { sessionId: string }) {
   const { messages, status, error, send, stop } = useOctavusChat({ transport });
 
   const sendMessage = async (text: string) => {
-    await send(
-      'user-message',
-      { USER_MESSAGE: text },
-      { userMessage: { content: text } },
-    );
+    await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });
   };
 
   // ... render chat
@@ -74,8 +71,8 @@ export async function POST(request: Request) {
     },
   });
 
-  // trigger() returns parsed events, toSSEStream() converts to SSE format
-  const events = session.trigger(triggerName, input);
+  // trigger() returns an async generator, toSSEStream() converts to SSE format
+  const events = session.trigger(triggerName, input, { signal: request.signal });
 
   return new Response(toSSEStream(events), {
     headers: {
@@ -112,8 +109,8 @@ export default function ChatPage() {
         input: { COMPANY_NAME: 'Acme Corp' },
       }),
     })
-      .then(res => res.json())
-      .then(data => setSessionId(data.sessionId));
+      .then((res) => res.json())
+      .then((data) => setSessionId(data.sessionId));
   }, []);
 
   if (!sessionId) {
@@ -145,14 +142,23 @@ This pattern is cleaner as the session is ready before the component renders.
 
 ## Error Handling
 
-Handle errors in both the transport and the hook:
+Handle errors with structured error information:
 
 ```tsx
+import { isRateLimitError, isProviderError } from '@octavus/react';
+
 const { messages, status, error, send } = useOctavusChat({
   transport,
   onError: (err) => {
-    console.error('Stream error:', err);
-    // Show toast, update UI, etc.
+    console.error('Stream error:', err.errorType, err.message);
+
+    if (isRateLimitError(err)) {
+      toast.error(`Rate limited. Try again in ${err.retryAfter}s`);
+    } else if (isProviderError(err)) {
+      toast.error('AI service temporarily unavailable');
+    } else {
+      toast.error('Something went wrong');
+    }
   },
 });
 
@@ -162,12 +168,24 @@ if (error) {
 }
 ```
 
+See [Error Handling](/docs/client-sdk/error-handling) for comprehensive error handling patterns.
+
 ## Stop Streaming
 
-Allow users to cancel ongoing streams:
+Allow users to cancel ongoing streams. When `stop()` is called:
+
+1. The HTTP request is aborted via the signal
+2. Any partial content is preserved in the message
+3. Tool calls in progress are marked as `cancelled`
+4. Status changes to `idle`
 
 ```tsx
-const { send, stop, status } = useOctavusChat({ transport });
+const { send, stop, status } = useOctavusChat({
+  transport,
+  onStop: () => {
+    console.log('User stopped generation');
+  },
+});
 
 return (
   <button
@@ -179,6 +197,8 @@ return (
 );
 ```
 
+> **Important**: For stop to work end-to-end, pass the `options.signal` to your `fetch()` call and forward `request.signal` to `session.trigger()` on the server.
+
 ## Express Server
 
 For non-Next.js backends:
@@ -230,12 +250,16 @@ app.post('/api/trigger', async (req, res) => {
 
 ```typescript
 interface HttpTransportOptions {
-  // Function that makes the HTTP request
   triggerRequest: (
     triggerName: string,
-    input?: Record<string, unknown>
+    input?: Record<string, unknown>,
+    options?: TriggerRequestOptions,
   ) => Promise<Response>;
 }
+
+interface TriggerRequestOptions {
+  signal?: AbortSignal;
+}
 ```
 
 ## Protocol
@@ -277,4 +301,4 @@ See [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list
 - [Quick Start](/docs/getting-started/quickstart) — Complete Next.js integration guide
 - [Messages](/docs/client-sdk/messages) — Working with message state
 - [Streaming](/docs/client-sdk/streaming) — Building streaming UIs
-
+- [Error Handling](/docs/client-sdk/error-handling) — Handling errors with type guards