@toothfairyai/sdk 0.2.6 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # ToothFairyAI SDK for JavaScript/TypeScript
 
-A comprehensive, TypeScript-first SDK for integrating with the ToothFairyAI API. Built for developers who want to embed AI agent functionality into their applications.
+Official TypeScript SDK for the ToothFairyAI API - A comprehensive toolkit for building AI-powered applications with chat, document processing, agent management, and more.
 
 ## Installation
 
@@ -8,360 +8,1603 @@ A comprehensive, TypeScript-first SDK for integrating with the ToothFairyAI API.
 npm install @toothfairyai/sdk
 ```
 
-## Configuration
+## Quick Start
+
+```typescript
+import { ToothFairyClient } from '@toothfairyai/sdk';
+
+const client = new ToothFairyClient({
+  apiKey: 'your-api-key',
+  workspaceId: 'your-workspace-id'
+});
+
+// Send a message to an agent
+const response = await client.chat.sendToAgent('Hello, how can you help me?', 'agent-id');
+console.log(response.agentResponse);
+```
+
+## Table of Contents
+
+- [SDK Overview](#sdk-overview)
+- [Client Configuration](#client-configuration)
+- [Core Features](#core-features)
+- [Complete API Reference](#complete-api-reference)
+  - [Chat & Messaging](#chat--messaging)
+  - [Agents](#agents)
+  - [Documents](#documents)
+  - [Entities](#entities)
+  - [Folders](#folders)
+  - [Prompts](#prompts)
+  - [Agent Functions](#agent-functions)
+  - [Authorisations](#authorisations)
+  - [Channels](#channels)
+  - [Connections](#connections)
+  - [Members](#members)
+  - [Sites](#sites)
+  - [Benchmarks](#benchmarks)
+  - [Hooks](#hooks)
+  - [Scheduled Jobs](#scheduled-jobs)
+  - [Secrets](#secrets)
+  - [Dictionary](#dictionary)
+  - [Embeddings](#embeddings)
+  - [Settings](#settings)
+  - [Billing](#billing)
+  - [Streams](#streams)
+  - [Request Logs](#request-logs)
+- [Streaming Responses](#streaming-responses)
+- [Error Handling](#error-handling)
+- [Best Practices](#best-practices)
+
+## SDK Overview
+
+The ToothFairyAI SDK provides a TypeScript-first interface to all 95 API endpoints, organized into 18 specialized managers:
+
+| Manager | Purpose | Endpoints |
+|---------|---------|-----------|
+| `client.chat` | Chat conversations & messages | 7 |
+| `client.agents` | AI agent management | 5 |
+| `client.documents` | Document upload & management | 6 |
+| `client.entities` | Topics, intents, NER entities | 5 |
+| `client.folders` | Content organization | 5 |
+| `client.prompts` | Prompt templates | 5 |
+| `client.agentFunctions` | Agent function calls | 5 |
+| `client.authorisations` | Auth configurations | 5 |
+| `client.channels` | Communication channels | 5 |
+| `client.connections` | Database/API connections | 3 |
+| `client.members` | Workspace members | 4 |
+| `client.sites` | Website crawling | 4 |
+| `client.benchmarks` | Performance testing | 5 |
+| `client.hooks` | Custom code execution | 5 |
+| `client.scheduledJobs` | Cron jobs & scheduling | 5 |
+| `client.secrets` | Secret management | 2 |
+| `client.dictionary` | Translation dictionary | 2 |
+| `client.embeddings` | Document embeddings | 1 |
+| `client.chartingSettings` | Charting configuration | 2 |
+| `client.embeddingsSettings` | Embeddings configuration | 2 |
+| `client.billing` | Usage & costs | 1 |
+| `client.streams` | Output streams | 2 |
+| `client.requestLogs` | Request logging | 2 |
+| `client.streaming` | Real-time streaming | - |
+
+## Client Configuration
+
+### Region-Specific Endpoints
+
+ToothFairyAI operates in multiple regions. Configure your client to use the appropriate endpoints:
+
+```typescript
+// US Region
+const clientUS = new ToothFairyClient({
+  apiKey: 'your-api-key',
+  workspaceId: 'your-workspace-id',
+  baseUrl: 'https://api.us.toothfairyai.com',
+  aiUrl: 'https://ai.us.toothfairyai.com',
+  aiStreamUrl: 'https://ai-stream.us.toothfairyai.com'
+});
+
+// EU Region
+const clientEU = new ToothFairyClient({
+  apiKey: 'your-api-key',
+  workspaceId: 'your-workspace-id',
+  baseUrl: 'https://api.eu.toothfairyai.com',
+  aiUrl: 'https://ai.eu.toothfairyai.com',
+  aiStreamUrl: 'https://ai-stream.eu.toothfairyai.com'
+});
+
+// Australia Region (default)
+const clientAU = new ToothFairyClient({
+  apiKey: 'your-api-key',
+  workspaceId: 'your-workspace-id',
+  baseUrl: 'https://api.toothfairyai.com',
+  aiUrl: 'https://ai.toothfairyai.com',
+  aiStreamUrl: 'https://ais.toothfairyai.com'
+});
+```
+
+### Configuration Options
+
+```typescript
+const client = new ToothFairyClient({
+  apiKey: 'your-api-key',           // Required: Your API key
+  workspaceId: 'your-workspace-id', // Required: Your workspace ID
+  baseUrl: 'https://api.toothfairyai.com',        // Optional: API base URL (region-specific)
+  aiUrl: 'https://ai.toothfairyai.com',           // Optional: AI service URL (region-specific)
+  aiStreamUrl: 'https://ais.toothfairyai.com', // Optional: Streaming URL (region-specific)
+  timeout: 120000                   // Optional: Request timeout in ms (default: 120000)
+});
+```
+
+### Getting Your Credentials
+
+1. **API Key**: Log in to ToothFairyAI Admin → API Integration → Generate API Key
+2. **Workspace ID**: Found in your workspace settings or API dashboard
+
+## Core Features
+
+### 1. Chat & Messaging
+Create conversations, send messages, and manage chat history with AI agents.
+
+### 2. Agent Management
+Create, configure, and manage AI agents with different modes (retriever, chatter, planner, etc.).
+
+### 3. Document Processing
+Upload, search, and manage documents for knowledge base integration.
+
+### 4. Entity Management
+Organize content with topics, intents, and named entity recognition.
+
+### 5. Streaming
+Real-time streaming responses with EventEmitter-based pattern.
+
+## Complete API Reference
+
+### Chat & Messaging
+
+#### Create a Chat Session
+
+```typescript
+const chat = await client.chat.create({
+  name: 'Customer Support',
+  primaryRole: 'agent-id',
+  customerId: 'customer-123',
+  customerInfo: { name: 'John Doe', email: 'john@example.com' },
+  externalParticipantId: 'john@example.com',
+  channelSettings: {
+    sms: { isEnabled: true, recipient: '+1234567890', providerID: 'twilio' },
+    email: { isEnabled: true, recipient: 'john@example.com' }
+  }
+});
+console.log(`Chat ID: ${chat.id}`);
+```
+
+#### Update a Chat
+
+```typescript
+const chat = await client.chat.update({
+  id: 'chat-id',
+  name: 'Updated Chat Name',
+  customerId: 'new-customer-id'
+});
+```
+
+#### Get Chat Details
+
+```typescript
+const chat = await client.chat.get('chat-id');
+console.log(`Chat: ${chat.name}`);
+console.log(`Primary Role: ${chat.primaryRole}`);
+```
+
+#### List Chats
+
+```typescript
+const chats = await client.chat.list(10, 0);
+for (const chat of chats.items) {
+  console.log(`${chat.name} (ID: ${chat.id})`);
+}
+```
+
+#### Delete a Chat
+
+```typescript
+await client.chat.delete('chat-id');
+```
+
+#### Create a Message
+
+```typescript
+const message = await client.chat.createMessage({
+  chatID: 'chat-id',
+  text: 'Hello, I need help with my account',
+  role: 'user',
+  userID: 'user-123',
+  images: ['https://example.com/image.jpg'],
+  files: ['https://example.com/document.pdf']
+});
+```
+
+#### Update a Message
+
+```typescript
+const message = await client.chat.updateMessage('message-id', {
+  text: 'Updated message text',
+  role: 'user'
+});
+```
+
+#### Get a Message
+
+```typescript
+const message = await client.chat.getMessage('message-id');
+console.log(`Message: ${message.text}`);
+```
+
+#### List Messages in a Chat
+
+```typescript
+const messages = await client.chat.listMessages('chat-id', 20, 0);
+for (const msg of messages.items) {
+  console.log(`${msg.role}: ${msg.text}`);
+}
+```
+
+#### Send Message to Agent (Non-Streaming)
+
+```typescript
+const response = await client.chat.sendToAgent(
+  'Hello, how can you help me?',
+  'agent-id',
+  {
+    chatId: 'existing-chat-id',  // Optional - creates new chat if not provided
+    phoneNumber: '+1234567890',  // Optional
+    customerId: 'customer-123',   // Optional
+    providerId: 'provider-id',    // Optional
+    customerInfo: { name: 'John' },  // Optional
+    attachments: {
+      images: ['https://example.com/image.jpg'],
+      files: ['https://example.com/document.pdf'],
+      audios: ['https://example.com/audio.mp3'],
+      videos: ['https://example.com/video.mp4']
+    }
+  }
+);
+console.log(`Response: ${response.agentResponse}`);
+console.log(`Chat ID: ${response.chatId}`);
+console.log(`Message ID: ${response.messageId}`);
+```
+
+### Agents
+
+#### Create an Agent
+
+```typescript
+const agent = await client.agents.create({
+  label: 'Customer Support Agent',
+  mode: 'retriever',  // retriever, coder, chatter, planner, computer, voice
+  interpolationString: 'You are a helpful customer support assistant...',
+  goals: 'Help customers resolve issues and answer questions',
+  temperature: 0.7,
+  maxTokens: 2000,
+  maxHistory: 10,
+  topK: 10,
+  docTopK: 5,
+  description: 'Specialized agent for customer support',
+  hasMemory: true,
+  showCitations: true,
+  allowedTopics: ['topic-1', 'topic-2'],
+  staticDocs: ['doc-1', 'doc-2']
+});
+console.log(`Agent ID: ${agent.id}`);
+```
+
+#### Update an Agent
+
+```typescript
+const agent = await client.agents.update('agent-id', {
+  label: 'Updated Agent Name',
+  temperature: 0.8,
+  maxTokens: 3000
+});
+```
+
+#### Get Agent Details
+
+```typescript
+const agent = await client.agents.get('agent-id');
+console.log(`Agent: ${agent.label}`);
+console.log(`Mode: ${agent.mode}`);
+console.log(`Goals: ${agent.goals}`);
+```
+
+#### List Agents
+
+```typescript
+const agents = await client.agents.list(10, 0);
+for (const agent of agents.items) {
+  console.log(`${agent.label} (${agent.mode})`);
+}
+```
+
+#### Delete an Agent
+
+```typescript
+await client.agents.delete('agent-id');
+```
+
+### Documents
+
+#### Upload a Document
+
+```typescript
+const result = await client.documents.upload('/path/to/document.pdf', 'folder-id', {
+  onProgress: (percent, loaded, total) => {
+    console.log(`Progress: ${percent}%`);
+  }
+});
+console.log(`Uploaded: ${result.filename}`);
+console.log(`Size: ${result.sizeInMB} MB`);
+```
+
+#### Upload from Base64
+
+```typescript
+const base64Data = 'base64-encoded-file-data';
+const result = await client.documents.uploadFromBase64(
+  base64Data,
+  'document.pdf',
+  'application/pdf',
+  'folder-id'
+);
+```
+
+#### Create Document from URL
+
+```typescript
+const doc = await client.documents.createFromPath(
+  'https://example.com/document.pdf',
+  'user-123',
+  {
+    title: 'My Document',
+    folderId: 'folder-id',
+    topics: ['topic-1', 'topic-2'],
+    status: 'published'
+  }
+);
+```
+
+#### Create Document Record
+
+```typescript
+const doc = await client.documents.create({
+  userid: 'user-123',
+  title: 'My Document',
+  type: 'readComprehensionFile',  // readComprehensionUrl, readComprehensionPdf
+  topics: ['topic-1'],
+  folderid: 'folder-id',
+  external_path: 'https://example.com/doc.pdf',
+  source: 'external',
+  status: 'published',
+  scope: 'training'
+});
+```
+
+#### Get Document
+
+```typescript
+const doc = await client.documents.get('doc-id');
+console.log(`Title: ${doc.title}`);
+console.log(`Type: ${doc.type}`);
+console.log(`Status: ${doc.status}`);
+```
+
+#### Update Document
+
+```typescript
+const doc = await client.documents.update('doc-id', {
+  userid: 'user-123',
+  title: 'Updated Title',
+  topics: ['new-topic'],
+  folderid: 'new-folder-id',
+  status: 'published'
+});
+```
+
+#### List Documents
+
+```typescript
+const docs = await client.documents.list(20, 0, 'folder-id', 'published');
+for (const doc of docs.items) {
+  console.log(`${doc.title} (ID: ${doc.id})`);
+}
+```
+
+#### Delete Document
+
+```typescript
+await client.documents.delete('doc-id');
+```
+
+#### Search Documents
+
+```typescript
+const results = await client.documents.search('dental procedures', {
+  topK: 10,
+  metadata: { category: 'procedures' }
+});
+for (const result of results) {
+  console.log(`Score: ${result.score}`);
+  console.log(`Content: ${result.content}`);
+}
+```
+
+#### Download Document
+
+```typescript
+const result = await client.documents.download(
+  'document.pdf',
+  '/downloads/document.pdf',
+  'documents',
+  {
+    onProgress: (percent, loaded, total) => {
+      console.log(`Download: ${percent}%`);
+    }
+  }
+);
+console.log(`Downloaded: ${result.filename}`);
+```
+
+### Entities
+
+#### Create an Entity
+
+```typescript
+const entity = await client.entities.create('user-123', 'Dental Cleaning', 'topic', {
+  description: 'Professional teeth cleaning procedures',
+  emoji: '🦷',
+  parentEntity: 'parent-topic-id',
+  backgroundColor: '#FF5733'
+});
+```
+
+#### Get Entity
+
+```typescript
+const entity = await client.entities.get('entity-id');
+console.log(`Label: ${entity.label}`);
+console.log(`Type: ${entity.type}`);
+```
+
+#### Update Entity
+
+```typescript
+const entity = await client.entities.update('entity-id', {
+  label: 'Updated Label',
+  description: 'New description',
+  emoji: '🔧'
+});
+```
+
+#### Delete Entity
+
+```typescript
+await client.entities.delete('entity-id');
+```
+
+#### List Entities
+
+```typescript
+const entities = await client.entities.list(20, 'topic');
+for (const entity of entities.items) {
+  console.log(`${entity.label} (${entity.type})`);
+}
+```
+
+#### Get Entities by Type
+
+```typescript
+const topics = await client.entities.getByType('topic');
+const intents = await client.entities.getByType('intent');
+const nerEntities = await client.entities.getByType('ner');
+```
+
+#### Search Entities
+
+```typescript
+const results = await client.entities.search('cleaning', 'topic');
+for (const entity of results) {
+  console.log(`${entity.label}`);
+}
+```
+
+### Folders
+
+#### Create a Folder
+
+```typescript
+const folder = await client.folders.create('user-123', 'Procedures', {
+  description: 'Medical procedures documentation',
+  emoji: '📁',
+  status: 'active',
+  parent: 'parent-folder-id'  // Optional - for subfolders
+});
+```
+
+#### Get Folder
+
+```typescript
+const folder = await client.folders.get('folder-id');
+console.log(`Name: ${folder.name}`);
+console.log(`Parent: ${folder.parent}`);
+```
+
+#### Update Folder
+
+```typescript
+const folder = await client.folders.update('folder-id', {
+  name: 'Updated Name',
+  description: 'New description',
+  status: 'active'
+});
+```
+
+#### Delete Folder
+
+```typescript
+await client.folders.delete('folder-id');
+```
+
+#### List Folders
+
+```typescript
+const folders = await client.folders.list('active', 20, 0);
+for (const folder of folders.items) {
+  console.log(`${folder.name}`);
+}
+```
+
+#### Get Root Folders
+
+```typescript
+const rootFolders = await client.folders.getRootFolders();
+for (const folder of rootFolders) {
+  console.log(`Root: ${folder.name}`);
+}
+```
+
+#### Get Subfolders
+
+```typescript
+const subfolders = await client.folders.getSubfolders('folder-id');
+for (const folder of subfolders) {
+  console.log(`Subfolder: ${folder.name}`);
+}
+```
+
+#### Get Folder Tree
+
+```typescript
+const tree = await client.folders.getTree();
+
+function printTree(nodes: any[], level = 0) {
+  for (const node of nodes) {
+    console.log('  '.repeat(level) + `📁 ${node.name}`);
+    printTree(node.children, level + 1);
+  }
+}
+
+printTree(tree);
+```
+
+#### Search Folders
+
+```typescript
+const results = await client.folders.search('procedures');
+for (const folder of results) {
+  console.log(`${folder.name}`);
+}
+```
+
+### Prompts
+
+#### Create a Prompt
+
+```typescript
+const prompt = await client.prompts.create('user-123', {
+  type: 'greeting',
+  label: 'Greeting',
+  promptLength: 50,
+  interpolationString: 'Hello {{name}}, how can I help you today?',
+  scope: 'global',
+  style: 'friendly',
+  domain: 'customer-support',
+  promptPlaceholder: 'Enter greeting message',
+  availableToAgents: ['agent-1', 'agent-2']
+});
+```
+
+#### Get Prompt
+
+```typescript
+const prompt = await client.prompts.get('prompt-id');
+console.log(`Label: ${prompt.label}`);
+console.log(`Template: ${prompt.interpolationString}`);
+```
+
+#### Update Prompt
+
+```typescript
+const prompt = await client.prompts.update('prompt-id', {
+  label: 'Updated Label',
+  interpolationString: 'New template string',
+  availableToAgents: ['agent-3']
+});
+```
+
+#### Delete Prompt
+
+```typescript
+await client.prompts.delete('prompt-id');
+```
+
+#### List Prompts
+
+```typescript
+const prompts = await client.prompts.list({
+  type: 'greeting',
+  limit: 20,
+  offset: 0
+});
+for (const prompt of prompts.items) {
+  console.log(`${prompt.label}`);
+}
+```
+
+#### Get Prompts by Type
+
+```typescript
+const greetings = await client.prompts.getByType('greeting');
+```
+
+#### Get Prompts by Agent
+
+```typescript
+const agentPrompts = await client.prompts.getByAgent('agent-id');
+```
+
+#### Get Prompts by Scope
+
+```typescript
+const globalPrompts = await client.prompts.getByScope('global');
+```
+
+#### Search Prompts
+
+```typescript
+const results = await client.prompts.search('greeting', 'greeting');
+```
+
+#### Clone Prompt
+
+```typescript
+const cloned = await client.prompts.clone('prompt-id', 'user-123', {
+  label: 'Cloned Greeting',
+  interpolationString: 'Modified template'
+});
+```
+
+### Agent Functions
+
+#### Create an Agent Function
+
+```typescript
+const func = await client.agentFunctions.create({
+  id: 'function-1',
+  name: 'Weather API',
+  url: 'https://api.weather.com/current',
+  model: 'gpt-4',
+  requestType: 'GET',
+  authorisationType: 'bearer',
+  authorisationKey: 'your-token',
+  description: 'Get current weather data',
+  parameters: [
+    { name: 'location', type: 'string', required: true }
+  ]
+});
+```
+
+#### Update Agent Function
+
+```typescript
+const func = await client.agentFunctions.update({
+  id: 'function-1',
+  name: 'Updated Function Name',
+  url: 'https://new-url.com'
+});
+```
+
+#### Delete Agent Function
+
+```typescript
+await client.agentFunctions.delete('function-1');
+```
+
+#### Get Agent Function
+
+```typescript
+const func = await client.agentFunctions.get('function-1');
+console.log(`Name: ${func.name}`);
+console.log(`URL: ${func.url}`);
+```
+
+#### List Agent Functions
+
+```typescript
+const functions = await client.agentFunctions.list(20);
+for (const func of functions.items) {
+  console.log(`${func.name}`);
+}
+```
+
+### Authorisations
+
+#### Create an Authorisation
+
+```typescript
+const auth = await client.authorisations.create({
+  id: 'auth-1',
+  name: 'GitHub OAuth',
+  type: 'oauth',
+  tokenSecret: 'encrypted-token',
+  description: 'GitHub OAuth token for API access',
+  scope: 'repo,user',
+  grantType: 'authorization_code',
+  clientId: 'github-client-id',
+  clientSecret: 'encrypted-secret',
+  authorizationBaseUrl: 'https://github.com/login/oauth/authorize',
+  tokenBaseUrl: 'https://github.com/login/oauth/access_token'
+});
+```
+
+#### Update Authorisation
+
+```typescript
+const auth = await client.authorisations.update({
+  id: 'auth-1',
+  name: 'Updated Auth Name',
+  scope: 'repo,user,admin'
+});
+```
+
+#### Delete Authorisation
+
+```typescript
+await client.authorisations.delete('auth-1');
+```
+
+#### Get Authorisation
+
+```typescript
+const auth = await client.authorisations.get('auth-1');
+console.log(`Name: ${auth.name}`);
+console.log(`Type: ${auth.type}`);
+```
+
+#### List Authorisations
+
+```typescript
+const auths = await client.authorisations.list(20);
+for (const auth of auths.items) {
+  console.log(`${auth.name} (${auth.type})`);
+}
+```
+
+### Channels
+
+#### Create a Channel
+
+```typescript
+const channel = await client.channels.create({
+  id: 'channel-1',
+  name: 'SMS Channel',
+  channel: 'sms',
+  provider: 'twilio',
+  senderid: '+1234567890',
+  description: 'SMS notifications via Twilio',
+  isActive: true
+});
+```
+
+#### Update Channel
+
+```typescript
+const channel = await client.channels.update({
+  id: 'channel-1',
+  name: 'Updated Channel',
+  isActive: false
+});
+```
+
+#### Delete Channel
+
+```typescript
+await client.channels.delete('channel-1');
+```
+
+#### Get Channel
+
+```typescript
+const channel = await client.channels.get('channel-1');
+console.log(`Name: ${channel.name}`);
+console.log(`Provider: ${channel.provider}`);
+```
+
+#### List Channels
+
+```typescript
+const channels = await client.channels.list(20);
+for (const channel of channels.items) {
+  console.log(`${channel.name} (${channel.provider})`);
+}
+```
+
+### Connections
+
+#### Get Connection
+
+```typescript
+const connection = await client.connections.get('connection-id');
+console.log(`Name: ${connection.name}`);
+console.log(`Type: ${connection.type}`);
+console.log(`Host: ${connection.host}`);
+```
+
+#### List Connections
+
+```typescript
+const connections = await client.connections.list(20);
+for (const conn of connections.items) {
+  console.log(`${conn.name} (${conn.type})`);
+}
+```
+
+#### Delete Connection
+
+```typescript
+await client.connections.delete('connection-id');
+```
+
+### Members
+
+#### Get Member
+
+```typescript
+const member = await client.members.get('member-id');
+console.log(`User ID: ${member.userID}`);
+console.log(`Role: ${member.role}`);
+console.log(`Status: ${member.status}`);
+```
+
+#### List Members
+
+```typescript
+const members = await client.members.list(20);
+for (const member of members.items) {
+  console.log(`${member.userID} (${member.role})`);
+}
+```
+
+#### Update Member
+
+```typescript
+const member = await client.members.update({
+  id: 'member-id',
+  role: 'admin',
+  status: 'active'
+});
+```
+
+#### Delete Member
+
+```typescript
+await client.members.delete('member-id');
+```
+
+### Sites
+
+#### Get Site
+
+```typescript
+const site = await client.sites.get('site-id');
+console.log(`Name: ${site.name}`);
+console.log(`URL: ${site.url}`);
+console.log(`Status: ${site.status}`);
+```
+
+#### List Sites
+
+```typescript
+const sites = await client.sites.list(20);
+for (const site of sites.items) {
+  console.log(`${site.name} - ${site.url}`);
+}
+```
+
+#### Update Site
+
+```typescript
+const site = await client.sites.update({
+  id: 'site-id',
+  name: 'Updated Site',
+  status: 'active',
+  allowedPaths: ['/docs', '/blog']
+});
+```
+
+#### Delete Site
+
+```typescript
+await client.sites.delete('site-id');
+```
+
+### Benchmarks
+
+#### Create a Benchmark
+
+```typescript
+const benchmark = await client.benchmarks.create({
+  id: 'benchmark-1',
+  name: 'Customer Support Test',
+  description: 'Test agent performance on customer support queries',
+  questions: [
+    {
+      question: 'How do I reset my password?',
+      answer: 'Go to Settings > Security > Reset Password',
+      reasoning: 'Standard password reset flow',
+      context: 'Account management'
+    }
+  ],
+  files: ['doc-1', 'doc-2']
+});
+```
+
+#### Update Benchmark
+
+```typescript
+const benchmark = await client.benchmarks.update({
+  id: 'benchmark-1',
+  name: 'Updated Benchmark',
+  description: 'New description'
+});
+```
+
+#### Delete Benchmark
+
+```typescript
+await client.benchmarks.delete('benchmark-1');
+```
+
+#### Get Benchmark
+
+```typescript
+const benchmark = await client.benchmarks.get('benchmark-1');
+console.log(`Name: ${benchmark.name}`);
+console.log(`Questions: ${benchmark.questions?.length}`);
+```
+
+#### List Benchmarks
+
+```typescript
+const benchmarks = await client.benchmarks.list(20);
+for (const benchmark of benchmarks.items) {
+  console.log(`${benchmark.name}`);
+}
+```
+
+### Hooks
+
+#### Create a Hook
+
+```typescript
+const hook = await client.hooks.create({
+  id: 'hook-1',
+  name: 'Data Processing Hook',
+  functionName: 'process_data',
+  customExecutionCode: 'def process_data(data): return data.upper()',
+  customExecutionInstructions: 'Process incoming data',
+  availableLibraries: 'pandas,numpy',
+  allowExternalAPI: true,
+  hardcodedScript: false
+});
+```
+
+#### Update Hook
+
+```typescript
+const hook = await client.hooks.update({
+  id: 'hook-1',
+  name: 'Updated Hook',
+  customExecutionCode: 'def process_data(data): return data.lower()'
+});
+```
 
-### Region-Specific Endpoints
+#### Delete Hook
+
+```typescript
+await client.hooks.delete('hook-1');
+```
 
-ToothFairyAI operates in multiple regions. Configure your client to use the appropriate endpoints for your region:
+#### Get Hook
 
 ```typescript
