@octavus/docs 0.0.8 → 1.0.0

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

@@ -7,10 +7,10 @@ description: Introduction to the Octavus Client SDKs for building chat interface
 
 Octavus provides two packages for frontend integration:
 
-| Package | Purpose | Use When |
-|---------|---------|----------|
-| `@octavus/react` | React hooks and bindings | Building React applications |
-| `@octavus/client-sdk` | Framework-agnostic core | Using Vue, Svelte, vanilla JS, or custom integrations |
+| Package               | Purpose                  | Use When                                              |
+| --------------------- | ------------------------ | ----------------------------------------------------- |
+| `@octavus/react`      | React hooks and bindings | Building React applications                           |
+| `@octavus/client-sdk` | Framework-agnostic core  | Using Vue, Svelte, vanilla JS, or custom integrations |
 
 **Most users should install `@octavus/react`** — it includes everything from `@octavus/client-sdk` plus React-specific hooks.
 
@@ -36,9 +36,9 @@ 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 | Docs |
-|-----------|----------|------|
-| `createHttpTransport` | HTTP/SSE (Next.js, Express, etc.) | [HTTP Transport](/docs/client-sdk/http-transport) |
+| 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.
@@ -71,11 +71,7 @@ function Chat({ sessionId }: { sessionId: string }) {
   const { messages, status, send } = 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 } });
   };
 
   return (
@@ -127,11 +123,7 @@ const unsubscribe = chat.subscribe(() => {
 });
 
 // Send a message
-await chat.send(
-  'user-message',
-  { USER_MESSAGE: 'Hello' },
-  { userMessage: { content: 'Hello' } },
-);
+await chat.send('user-message', { USER_MESSAGE: 'Hello' }, { userMessage: { content: 'Hello' } });
 
 // Cleanup when done
 unsubscribe();
@@ -147,11 +139,7 @@ The `send` function handles both user message display and agent triggering in on
 const { send } = useOctavusChat({ transport });
 
 // Add user message to UI and trigger agent
-await send(
-  'user-message',
-  { USER_MESSAGE: text },
-  { userMessage: { content: text } },
-);
+await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });
 
 // Trigger without adding a user message (e.g., button click)
 await send('request-human');
@@ -167,10 +155,10 @@ const { messages } = useOctavusChat({ transport });
 // Each message has typed parts
 message.parts.map((part) => {
   switch (part.type) {
-    case 'text':       // Text content
-    case 'reasoning':  // Extended reasoning/thinking
-    case 'tool-call':  // Tool execution
-    case 'operation':  // Internal operations (set-resource, etc.)
+    case 'text': // Text content
+    case 'reasoning': // Extended reasoning/thinking
+    case 'tool-call': // Tool execution
+    case 'operation': // Internal operations (set-resource, etc.)
   }
 });
 ```
@@ -203,32 +191,53 @@ interface OctavusChatOptions {
   // Required: Transport for streaming events
   transport: Transport;
 
+  // Optional: Function to request upload URLs for file uploads
+  requestUploadUrls?: (
+    files: { filename: string; mediaType: string; size: number }[],
+  ) => Promise<UploadUrlsResponse>;
+
   // Optional: Pre-populate with existing messages (session restore)
   initialMessages?: UIMessage[];
 
   // Optional: Callbacks
-  onError?: (error: Error) => void;
+  onError?: (error: OctavusError) => void; // Structured error with type, source, retryable
   onFinish?: () => void;
+  onStop?: () => void; // Called when user stops generation
   onResourceUpdate?: (name: string, value: unknown) => void;
 }
 
 interface UseOctavusChatReturn {
   // State
   messages: UIMessage[];
-  status: ChatStatus;  // 'idle' | 'streaming' | 'error'
-  error: Error | null;
+  status: ChatStatus; // 'idle' | 'streaming' | 'error'
+  error: OctavusError | null; // Structured error with type, source, retryable
+
+  // Connection (socket transport only - undefined for HTTP)
+  connectionState: ConnectionState | undefined; // 'disconnected' | 'connecting' | 'connected' | 'error'
+  connectionError: Error | undefined;
 
   // Actions
   send: (
     triggerName: string,
     input?: Record<string, unknown>,
-    options?: { userMessage?: UserMessageInput }
+    options?: { userMessage?: UserMessageInput },
   ) => Promise<void>;
   stop: () => void;
+
+  // Connection management (socket transport only - undefined for HTTP)
+  connect: (() => Promise<void>) | undefined;
+  disconnect: (() => void) | undefined;
+
+  // File uploads (requires requestUploadUrls)
+  uploadFiles: (
+    files: FileList | File[],
+    onProgress?: (fileIndex: number, progress: number) => void,
+  ) => Promise<FileReference[]>;
 }
 
 interface UserMessageInput {
-  content: string;
+  content?: string;
+  files?: FileList | File[] | FileReference[];
 }
 ```
 
