@octavus/docs 0.0.8 → 1.0.0

package/content/06-examples/03-socket-chat.md

@@ -10,6 +10,7 @@ This example builds a chat interface using SockJS for bidirectional communicatio
 ## What You're Building
 
 A chat interface that:
+
 - Uses SockJS for real-time streaming
 - Manages sessions server-side (client doesn't need sessionId)
 - Supports custom events alongside chat
@@ -35,12 +36,14 @@ flowchart LR
 ## Step 1: Install Dependencies
 
 **Server:**
+
 ```bash
 npm install @octavus/server-sdk sockjs express
 npm install -D @types/sockjs @types/express
 ```
 
 **Client:**
+
 ```bash
 npm install @octavus/react sockjs-client
 npm install -D @types/sockjs-client
@@ -182,7 +185,7 @@ server.listen(3001, () => {
 
 ```typescript
 // src/hooks/useOctavusSocket.ts
-import { useMemo } from 'react';
+import { useEffect, useMemo } from 'react';
 import SockJS from 'sockjs-client';
 import { useOctavusChat, createSocketTransport, type SocketLike } from '@octavus/react';
 
@@ -197,25 +200,35 @@ function connectSocket(): Promise<SocketLike> {
 
 export function useOctavusSocket() {
   // Transport is stable - empty deps because server manages sessions
-  const transport = useMemo(
-    () => createSocketTransport({ connect: connectSocket }),
-    [],
-  );
-
-  const { messages, status, error, send, stop } = useOctavusChat({
+  const transport = useMemo(() => createSocketTransport({ connect: connectSocket }), []);
+
+  const {
+    messages,
+    status,
+    error,
+    send,
+    stop,
+    // Socket-specific connection state
+    connectionState,
+    connectionError,
+    connect,
+    disconnect,
+  } = useOctavusChat({
     transport,
     onError: (err) => console.error('Chat error:', err),
   });
 
+  // Eagerly connect for UI status indicator
+  useEffect(() => {
+    connect?.();
+    return () => disconnect?.();
+  }, [connect, disconnect]);
+
   const sendMessage = async (message: string) => {
-    await send(
-      'user-message',
-      { USER_MESSAGE: message },
-      { userMessage: { content: message } },
-    );
+    await send('user-message', { USER_MESSAGE: message }, { userMessage: { content: message } });
   };
 
-  return { messages, status, error, sendMessage, stop };
+  return { messages, status, error, connectionState, connectionError, sendMessage, stop };
 }
 ```
 
@@ -226,9 +239,20 @@ export function useOctavusSocket() {
 import { useState } from 'react';
 import { useOctavusSocket } from '../hooks/useOctavusSocket';
 
+function ConnectionIndicator({ state }: { state: string | undefined }) {
+  const colors: Record<string, string> = {
+    connected: 'bg-green-500',
+    connecting: 'bg-yellow-500',
+    error: 'bg-red-500',
+    disconnected: 'bg-gray-400',
+  };
+  const color = colors[state ?? 'disconnected'];
+  return <div className={`w-2 h-2 rounded-full ${color}`} title={state} />;
+}
+
 export function Chat() {
   const [inputValue, setInputValue] = useState('');
-  const { messages, status, sendMessage, stop } = useOctavusSocket();
+  const { messages, status, connectionState, sendMessage, stop } = useOctavusSocket();
 
   const handleSubmit = async (e: React.FormEvent) => {
     e.preventDefault();
@@ -241,18 +265,19 @@ export function Chat() {
 
   return (
     <div className="flex flex-col h-screen">
+      {/* Header with connection status */}
+      <div className="p-4 border-b flex items-center justify-between">
+        <h1 className="font-semibold">AI Chat</h1>
+        <ConnectionIndicator state={connectionState} />
+      </div>
+
       {/* Messages */}
       <div className="flex-1 overflow-y-auto p-4 space-y-4">
         {messages.map((msg) => (
-          <div
-            key={msg.id}
-            className={msg.role === 'user' ? 'text-right' : 'text-left'}
-          >
+          <div key={msg.id} className={msg.role === 'user' ? 'text-right' : 'text-left'}>
             <div
               className={`inline-block p-3 rounded-lg ${
-                msg.role === 'user'
-                  ? 'bg-blue-500 text-white'
-                  : 'bg-gray-100'
+                msg.role === 'user' ? 'bg-blue-500 text-white' : 'bg-gray-100'
               }`}
             >
               {msg.parts.map((part, i) => {
@@ -283,10 +308,7 @@ export function Chat() {
             Stop
           </button>
         ) : (
-          <button
-            type="submit"
-            className="px-4 py-2 bg-blue-500 text-white rounded-lg"
-          >
+          <button type="submit" className="px-4 py-2 bg-blue-500 text-white rounded-lg">
             Send
           </button>
         )}
@@ -326,10 +348,12 @@ const transport = useMemo(
 
 ```typescript
 // Server - send custom events
-conn.write(JSON.stringify({
-  type: 'typing-indicator',
-  isTyping: true,
-}));
+conn.write(
+  JSON.stringify({
+    type: 'typing-indicator',
+    isTyping: true,
+  }),
+);
 ```
 
 ## Protocol Integration
@@ -389,4 +413,3 @@ const SockJS: typeof import('sockjs-client') = require('sockjs-client');
 - [Socket Transport](/docs/client-sdk/socket-transport) — Advanced socket patterns
 - [Protocol Overview](/docs/protocol/overview) — Define agent behavior
 - [Tools](/docs/protocol/tools) — Building tool handlers
-

package/content/06-examples/_meta.md

@@ -2,4 +2,3 @@
 title: Examples
 description: Complete working examples demonstrating Octavus integration patterns.
 ---
-