-import { ToothFairyClient } from '@toothfairyai/sdk';
+const hook = await client.hooks.get('hook-1');
+console.log(`Name: ${hook.name}`);
+console.log(`Function: ${hook.functionName}`);
+```
 
-// US Region
-const clientUS = new ToothFairyClient({
-  apiKey: 'your-api-key',
-  workspaceId: 'your-workspace-id',
-  baseUrl: 'https://api.us.toothfairyai.com',
-  aiUrl: 'https://ai.us.toothfairyai.com',
-  aiStreamUrl: 'https://ai-stream.us.toothfairyai.com'
-});
+#### List Hooks
 
-// EU Region
-const clientEU = new ToothFairyClient({
-  apiKey: 'your-api-key',
-  workspaceId: 'your-workspace-id',
-  baseUrl: 'https://api.eu.toothfairyai.com',
-  aiUrl: 'https://ai.eu.toothfairyai.com',
-  aiStreamUrl: 'https://ai-stream.eu.toothfairyai.com'
+```typescript
+const hooks = await client.hooks.list(20);
+for (const hook of hooks.items) {
+  console.log(`${hook.name}`);
+}
+```
+
+### Scheduled Jobs
+
+#### Create a Scheduled Job
+
+```typescript
+const job = await client.scheduledJobs.create({
+  id: 'job-1',
+  name: 'Daily Report',
+  description: 'Generate daily report at 9 AM',
+  agentID: 'agent-id',
+  customPromptID: 'prompt-id',
+  forcedPrompt: 'Generate a daily summary report',
+  schedule: {
+    frequency: 'DAILY',
+    hour: 9,
+    minute: 0
+  },
+  timezone: 'UTC',
+  isActive: true,
+  status: 'ACTIVE'
 });
