@octavus/docs 0.0.6 → 0.0.8

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

@@ -0,0 +1,280 @@
+---
+title: HTTP Transport
+description: Using HTTP/SSE for streaming with Octavus in Next.js, Express, and other frameworks.
+---
+
+# HTTP Transport
+
+The HTTP transport uses standard HTTP requests with Server-Sent Events (SSE) for streaming. This is the simplest and most compatible transport option.
+
+## 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) |
+
+## Basic Setup
+
+### Client
+
+```tsx
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+function Chat({ sessionId }: { sessionId: string }) {
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
+
+  const { messages, status, error, send, stop } = useOctavusChat({ transport });
+
+  const sendMessage = async (text: string) => {
+    await send(
+      'user-message',
+      { USER_MESSAGE: text },
+      { userMessage: { content: text } },
+    );
+  };
+
+  // ... render chat
+}
+```
+
+### Server (Next.js API Route)
+
+```typescript
+// app/api/trigger/route.ts
+import { OctavusClient, toSSEStream } from '@octavus/server-sdk';
+
+const client = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+export async function POST(request: Request) {
+  const { sessionId, triggerName, input } = await request.json();
+
+  const session = client.agentSessions.attach(sessionId, {
+    tools: {
+      'get-user-account': async (args) => {
+        return { name: 'Demo User', plan: 'pro' };
+      },
+    },
+  });
+
+  // trigger() returns parsed events, toSSEStream() converts to SSE format
+  const events = session.trigger(triggerName, input);
+
+  return new Response(toSSEStream(events), {
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive',
+    },
+  });
+}
+```
+
+## Session Creation
+
+Sessions should be created server-side before rendering the chat. There are two patterns:
+
+### Pattern 1: Create Session on Page Load
+
+```tsx
+// app/chat/page.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import { Chat } from '@/components/Chat';
+
+export default function ChatPage() {
+  const [sessionId, setSessionId] = useState<string | null>(null);
+
+  useEffect(() => {
+    fetch('/api/sessions', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        agentId: 'your-agent-id',
+        input: { COMPANY_NAME: 'Acme Corp' },
+      }),
+    })
+      .then(res => res.json())
+      .then(data => setSessionId(data.sessionId));
+  }, []);
+
+  if (!sessionId) {
+    return <LoadingSpinner />;
+  }
+
+  return <Chat sessionId={sessionId} />;
+}
+```
+
+### Pattern 2: Server-Side Session Creation (App Router)
+
+```tsx
+// app/chat/page.tsx
+import { octavus } from '@/lib/octavus';
+import { Chat } from '@/components/Chat';
+
+export default async function ChatPage() {
+  // Create session server-side
+  const sessionId = await octavus.agentSessions.create('your-agent-id', {
+    COMPANY_NAME: 'Acme Corp',
+  });
+
+  return <Chat sessionId={sessionId} />;
+}
+```
+
+This pattern is cleaner as the session is ready before the component renders.
+
+## Error Handling
+
+Handle errors in both the transport and the hook:
+
+```tsx
+const { messages, status, error, send } = useOctavusChat({
+  transport,
+  onError: (err) => {
+    console.error('Stream error:', err);
+    // Show toast, update UI, etc.
+  },
+});
+
+// Also check error state
+if (error) {
+  return <ErrorMessage error={error} />;
+}
+```
+
+## Stop Streaming
+
+Allow users to cancel ongoing streams:
+
+```tsx
+const { send, stop, status } = useOctavusChat({ transport });
+
+return (
+  <button
+    onClick={status === 'streaming' ? stop : () => sendMessage()}
+    disabled={status === 'streaming' && !inputValue}
+  >
+    {status === 'streaming' ? 'Stop' : 'Send'}
+  </button>
+);
+```
+
+## Express Server
+
+For non-Next.js backends:
+
+```typescript
+import express from 'express';
+import { OctavusClient, toSSEStream } from '@octavus/server-sdk';
+
+const app = express();
+const client = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+
+app.post('/api/trigger', async (req, res) => {
+  const { sessionId, triggerName, input } = req.body;
+
+  const session = client.agentSessions.attach(sessionId, {
+    tools: {
+      // Your tool handlers
+    },
+  });
+
+  const events = session.trigger(triggerName, input);
+  const stream = toSSEStream(events);
+
+  // Set SSE headers
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+
+  // Pipe the stream to the response
+  const reader = stream.getReader();
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      res.write(value);
+    }
+  } finally {
+    reader.releaseLock();
+    res.end();
+  }
+});
+```
+
+## Transport Options
+
+```typescript
+interface HttpTransportOptions {
+  // Function that makes the HTTP request
+  triggerRequest: (
+    triggerName: string,
+    input?: Record<string, unknown>
+  ) => Promise<Response>;
+}
+```
+
+## Protocol
+
+### Request Format
+
+The `triggerRequest` function should send a POST request with:
+
+```json
+{
+  "sessionId": "sess_abc123",
+  "triggerName": "user-message",
+  "input": {
+    "USER_MESSAGE": "Hello"
+  }
+}
+```
+
+### Response Format
+
+The server responds with an SSE stream:
+
+```
+data: {"type":"start","messageId":"msg_xyz"}
+
+data: {"type":"text-delta","id":"msg_xyz","delta":"Hello"}
+
+data: {"type":"text-delta","id":"msg_xyz","delta":" there!"}
+
+data: {"type":"finish","finishReason":"stop"}
+
+data: [DONE]
+```
+
+See [Streaming Events](/docs/server-sdk/streaming#event-types) for the full list of event types.
+
+## Next Steps
+
+- [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
+

package/content/04-protocol/03-triggers.md

@@ -32,7 +32,7 @@ triggers:
   request-human:
     description: User clicks "Talk to Human" button
     # No input needed - action is implicit
-  
+
   submit-feedback:
     description: User submits feedback form
     input:
@@ -79,29 +79,57 @@ triggers:
 
 ### From Client SDK
 
-```typescript
-const { send } = useOctavusChat({...});
-
-// User message trigger with UI message
-await send('user-message', { USER_MESSAGE: text }, {
-  userMessage: { content: text },
-});
-
-// User action trigger (no input, no UI message)
-await send('request-human');
-
-// Action with input
-await send('submit-feedback', { RATING: 5, COMMENT: 'Great help!' });
+```tsx
+import { useMemo } from 'react';
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+function Chat({ sessionId }: { sessionId: string }) {
+  const transport = useMemo(
+    () =>
+      createHttpTransport({
+        triggerRequest: (triggerName, input) =>
+          fetch('/api/trigger', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId, triggerName, input }),
+          }),
+      }),
+    [sessionId],
+  );
+
+  const { send } = useOctavusChat({ transport });
+
+  // User message trigger with UI message
+  await send(
+    'user-message',
+    { USER_MESSAGE: text },
+    { userMessage: { content: text } },
+  );
+
+  // User action trigger (no input, no UI message)
+  await send('request-human');
+
+  // Action with input
+  await send('submit-feedback', { RATING: 5, COMMENT: 'Great help!' });
+}
 ```
 
 ### From Server SDK
 
 ```typescript