@@ -242,11 +251,12 @@ Creates an HTTP/SSE transport using native `fetch()`:
 import { createHttpTransport } from '@octavus/react';
 
 const transport = 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,
     }),
 });
 ```
@@ -268,6 +278,24 @@ const transport = createSocketTransport({
 });
 ```
 
+Socket transport provides additional connection management:
+
+```typescript
+// Access connection state directly
+transport.connectionState; // 'disconnected' | 'connecting' | 'connected' | 'error'
+
+// Subscribe to state changes
+transport.onConnectionStateChange((state, error) => {
+  /* ... */
+});
+
+// Eager connection (instead of lazy on first send)
+await transport.connect();
+
+// Manual disconnect
+transport.disconnect();
+```
+
 For detailed WebSocket/SockJS usage including custom events, reconnection patterns, and server-side implementation, see [Socket Transport](/docs/client-sdk/socket-transport).
 
 ## Class Reference (Framework-Agnostic)
@@ -281,18 +309,18 @@ class OctavusChat {
   // State (read-only)
   readonly messages: UIMessage[];
   readonly status: ChatStatus;
-  readonly error: Error | null;
+  readonly error: OctavusError | null; // Structured error
 
   // Actions
   send(
     triggerName: string,
     input?: Record<string, unknown>,
-    options?: { userMessage?: UserMessageInput }
+    options?: { userMessage?: UserMessageInput },
   ): Promise<void>;
   stop(): void;
 
   // Subscription
-  subscribe(callback: () => void): () => void;  // Returns unsubscribe function
+  subscribe(callback: () => void): () => void; // Returns unsubscribe function
 }
 ```
 
@@ -303,4 +331,6 @@ class OctavusChat {
 - [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
+- [Error Handling](/docs/client-sdk/error-handling) — Handling errors with type guards
+- [File Uploads](/docs/client-sdk/file-uploads) — Uploading images and documents
 - [Examples](/docs/examples/overview) — Complete working examples

package/content/03-client-sdk/02-messages.md

@@ -28,14 +28,17 @@ type UIMessagePart =
   | UITextPart
   | UIReasoningPart
   | UIToolCallPart
-  | UIOperationPart;
+  | UIOperationPart
+  | UISourcePart
+  | UIFilePart
+  | UIObjectPart;
 
 // Text content
 interface UITextPart {
   type: 'text';
   text: string;
   status: 'streaming' | 'done';
-  thread?: string;  // For named threads (e.g., "summary")
+  thread?: string; // For named threads (e.g., "summary")
 }
 
 // Extended reasoning/thinking
@@ -51,7 +54,7 @@ interface UIToolCallPart {
   type: 'tool-call';
   toolCallId: string;
   toolName: string;
-  displayName?: string;  // Human-readable name
+  displayName?: string; // Human-readable name
   args: Record<string, unknown>;
   result?: unknown;
   error?: string;
@@ -68,6 +71,42 @@ interface UIOperationPart {
   status: 'running' | 'done';
   thread?: string;
 }
+
+// Source references (from web search, document processing)
+interface UISourcePart {
+  type: 'source';
+  sourceType: 'url' | 'document';
+  id: string;
+  url?: string; // For URL sources
+  title?: string;
+  mediaType?: string; // For document sources
+  filename?: string;
+  thread?: string;
+}
+
+// Generated files (from image generation, skills, code execution)
+interface UIFilePart {
+  type: 'file';
+  id: string;
+  mediaType: string; // MIME type (e.g., 'image/png', 'image/webp')
+  url: string; // Download/display URL (presigned S3 URL)
+  filename?: string;
+  size?: number;
+  toolCallId?: string; // Present if from a tool call
+  thread?: string;
+}
+
+// Structured output (when responseType is used)
+interface UIObjectPart {
+  type: 'object';
+  id: string;
+  typeName: string; // Type name from protocol (e.g., "ChatResponse")
+  partial?: unknown; // Partial object while streaming
+  object?: unknown; // Final object when done
+  status: 'streaming' | 'done' | 'error';
+  error?: string;
+  thread?: string;
+}
 ```
 
 ## Sending Messages
