@octavus/docs 0.0.7 → 0.0.9

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
+