+```
 
-// Australia Region (default if not specified)
-const clientAU = new ToothFairyClient({
-  apiKey: 'your-api-key',
-  workspaceId: 'your-workspace-id',
-  baseUrl: 'https://api.toothfairyai.com',
-  aiUrl: 'https://ai.toothfairyai.com',
-  aiStreamUrl: 'https://ai-stream.toothfairyai.com'
+#### Update Scheduled Job
+
+```typescript
+const job = await client.scheduledJobs.update({
+  id: 'job-1',
+  name: 'Updated Job',
+  isActive: false,
+  schedule: {
+    frequency: 'WEEKLY',
+    dayOfWeek: 1,
+    hour: 9
+  }
 });
 ```
 
-**Available Regions:**
-- **US**: `api.us.toothfairyai.com` / `ai.us.toothfairyai.com`
-- **EU**: `api.eu.toothfairyai.com` / `ai.eu.toothfairyai.com`
-- **Australia** (default): `api.toothfairyai.com` / `ai.toothfairyai.com`
+#### Delete Scheduled Job
 
-### Configuration Options
+```typescript
+await client.scheduledJobs.delete('job-1');
+```
+
+#### Get Scheduled Job
 
 ```typescript
-const client = new ToothFairyClient({
-  apiKey: 'your-api-key',           // Required: Your ToothFairyAI API key
-  workspaceId: 'your-workspace-id', // Required: Your workspace ID
-  baseUrl: 'https://api.us.toothfairyai.com',        // Optional: API base URL (region-specific)
-  aiUrl: 'https://ai.us.toothfairyai.com',           // Optional: AI service URL (region-specific)
-  aiStreamUrl: 'https://ai-stream.us.toothfairyai.com', // Optional: Streaming URL (region-specific)
-  timeout: 120000                   // Optional: Request timeout in ms
+const job = await client.scheduledJobs.get('job-1');
+console.log(`Name: ${job.name}`);
+console.log(`Status: ${job.status}`);
+console.log(`Schedule: ${JSON.stringify(job.schedule)}`);
+```
+
+#### List Scheduled Jobs
+
+```typescript
+const jobs = await client.scheduledJobs.list(20);
+for (const job of jobs.items) {
+  console.log(`${job.name} (${job.status})`);
+}
+```
+
+### Secrets
+
+#### Create a Secret
+
+```typescript
+const secret = await client.secrets.create({
+  id: 'secret-1',
+  name: 'API Key',
+  description: 'External API key for service X'
 });
 ```
 
-## Quick Start
+#### Delete Secret
 
 ```typescript
-import { ToothFairyClient } from '@toothfairyai/sdk';
+await client.secrets.delete('secret-1');
+```
 
-const client = new ToothFairyClient({
-  apiKey: 'your-api-key',
-  workspaceId: 'your-workspace-id'
-  // Uses Australia region by default
+### Dictionary
+
+#### Get Dictionary Entry
+
+```typescript
+const entry = await client.dictionary.get('entry-id');
+console.log(`Source: ${entry.sourceText}`);
+console.log(`Target: ${entry.targetText}`);
+console.log(`Languages: ${entry.sourceLanguage} -> ${entry.targetLanguage}`);
+```
+
+#### List Dictionary Entries
+
+```typescript
+const entries = await client.dictionary.list(20);
+for (const entry of entries.items) {
+  console.log(`${entry.sourceLanguage} -> ${entry.targetLanguage}`);
+}
+```
+
+### Embeddings
+
+#### Get Document Embeddings
+
+```typescript
+const embeddings = await client.embeddings.get();
+for (const emb of embeddings) {
+  console.log(`Document: ${emb.title}`);
+  console.log(`Chunk: ${emb.chunk_id}`);
+  console.log(`Type: ${emb.type}`);
+}
+```
+
+### Settings
+
+#### Charting Settings
+
+```typescript
+// Get charting settings
+const settings = await client.chartingSettings.get('settings-id');
+console.log(`Primary Color: ${settings.primaryColor}`);
+console.log(`Secondary Color: ${settings.secondaryColor}`);
+
+// Update charting settings
+const updated = await client.chartingSettings.update({
+  id: 'settings-id',
+  primaryColor: '#FF5733',
+  secondaryColor: '#33FF57',
+  lineColor: '#3357FF'
 });
+```
 
-// Send a message to an agent
-const response = await client.chat.sendToAgent('Hello', 'agent-id');
-console.log(response.agentResponse);
+#### Embeddings Settings
+
+```typescript
+// Get embeddings settings
+const settings = await client.embeddingsSettings.get('settings-id');
+console.log(`Max Chunk Words: ${settings.maxChunkWords}`);
+console.log(`Chunking Strategy: ${settings.chunkingStrategy}`);
+
+// Update embeddings settings
+const updated = await client.embeddingsSettings.update({
+  id: 'settings-id',
+  maxChunkWords: 1000,
+  chunkingStrategy: 'summary',
+  imageExtractionStrategy: 'safe'
+});
+```
+
+### Billing
+
+#### Get Monthly Costs
+
+```typescript
+const costs = await client.billing.getMonthCosts();
+console.log(`API Usage: ${JSON.stringify(costs.apiUsage)}`);
+console.log(`Training Usage: ${JSON.stringify(costs.trainingUsage)}`);
+console.log(`Total Cost: $${costs.apiUsage?.totalCostUSD || 0}`);
+```
+
+### Streams
+
+#### Get Output Stream
+
+```typescript
+const stream = await client.streams.get('stream-id');
+console.log(`Content: ${stream.content}`);
+console.log(`Type: ${stream.type}`);
+console.log(`Status: ${stream.status}`);
+```
+
+#### List Output Streams
+
+```typescript
+const streams = await client.streams.list(20);
+for (const stream of streams.items) {
+  console.log(`${stream.type} - ${stream.status}`);
+}
+```
+
+### Request Logs
+
+#### Get Request Log
+
+```typescript
+const log = await client.requestLogs.get('log-id');
+console.log(`Type: ${log.type}`);
+console.log(`Status: ${log.status}`);
+console.log(`Tokens: ${log.tokens}`);
+console.log(`Words: ${log.words}`);
 ```
 
-## Features
+#### List Request Logs
 
-- 🔄 **Real-time Streaming**: Event-driven streaming for live agent interactions
-- 📄 **Document Management**: Upload, download, and search through documents
-- 🏷️ **Entity Management**: Manage topics, intents, and NER entities
-- 📁 **Folder Organization**: Organize documents hierarchically
-- 🤖 **Prompt Management**: Create and manage AI prompts
-- 💬 **Chat Management**: Handle conversations and messaging
-- 🔧 **TypeScript First**: Comprehensive type definitions included
-- 📦 **Modular Design**: Use only what you need
-- 🌍 **Multi-Region Support**: US, EU, and Australia endpoints
+```typescript
+const logs = await client.requestLogs.list(20);
+for (const log of logs.items) {
+  console.log(`${log.type} - ${log.status} (${log.tokens} tokens)`);
+}
+```
+
+## Streaming Responses
 
-## Architecture
+### Simple Streaming
 
-The SDK is organized into logical modules:
+```typescript
+const session = await client.streaming.sendToAgent('Tell me about dental care', 'agent-id');
 
-- **`client.chat`** - Chat and messaging operations
-- **`client.streaming`** - Real-time streaming functionality
-- **`client.documents`** - Document upload, download, search, and management
-- **`client.entities`** - Entity management (topics, intents, NER)
-- **`client.folders`** - Folder organization
-- **`client.prompts`** - AI prompt management
+session.on('data', (data) => {
+  console.log(data.text, end='', flush=true);
+});
 
-## Usage Examples
+session.on('complete', () => {
+  console.log('\nDone!');
+  console.log(`Chat ID: ${session.chatId}`);
+  console.log(`Message ID: ${session.messageId}`);
+});
+```
 
-### Real-time Streaming Chat
+### Streaming with Event Types
 
 ```typescript
-// Start a streaming conversation
 const session = await client.streaming.sendToAgent('Hello', 'agent-id');
 
-// Listen for different types of events
 session.on('status', (data) => {
-  console.log('Connection status:', data.status);
+  console.log('Status:', data.status);
 });
 
 session.on('progress', (data) => {
-  console.log('Agent processing:', data.processing_status);
+  console.log('Progress:', data.processing_status);
 });
 
 session.on('data', (data) => {
-  console.log('Agent response:', data.text);
+  console.log('Response:', data.text);
 });
 
 session.on('complete', (data) => {
-  console.log('Final response:', data);
+  console.log('Complete:', data);
 });
 
 session.on('error', (error) => {
-  console.error('Streaming error:', error);
+  console.error('Error:', error);
 });
 ```
 
-### Advanced Streaming with Progress Tracking (NEW in v0.2.0!)
-
-The SDK now supports comprehensive event tracking similar to the CLI's `--show-progress` flag:
+### Streaming with Progress Tracking
 
 ```typescript
 // Enable ALL SSE events tracking
 const session = await client.streaming.sendToAgent('Explain AI', 'agent-id', {
-  showProgress: true // Enables raw SSE event emission
+  showProgress: true
 });
 
-// Standard events (still available)
+// Standard events
 session.on('data', (data) => {
   console.log('Agent text:', data.text);
 });
 
-session.on('status', (data) => {
-  console.log('Status:', data.status);
-});
-
 // NEW: Raw SSE events (when showProgress=true)
 session.on('sse_event', (data) => {
   console.log('Raw SSE event:', data);
   // This gives you access to ALL events from the streaming endpoint
-  // Useful for debugging, analytics, or building custom progress indicators
 });
 ```
 
-**Event Types:**
-- `'status'`: Connection status updates ('connected', 'complete')
-- `'progress'`: Agent processing status updates
-- `'data'`: Streaming response text chunks  
-- `'complete'`: Final response with metadata
-- `'error'`: Error events
-- `'chat_created'`: Chat creation events with chat ID
-- `'sse_event'`: All raw SSE events (when `showProgress=true`)
-
-**When to use `showProgress`:**
-- **Debugging**: See exactly what events the SSE endpoint sends
-- **Analytics**: Track detailed agent processing metrics
-- **Custom UI**: Build advanced progress indicators
-- **Monitoring**: Monitor all agent processing stages
+### Continue a Conversation
 
 ```typescript
-// Example: Custom progress tracking
-const session = await client.streaming.sendToAgent('Complex query', 'agent-id', {
-  showProgress: true
-});
+// First message creates a new chat
+const session1 = await client.streaming.sendToAgent('Hello', 'agent-id');
 
-let eventCount = 0;
-const eventTypes = new Set();
-
-session.on('sse_event', (data) => {
-  eventCount++;
-  eventTypes.add(data.type || data.status || 'unknown');
-  
-  console.log(`Event #${eventCount}: ${JSON.stringify(data)}`);
+session1.on('data', (data) => {
+  console.log(data.text, end='');
 });
 
-session.on('complete', () => {
-  console.log(`Total events: ${eventCount}`);
-  console.log(`Event types seen: ${Array.from(eventTypes).join(', ')}`);
+session1.on('complete', () => {
+  // Continue in the same chat
+  const session2 = await client.streaming.sendToAgent(
+    'Tell me more',
+    'agent-id',
+    { chatId: session1.chatId }  // Use the chat ID from first session
+  );
+
+  session2.on('data', (data) => {
+    console.log(data.text, end='');
+  });
 });
 ```
 
-### Document Management
+### Streaming with Attachments
 
 ```typescript
-// Upload a document
-const uploadResult = await client.documents.upload('/path/to/file.pdf', {
-  onProgress: (percent, loaded, total) => {
-    console.log(`Upload progress: ${percent}%`);
-  }
-});
-
-// Create a document from URL
-const document = await client.documents.createFromPath(
-  'https://example.com/policy.pdf',
-  'user-123',
+const session = await client.streaming.sendToAgent(
+  'What\'s in this image?',
+  'agent-id',
   {
-    title: 'Company Policy',
-    folderId: 'folder-id'
+    attachments: {
+      images: ['https://example.com/image.jpg']
+    }
   }
 );
 
-// Search documents semantically
-const searchResults = await client.documents.search('company policy', {
-  topK: 5
+session.on('data', (data) => {
+  console.log(data.text, end='');
 });
+```
 
-// Download a file
-await client.documents.download(
-  'filename.pdf',
-  '/local/path/file.pdf',
-  {
-    onProgress: (percent, loaded, total) => {
-      console.log(`Download progress: ${percent}%`);
-    }
+## Error Handling
+
+```typescript
+import { ToothFairyError } from '@toothfairyai/sdk';
+
+const client = new ToothFairyClient({
+  apiKey: '...',
+  workspaceId: '...'
+});
+
+try {
+  const response = await client.chat.sendToAgent('Hello', 'agent-id');
+} catch (error) {
+  if (error instanceof ToothFairyError) {
+    console.error('Error:', error.message);
+    console.error('Code:', error.code);
+    console.error('Status:', error.statusCode);
+    console.error('Response:', error.response);
+  } else {
+    console.error('Unknown error:', error);
   }
-);
+}
 ```
 
-### Chat Management
+### Specific Error Types
 
 ```typescript
-// Create a new chat
-const chat = await client.chat.create({
-  name: 'Customer Support Chat',
-  primaryRole: 'agent-id',
-  customerId: 'customer-123',
-  externalParticipantId: '+1234567890',
-  channelSettings: {
-    sms: {
-      isEnabled: true,
-      recipient: '+1234567890',
-      providerID: 'twilio'
-    }
+import {
+  ToothFairyError
+} from '@toothfairyai/sdk';
+
+try {
+  const client = new ToothFairyClient({
+    apiKey: '',
+    workspaceId: ''
+  });
+} catch (error) {
+  if (error instanceof ToothFairyError) {
+    console.error('Error:', error.message);
+    console.error('Code:', error.code);
   }
-});
+}
 
-// Send a message in the chat
-const message = await client.chat.createMessage({
-  chatID: chat.id,
-  text: 'I need help with my order',
-  role: 'user',
-  userID: 'customer-123'
+try {
+  const result = await client.documents.upload('large_file.pdf');
+} catch (error) {
+  if (error instanceof ToothFairyError) {
+    console.error('Error:', error.message);
+    console.error('Status:', error.statusCode);
+  }
+}
+```
+
+## Connection Testing
+
+```typescript
+// Test connection
+const isConnected = await client.testConnection();
+console.log(`Connected: ${isConnected}`);
+
+// Get health status
+const health = await client.getHealth();
+console.log(`Status: ${health.status}`);
+```
+
+## Best Practices
+
+### 1. Use Environment Variables for Credentials
+
+```typescript
+import { ToothFairyClient } from '@toothfairyai/sdk';
+
+const client = new ToothFairyClient({
+  apiKey: process.env.TOOTHPAIRY_API_KEY!,
+  workspaceId: process.env.TOOTHPAIRY_WORKSPACE_ID!
 });
+```
 
-// Get agent response (non-streaming)
-const response = await client.chat.sendToAgent(
-  'Hello, I need help',
-  'agent-id',
-  {
-    phoneNumber: '+1234567890',
-    customerId: 'customer-123',
-    customerInfo: {
-      name: 'John Doe',
-      email: 'john@example.com'
+### 2. Handle Pagination
+
+```typescript
+async function getAllChats() {
+  const allChats: any[] = [];
+  let offset = 0;
+  const limit = 100;
+
+  while (true) {
+    const response = await client.chat.list(limit, offset);
+    allChats.push(...response.items);
+    
+    if (response.items.length < limit) {
+      break;
     }
+    
+    offset += limit;
   }
-);
+  
+  return allChats;
+}
 ```
 
-### Entity Management
+### 3. Use Streaming for Long Responses
 
 ```typescript
-// Create a topic entity
-const topic = await client.entities.create(
-  'user-123',
-  'Customer Support',
-  'topic',
-  {
-    description: 'Customer support related topics',
-    emoji: '🎧'
-  }
+// For long responses, use streaming to show progress
+const session = await client.streaming.sendToAgent(
+  'Generate a comprehensive report',
+  'agent-id'
 );
 
-// List all entities
-const entities = await client.entities.list();
+session.on('data', (data) => {
+  console.log(data.text, end='', flush=true);
+});
+```
 
-// Search entities
-const supportEntities = await client.entities.search('support');
+### 4. Implement Retry Logic
 
-// Get entities by type
-const topics = await client.entities.getByType('topic');
+```typescript
+async function sendWithRetry(
+  message: string,
+  agentId: string,
+  maxRetries = 3
+): Promise<any> {
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      return await client.chat.sendToAgent(message, agentId);
+    } catch (error) {
+      if (attempt < maxRetries - 1) {
+        const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
+        await new Promise(resolve => setTimeout(resolve, delay));
+      } else {
+        throw error;
+      }
+    }
+  }
+}
 ```
 
-### Folder Management
+### 5. Use Chat IDs for Conversations
 
 ```typescript
-// Create a folder
-const folder = await client.folders.create('user-123', 'Documents', {
-  description: 'Document collection',
-  emoji: '📁'
+// Create a chat once
+const chat = await client.chat.create({
+  name: 'Support Session',
+  primaryRole: 'agent-id'
+});
+
+// Use the same chat ID for all messages in the conversation
+const response1 = await client.chat.sendToAgent('Hello', 'agent-id', {
+  chatId: chat.id
+});
+const response2 = await client.chat.sendToAgent('Tell me more', 'agent-id', {
+  chatId: chat.id
 });
+```
+
+### 6. Organize Documents with Folders
 
-// Create a subfolder
-const subfolder = await client.folders.create('user-123', 'Contracts', {
-  parent: folder.id
+```typescript
+// Create folder structure
+const procedures = await client.folders.create('user-123', 'Procedures', {
+  description: 'Medical procedures documentation'
 });
 
-// Get folder hierarchy
-const folderTree = await client.folders.getTree();
+const policies = await client.folders.create('user-123', 'Policies', {
+  description: 'Company policies'
+});
 
-// Search folders
-const contractFolders = await client.folders.search('contract');
+// Upload documents to appropriate folders
+await client.documents.upload('procedure1.pdf', procedures.id);
+await client.documents.upload('policy1.pdf', policies.id);
 ```
 
-### Prompt Management
+### 7. Use Topics for Content Organization
 
 ```typescript
-// Create a prompt
-const prompt = await client.prompts.create('user-123', {
-  type: 'system',
-  label: 'Customer Service Prompt',
-  promptLength: 150,
-  interpolationString: 'You are a helpful customer service agent...',
-  scope: 'customer_support'
-});
+// Create topics
+const cleaningTopic = await client.entities.create(
+  'user-123',
+  'Dental Cleaning',
+  'topic',
+  {
+    description: 'Professional teeth cleaning procedures',
+    emoji: '🦷'
+  }
+);
+
+// Associate documents with topics
+const doc = await client.documents.createFromPath(
+  'cleaning_guide.pdf',
+  'user-123',
+  {
+    title: 'Cleaning Guide',
+    topics: [cleaningTopic.id]
+  }
+);
+```
 
-// Get prompts by type
-const systemPrompts = await client.prompts.getByType('system');
+### 8. Monitor Usage with Billing
 
-// Get prompts for a specific agent
-const agentPrompts = await client.prompts.getByAgent('agent-id');
+```typescript
+// Check monthly usage
+const costs = await client.billing.getMonthCosts();
+const apiCost = costs.apiUsage?.totalCostUSD || 0;
+const trainingCost = costs.trainingUsage?.totalCharge || 0;
+
+console.log(`API Cost: $${apiCost.toFixed(2)}`);
+console.log(`Training Cost: $${trainingCost.toFixed(2)}`);
+console.log(`Total: $${(apiCost + trainingCost).toFixed(2)}`);
+```
 
-// Clone a prompt with modifications
-const clonedPrompt = await client.prompts.clone('prompt-id', 'user-123', {
-  label: 'Modified Customer Service Prompt'
+### 9. Use Scheduled Jobs for Automation
+
+```typescript
+// Create a daily report job
+const job = await client.scheduledJobs.create({
+  id: 'daily-report',
+  name: 'Daily Summary Report',
+  agentID: 'report-agent-id',
+  schedule: {
+    frequency: 'DAILY',
+    hour: 9,
+    minute: 0
+  },
+  timezone: 'UTC',
+  isActive: true,
+  status: 'ACTIVE'
 });
 ```
 
-## Error Handling
-
-The SDK provides structured error handling:
+### 10. Secure Secrets Management
 
 ```typescript
-import { ToothFairyError } from '@toothfairyai/sdk';
+// Store sensitive data as secrets
+await client.secrets.create({
+  id: 'external-api-key',
+  name: 'External Service API Key',
+  description: 'API key for external service integration'
+});
 
-try {
-  const response = await client.chat.sendToAgent('Hello', 'invalid-agent');
-} catch (error) {
-  if (error instanceof ToothFairyError) {
-    console.error('API Error:', error.message);
-    console.error('Error Code:', error.code);
-    console.error('Status Code:', error.statusCode);
-    console.error('Response:', error.response);
-  } else {
-    console.error('Unknown error:', error);
-  }
-}
+// Reference secrets in agent functions
+await client.agentFunctions.create({
+  id: 'api-function',
+  name: 'External API Call',
+  url: 'https://api.example.com/data',
+  authorisationType: 'apikey',
+  // Use secret reference instead of hardcoding
+});
 ```
 
 ## Integration Examples
@@ -374,8 +1617,8 @@ import { ToothFairyClient } from '@toothfairyai/sdk';
 
 const app = express();
 const client = new ToothFairyClient({
-  apiKey: process.env.TOOTHFAIRY_API_KEY!,
-  workspaceId: process.env.TOOTHFAIRY_WORKSPACE_ID!
+  apiKey: process.env.TOOTHPAIRY_API_KEY!,
+  workspaceId: process.env.TOOTHPAIRY_WORKSPACE_ID!
 });
 
 app.post('/chat', async (req, res) => {
@@ -400,11 +1643,14 @@ import { NextApiRequest, NextApiResponse } from 'next';
 import { ToothFairyClient } from '@toothfairyai/sdk';
 
 const client = new ToothFairyClient({
-  apiKey: process.env.TOOTHFAIRY_API_KEY!,
-  workspaceId: process.env.TOOTHFAIRY_WORKSPACE_ID!
+  apiKey: process.env.TOOTHPAIRY_API_KEY!,
+  workspaceId: process.env.TOOTHPAIRY_WORKSPACE_ID!
 });
 
-export default async function handler(req: NextApiRequest, res: NextApiResponse) {
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
   const { message, agentId } = req.body;
   
   try {
@@ -430,7 +1676,7 @@ const client = new ToothFairyClient({
 function ChatComponent() {
   const [messages, setMessages] = useState<string[]>([]);
   const [currentResponse, setCurrentResponse] = useState('');
-
+  
   const sendMessage = async (message: string) => {
     const session = await client.streaming.sendToAgent(message, 'agent-id');
     
@@ -453,18 +1699,6 @@ function ChatComponent() {
 }
 ```
 
-## Comparison with CLI
-
-| Feature | SDK (`@toothfairyai/sdk`) | CLI (`@toothfairyai/cli`) |
-|---------|---------------------------|---------------------------|
-| **Purpose** | Programmatic integration in applications | Interactive command-line operations |
-| **Usage** | `import { ToothFairyClient } from '@toothfairyai/sdk'` | `toothfairy stream "message" --agent-id xyz` |
-| **Dependencies** | Minimal (axios only) | CLI tools (commander, chalk, ora) |
-| **TypeScript** | TypeScript-first with comprehensive types | Basic TypeScript support |
-| **Streaming** | EventEmitter-based real-time events | Callback-based streaming |
-| **Error Handling** | Structured error classes | CLI-friendly error messages |
-| **Use Cases** | Web apps, servers, integrations | Testing, debugging, CI/CD |
-
 ## Development
 
 ### Building
@@ -476,7 +1710,14 @@ npm run build
 ### Testing
 
 ```bash
+# Run unit tests
 npm test
+
+# Run integration tests (requires API credentials)
+TF_API_KEY=your-api-key \
+TF_WORKSPACE_ID=your-workspace-id \
+TF_AGENT_ID=your-agent-id \
+npx ts-node tests/integration/test-streaming.ts
 ```
 
 ### Linting