@@ -94,11 +133,7 @@ function Chat({ sessionId }: { sessionId: string }) {
 
   async function handleSend(text: string) {
     // Add user message to UI and trigger agent
-    await send(
-      'user-message',
-      { USER_MESSAGE: text },
-      { userMessage: { content: text } },
-    );
+    await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });
   }
 
   // ...
@@ -106,10 +141,56 @@ function Chat({ sessionId }: { sessionId: string }) {
 ```
 
 The `send` function:
+
 1. Adds the user message to the UI immediately (if `userMessage` is provided)
 2. Triggers the agent with the specified trigger name and input
 3. Streams the assistant's response back
 
+### Message Content Types
+
+The `content` field in `userMessage` accepts both strings and objects:
+
+```tsx
+// Text content → creates a text part
+await send('user-message', { USER_MESSAGE: text }, { userMessage: { content: text } });
+
+// Object content → creates an object part (uses `type` field as typeName)
+const selection = { type: 'product_selection', productId: 'abc123', action: 'select' };
+await send('user-message', { USER_INPUT: selection }, { userMessage: { content: selection } });
+```
+
+When passing an object as `content`:
+
+- The SDK creates a `UIObjectPart` instead of a `UITextPart`
+- The object's `type` field is used as the `typeName` (defaults to `'object'` if not present)
+- This is useful for rich UI interactions like product selections, quick replies, etc.
+
+### Sending with Files
+
+Include file attachments with messages:
+
+```tsx
+import type { FileReference } from '@octavus/react';
+
+async function handleSend(text: string, files?: FileReference[]) {
+  await send(
+    'user-message',
+    {
+      USER_MESSAGE: text,
+      FILES: files, // Array of FileReference
+    },
+    {
+      userMessage: {
+        content: text,
+        files: files, // Shows files in user message bubble
+      },
+    },
+  );
+}
+```
+
+See [File Uploads](/docs/client-sdk/file-uploads) for complete upload flow.
+
 ## Rendering Messages
 
 ### Basic Rendering
@@ -180,6 +261,33 @@ function PartRenderer({ part }: { part: UIMessagePart }) {
         </div>
       );
 
+    case 'source':
+      return (
+        <div className="text-blue-500 text-sm">📎 {part.title || part.url || part.filename}</div>
+      );
+
+    case 'file':
+      // Render images inline, other files as download links
+      if (part.mediaType.startsWith('image/')) {
+        return (
+          <img
+            src={part.url}
+            alt={part.filename || 'Generated image'}
+            className="max-w-full rounded-lg"
+          />
+        );
+      }
+      return (
+        <a href={part.url} className="text-blue-500 text-sm underline">
+          📄 {part.filename || 'Download file'}
+        </a>
+      );
+
+    case 'object':
+      // For structured output, render custom UI based on typeName
+      // See Structured Output guide for more details
+      return <ObjectPartRenderer part={part} />;
+
     default:
       return null;
   }

package/content/03-client-sdk/03-streaming.md

@@ -85,9 +85,7 @@ function ReasoningPart({ part }: { part: UIReasoningPart }) {
         {expanded ? '▼' : '▶'}
       </button>
 
-      {expanded && (
-        <pre className="mt-2 text-sm text-gray-600">{part.text}</pre>
-      )}
+      {expanded && <pre className="mt-2 text-sm text-gray-600">{part.text}</pre>}
     </div>
   );
 }
@@ -117,9 +115,10 @@ function ToolCallPart({ part }: { part: UIToolCallPart }) {
       )}
 
       {/* Show error if failed */}
-      {part.status === 'error' && (
-        <p className="mt-2 text-red-500 text-sm">{part.error}</p>
-      )}
+      {part.status === 'error' && <p className="mt-2 text-red-500 text-sm">{part.error}</p>}
+
+      {/* Show cancelled state */}
+      {part.status === 'cancelled' && <p className="mt-2 text-amber-500 text-sm">Cancelled</p>}
     </div>
   );
 }
@@ -134,6 +133,8 @@ function StatusBadge({ status }: { status: UIToolCallPart['status'] }) {
       return <span className="text-green-500">✓</span>;
     case 'error':
       return <span className="text-red-500">✗</span>;
+    case 'cancelled':
+      return <span className="text-amber-500">◼</span>;
   }
 }
 ```
@@ -156,19 +157,34 @@ function StatusIndicator({ status }: { status: ChatStatus }) {
 ## Handling Completion
 
 ```tsx
+import { isRateLimitError, type OctavusError } from '@octavus/react';
+
 useOctavusChat({
   transport,
   onFinish: () => {
-    console.log('Stream completed');
+    console.log('Stream completed successfully');
     // Scroll to bottom, play sound, etc.
   },
-  onError: (error) => {
-    console.error('Stream error:', error);
-    toast.error('Failed to get response');
+  onStop: () => {
+    console.log('User stopped generation');
+    // Handle stop - content is preserved
+  },
+  onError: (error: OctavusError) => {
+    console.error('Stream error:', error.errorType, error.message);
+
+    if (isRateLimitError(error)) {
+      toast.error(`Rate limited. Retry in ${error.retryAfter}s`);
+    } else {
+      toast.error('Failed to get response');
+    }
   },
 });
 ```
 
+See [Error Handling](/docs/client-sdk/error-handling) for comprehensive error handling patterns.
+
+````
+
 ## Stop Function
 
 Stop the current stream and finalize any partial message:
@@ -182,12 +198,17 @@ const { status, stop } = useOctavusChat({ transport });
     Stop generating
   </button>
 )}
