@octavus/docs 0.0.7 → 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

@@ -117,11 +117,19 @@ function Chat({ sessionId }: { sessionId: string }) {
 ### From Server SDK
 
 ```typescript
-const { stream } = session.trigger('user-message', {
+// 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

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

package/content/06-examples/02-nextjs-chat.md

@@ -0,0 +1,343 @@
+---
+title: Next.js Chat
+description: Building a chat interface with Next.js and HTTP transport.
+---
+
+# Next.js Chat Example
+
+This example builds a support chat interface using Next.js App Router with HTTP/SSE transport. This is the recommended pattern for most web applications.
+
+## What You're Building
+
+A chat interface that:
+- Creates sessions server-side
+- Streams AI responses in real-time
+- Handles tool calls on your server
+- Shows typing status during streaming
+
+## Architecture
+
+```mermaid
+flowchart LR
+    Browser["Browser<br/>(React)"] -->|"POST /api/chat"| NextJS["Next.js API<br/>Routes"]
+    NextJS -->|"SSE"| Browser
+    NextJS --> Platform["Octavus Platform"]
+```
+
+## Prerequisites
+
+- Next.js 14+ with App Router
+- Octavus account with API key
+- An agent configured in Octavus
+
+## Step 1: Install Dependencies
+
+```bash
+npm install @octavus/server-sdk @octavus/react
+```
+
+## Step 2: Configure Environment
+
+```bash
+# .env.local
+OCTAVUS_API_URL=https://octavus.ai
+OCTAVUS_API_KEY=your-api-key
+```
+
+## Step 3: Create the Octavus Client
+
+```typescript
+// lib/octavus.ts
+import { OctavusClient } from '@octavus/server-sdk';
+
+export const octavus = new OctavusClient({
+  baseUrl: process.env.OCTAVUS_API_URL!,
+  apiKey: process.env.OCTAVUS_API_KEY!,
+});
+```
+
+## Step 4: Create Session Endpoint
+
+Sessions hold conversation state. Create one when the user opens the chat:
+
+```typescript
+// app/api/sessions/route.ts
+import { NextResponse } from 'next/server';
+import { octavus } from '@/lib/octavus';
+
+export async function POST(request: Request) {
+  const { agentId, input } = await request.json();
+
+  // Create a new session with initial input variables
+  const sessionId = await octavus.agentSessions.create(agentId, input);
+
+  return NextResponse.json({ sessionId });
+}
+```
+
+**Protocol Note:** The `input` object contains variables defined in your agent's protocol. For example, if your agent has `COMPANY_NAME` as an input variable:
+
+```typescript
+const sessionId = await octavus.agentSessions.create(agentId, {
+  COMPANY_NAME: 'Acme Corp',
+  USER_ID: user.id,
+});
+```
+
+## Step 5: Create Trigger Endpoint
+
+Triggers execute agent actions. The `user-message` trigger is the most common:
+
+```typescript
+// app/api/trigger/route.ts
+import { toSSEStream } from '@octavus/server-sdk';
+import { octavus } from '@/lib/octavus';
+
+export async function POST(request: Request) {
+  const { sessionId, triggerName, input } = await request.json();
+
+  // Attach to the session with tool handlers
+  const session = octavus.agentSessions.attach(sessionId, {
+    tools: {
+      // Tool handlers run on YOUR server, not Octavus
+      'get-user-account': async (args) => {
+        const userId = args.userId as string;
+        // Fetch from your database
+        const user = await db.users.findUnique({ where: { id: userId } });
+        return {
+          name: user.name,
+          email: user.email,
+          plan: user.plan,
+        };
+      },
+
+      'create-support-ticket': async (args) => {
+        const ticket = await db.tickets.create({
+          data: {
+            summary: args.summary as string,
+            priority: args.priority as string,
+          },
+        });
+        return {
+          ticketId: ticket.id,
+          estimatedResponse: '24 hours',
+        };
+      },
+    },
+  });
+
+  // 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',
+    },
+  });
+}
+```
+
+**Protocol Note:** Tool names and arguments are defined in your agent's protocol YAML. The tool handlers here must match those definitions.
+
+## Step 6: Build the Chat Component
+
+```tsx
+// components/Chat.tsx
+'use client';
+
+import { useState, useMemo } from 'react';
+import { useOctavusChat, createHttpTransport } from '@octavus/react';
+
+interface ChatProps {
+  sessionId: string;
+}
+
+export function Chat({ sessionId }: ChatProps) {
+  const [inputValue, setInputValue] = useState('');
+
+  // Create transport - memoized on sessionId
+  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, send } = useOctavusChat({ transport });
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!inputValue.trim() || status === 'streaming') return;
+
+    const message = inputValue.trim();
+    setInputValue('');
+
+    // Send triggers the 'user-message' action
+    // The third argument adds the user message to the UI
+    await send(
+      'user-message',
+      { USER_MESSAGE: message },
+      { userMessage: { content: message } },
+    );
+  };
+
+  return (
+    <div className="flex flex-col h-screen">
+      {/* 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
+              className={`inline-block p-3 rounded-lg ${
+                msg.role === 'user'
+                  ? 'bg-blue-500 text-white'
+                  : 'bg-gray-100'
+              }`}
+            >
+              {msg.parts.map((part, i) => {
+                if (part.type === 'text') {
+                  return <p key={i}>{part.text}</p>;
+                }
+                if (part.type === 'tool-call') {
+                  return (
+                    <div key={i} className="text-sm opacity-70">
+                      Using {part.toolName}...
+                    </div>
+                  );
+                }
+                return null;
+              })}
+            </div>
+          </div>
+        ))}
+      </div>
+
+      {/* Input */}
+      <form onSubmit={handleSubmit} className="p-4 border-t">
+        <div className="flex gap-2">
+          <input
+            type="text"
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
+            placeholder="Type a message..."
+            className="flex-1 px-4 py-2 border rounded-lg"
+            disabled={status === 'streaming'}
+          />
+          <button
+            type="submit"
+            disabled={status === 'streaming'}
+            className="px-4 py-2 bg-blue-500 text-white rounded-lg"
+          >
+            {status === 'streaming' ? 'Sending...' : 'Send'}
+          </button>
+        </div>
+      </form>
+    </div>
+  );
+}
+```
+
+## Step 7: Create the Page
+
+```tsx
+// app/chat/page.tsx
+'use client';
+
+import { useEffect, useState } from 'react';
+import { Chat } from '@/components/Chat';
+
+const AGENT_ID = 'your-agent-id'; // From Octavus dashboard
+
+export default function ChatPage() {
+  const [sessionId, setSessionId] = useState<string | null>(null);
+
+  useEffect(() => {
+    // Create session on mount
+    fetch('/api/sessions', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        agentId: AGENT_ID,
+        input: {
+          COMPANY_NAME: 'Acme Corp',
+        },
+      }),
+    })
+      .then((res) => res.json())
+      .then((data) => setSessionId(data.sessionId));
+  }, []);
+
+  if (!sessionId) {
+    return <div className="p-8">Loading...</div>;
+  }
+
+  return <Chat sessionId={sessionId} />;
+}
+```
+
+## Protocol Integration
+
+Your agent's protocol defines the triggers and tools. Here's how the code maps to protocol:
+
+### Triggers
+
+```yaml
+# In your agent's protocol.yaml
+triggers:
+  user-message:
+    description: User sends a chat message
+    input:
+      USER_MESSAGE:
+        type: string
+        description: The user's message
+```
+
+The `send()` call maps directly:
+
+```typescript
+await send(
+  'user-message',           // trigger name
+  { USER_MESSAGE: message }, // trigger inputs
+  { userMessage: { content: message } },
+);
+```
+
+### Tools
+
+```yaml
+# In your agent's protocol.yaml
+tools:
+  get-user-account:
+    description: Fetch user account details
+    parameters:
+      userId:
+        type: string
+        description: The user ID to look up
+```
+
+Tool handlers receive the parameters as `args`:
+
+```typescript
+'get-user-account': async (args) => {
+  const userId = args.userId as string;
+  // ...
+}
+```
+
+## Next Steps
+
+- [Protocol Overview](/docs/protocol/overview) — Define agent behavior
+- [Messages](/docs/client-sdk/messages) — Rich message rendering
+- [Streaming](/docs/client-sdk/streaming) — Advanced streaming UI
+