-const { stream } = session.trigger('user-message', { 
-  USER_MESSAGE: 'Help me with billing' 
+// trigger() returns an async generator of events
+const events = session.trigger('user-message', {
+  USER_MESSAGE: 'Help me with billing',
 });
 
-const { stream } = session.trigger('request-human');
+// Iterate events directly
+for await (const event of events) {
+  console.log(event);
+}
+
+// Or convert to SSE for HTTP responses
+import { toSSEStream } from '@octavus/server-sdk';
+return new Response(toSSEStream(events), { headers: { 'Content-Type': 'text/event-stream' } });
 ```
 
 ## Handlers
@@ -125,7 +153,7 @@ handlers:
       role: user
       prompt: user-message
       input: [USER_MESSAGE]
-    
+
     Respond:
       type: next-message
 
@@ -191,10 +219,10 @@ Each trigger should do one thing:
 triggers:
   send-message:
     input: { MESSAGE: { type: string } }
-  
+
   upload-file:
     input: { FILE_URL: { type: string } }
-  
+
   request-callback:
     input: { PHONE: { type: string } }
 
@@ -205,4 +233,3 @@ triggers:
       ACTION_TYPE: { type: string }  # "message" | "file" | "callback"
       PAYLOAD: { type: unknown }     # Different structure per type
 ```
-

package/content/04-protocol/04-tools.md

@@ -59,17 +59,17 @@ tools:
       query:
         type: string
         description: Search query
-      
+
       category:
         type: string
         description: Filter by category
         optional: true
-      
+
       maxPrice:
         type: number
         description: Maximum price filter
         optional: true
-      
+
       inStock:
         type: boolean
         description: Only show in-stock items
@@ -86,7 +86,7 @@ tools:
     description: Look up user account
     parameters:
       userId: { type: string }
-  
+
   create-support-ticket:
     description: Create a support ticket
     parameters:
@@ -136,17 +136,30 @@ handlers:
 
 ### In Prompts
 
-Reference tool results in prompts:
+Tool results are stored in variables. Reference the variable in prompts:
 
 ```markdown
 <!-- prompts/ticket-directive.md -->
 A support ticket has been created:
-- Ticket ID: {{TICKET.ticketId}}
-- Estimated Response: {{TICKET.estimatedResponse}}
+{{TICKET}}
+
+Let the user know their ticket has been created.
+```
+
+When the `TICKET` variable contains an object, it's automatically serialized as JSON in the prompt:
+
+```
+A support ticket has been created:
+{
+  "ticketId": "TKT-123ABC",
+  "estimatedResponse": "24 hours"
+}
 
 Let the user know their ticket has been created.
 ```
 
+> **Note**: Variables use `{{VARIABLE_NAME}}` syntax with `UPPERCASE_SNAKE_CASE`. Dot notation (like `{{TICKET.ticketId}}`) is not supported. Objects are automatically JSON-serialized.
+
 ### In Variables
 
 Store tool results for later use:
@@ -160,15 +173,13 @@ handlers:
       input:
         userId: USER_ID
       output: ACCOUNT  # Result stored here
-    
+
     Create ticket:
       type: tool-call
       tool: create-support-ticket
       input:
         summary: SUMMARY
         priority: medium
-        # Can reference ACCOUNT here
-        email: ACCOUNT.email
       output: TICKET
 ```
 
@@ -182,7 +193,7 @@ const session = client.agentSessions.attach(sessionId, {
     'get-user-account': async (args) => {
       const userId = args.userId as string;
       const user = await db.users.findById(userId);
-      
+
       return {
         name: user.name,
         email: user.email,
@@ -190,13 +201,13 @@ const session = client.agentSessions.attach(sessionId, {
         createdAt: user.createdAt.toISOString(),
       };
     },
-    
+
     'create-support-ticket': async (args) => {
       const ticket = await ticketService.create({
         summary: args.summary as string,
         priority: args.priority as string,
       });
-      
+
       return {
         ticketId: ticket.id,
         estimatedResponse: getEstimatedTime(args.priority),
@@ -218,7 +229,7 @@ tools:
       Retrieves the user's account information including name, email,
       subscription plan, and account creation date. Use this when the
       user asks about their account or you need to verify their identity.
-  
+
   # Avoid - vague
   get-data:
     description: Gets some data
@@ -234,4 +245,3 @@ tools:
         type: string
         description: Ticket priority level (low, medium, high, urgent)
 ```
-

package/content/05-api-reference/01-overview.md

@@ -22,7 +22,7 @@ curl -H "Authorization: Bearer YOUR_API_KEY" \
   https://octavus.ai/api/agents
 ```
 
-API keys can be created in the Octavus Platform under Project Settings → API Keys.
+API keys can be created in the Octavus Platform under your project's **API Keys** page.
 
 ## Response Format
 
@@ -57,23 +57,8 @@ All responses are JSON. Success responses return the data directly (not wrapped
 | 401 | Unauthorized - Missing or invalid API key |
 | 403 | Forbidden - Insufficient permissions |
 | 404 | Not Found |
-| 429 | Too Many Requests - Rate limited |
 | 500 | Internal Server Error |
 
-## Rate Limits
-
-- **Standard tier**: 100 requests/minute
-- **Pro tier**: 1,000 requests/minute
-- **Enterprise**: Custom limits
-
-Rate limit headers are included in responses:
-
-```
-X-RateLimit-Limit: 100
-X-RateLimit-Remaining: 95
-X-RateLimit-Reset: 1735312800
-```
-
 ## Endpoints Overview
 
 ### Agents
@@ -131,7 +116,8 @@ data: [DONE]
 We recommend using our SDKs instead of calling the API directly:
 
 - **Server SDK**: `@octavus/server-sdk` - For Node.js backends
-- **Client SDK**: `@octavus/client-sdk` - For React frontends
+- **React SDK**: `@octavus/react` - For React applications
+- **Client SDK**: `@octavus/client-sdk` - For other frontend frameworks
 
 The SDKs handle authentication, streaming, and tool execution automatically.
 

package/content/06-examples/01-overview.md

@@ -0,0 +1,27 @@
+---
+title: Overview
+description: Complete integration examples for different architectures.
+---
+
+# Examples
+
+This section provides complete integration examples for different architectures. Each example walks through building a functional chat interface from scratch.
+
+## Available Examples
+
+| Example | Transport | Best For |
+|---------|-----------|----------|
+| [Next.js Chat](/docs/examples/nextjs-chat) | HTTP/SSE | Next.js, Remix, standard web apps |
+| [Socket Chat](/docs/examples/socket-chat) | SockJS | Meteor, Phoenix, real-time apps |
+
+## Choosing a Transport
+
+**Use HTTP Transport when:**
+- Building with Next.js, Remix, or similar frameworks
+- You want the simplest integration
+- Deploying to serverless (Vercel, Netlify, etc.)
+
+**Use Socket Transport when:**
+- Using Meteor, Phoenix, or socket-based frameworks
+- Need custom real-time events (typing indicators, presence)
+- Behind proxies that don't support SSE well