-```
+````
 
 When `stop()` is called:
-1. The current request is aborted
-2. Any partial message is finalized with current content
-3. Status changes to `'idle'`
+
+1. The HTTP request is aborted (requires `signal` in transport)
+2. Any partial text/reasoning is finalized with `done` status
+3. In-progress tool calls are marked as `cancelled`
+4. The `onStop` callback is invoked
+5. Status changes to `idle`
+
+Partial content is preserved in the message, so users don't lose what was already generated.
 
 ## Named Thread Content
 
@@ -211,9 +232,7 @@ function MessageBubble({ message }: { message: UIMessage }) {
       {/* Named thread content (e.g., summarization) */}
       {otherParts.length > 0 && (
         <div className="bg-amber-50 p-3 rounded mt-4 border border-amber-200">
-          <div className="text-amber-600 font-medium mb-2">
-            Background processing
-          </div>
+          <div className="text-amber-600 font-medium mb-2">Background processing</div>
           {otherParts.map((part, i) => (
             <PartRenderer key={i} part={part} />
           ))}

package/content/03-client-sdk/04-execution-blocks.md

@@ -13,10 +13,10 @@ Operations represent internal agent activities like setting resources or seriali
 interface UIOperationPart {
   type: 'operation';
   operationId: string;
-  name: string;           // Human-readable name
-  operationType: string;  // e.g., 'set-resource', 'serialize-thread'
+  name: string; // Human-readable name
+  operationType: string; // e.g., 'set-resource', 'serialize-thread'
   status: 'running' | 'done';
-  thread?: string;        // For named threads
+  thread?: string; // For named threads
 }
 ```
 
@@ -76,9 +76,9 @@ function PartRenderer({ part }: { part: UIMessagePart }) {
 
 ## Common Operation Types
 
-| Type | Description |
-|------|-------------|
-| `set-resource` | Updating a resource value |
+| Type               | Description                        |
+| ------------------ | ---------------------------------- |
+| `set-resource`     | Updating a resource value          |
 | `serialize-thread` | Converting thread messages to text |
 
 ## Example: Progress During Escalation
@@ -87,9 +87,7 @@ When a user clicks "Talk to Human", multiple operations may occur:
 
 ```tsx
 function EscalationProgress({ message }: { message: UIMessage }) {
-  const operations = message.parts.filter(
-    (p): p is UIOperationPart => p.type === 'operation'
-  );
+  const operations = message.parts.filter((p): p is UIOperationPart => p.type === 'operation');
 
   return (
     <div className="space-y-2">
@@ -123,9 +121,7 @@ Operations can belong to named threads. Use the `thread` property to identify th
 function OperationCard({ operation }: { operation: UIOperationPart }) {
   return (
     <div className="flex items-center gap-2 text-sm">
-      {operation.thread && (
-        <span className="text-amber-500">[{operation.thread}]</span>
-      )}
+      {operation.thread && <span className="text-amber-500">[{operation.thread}]</span>}
       <span>{operation.name}</span>
       {operation.status === 'done' && <span className="text-green-500">✓</span>}
     </div>