Chat SDK

A TypeScript SDK for interacting with the AI Content Creator chat system.

Installation

npm install @odin-ai/sdk

Authentication

The ChatSDK supports two authentication methods:

1. Access Token Authentication (Web App)

For web applications that already have user sessions:

import { ChatSDK } from '@odin-ai/sdk';

const chatSDK = new ChatSDK({
  baseUrl: 'https://api.example.com/',
  projectId: 'your-project-id',
  accessToken: 'your-access-token', // From user session
});

2. API Key Authentication (External SDK)

For external applications and server-to-server communication:

import { ChatSDK } from '@odin-ai/sdk';

const chatSDK = new ChatSDK({
  baseUrl: 'https://api.example.com/',
  projectId: 'your-project-id',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret',
});

Usage Examples

Creating a Chat

const chat = await chatSDK.createChat('My Chat', ['document-key-1']);
console.log('Created chat:', chat.chat_id);

Sending a Message

const response = await chatSDK.sendMessage('Hello!', {
  chatId: 'chat-id',
  agentType: 'chat_agent',
});
console.log('Response:', response);

Streaming Messages

await chatSDK.sendMessageStream('Tell me about...', {
  chatId: 'chat-id',
  onChunk: (chunk) => console.log('Chunk:', chunk),
  onComplete: (message) => console.log('Complete:', message),
  onError: (error) => console.error('Error:', error),
});

Listing Chats

const chats = await chatSDK.listChats();
console.log('Chats:', chats.chats);

Deleting a Chat

await chatSDK.deleteChat('chat-id');
console.log('Chat deleted');

Error Handling

The SDK throws errors for failed requests. Always wrap SDK calls in try-catch blocks:

try {
  const chat = await chatSDK.createChat('My Chat');
  // Handle success
} catch (error) {
  console.error('Failed to create chat:', error.message);
  // Handle error
}

TypeScript Support

The SDK is written in TypeScript and includes full type definitions for all methods and responses.

Features

• ✅ Authentication: X-API-KEY and X-API-SECRET headers
• ✅ Chat Management: Create, list, get, delete, rename chats
• ✅ Message Sending: Both simple and streaming responses
• ✅ File Support: Image and document uploads
• ✅ Pagination: Cursor-based pagination for chat listing
• ✅ TypeScript: Full type safety and IntelliSense support
• ✅ Error Handling: Comprehensive error handling
• ✅ Real-time: Streaming message responses
• ✅ Feedback: User feedback on AI responses

API Reference

Configuration

interface ChatSDKConfig {
  apiKey: string;        // X-API-KEY header
  apiSecret: string;     // X-API-SECRET header  
  baseUrl: string;       // API base URL
  projectId: string;     // Project ID for all operations
}

Chat Management

createChat(name?, documentKeys?)

Creates a new chat in the project.

const chat = await chatSDK.createChat('My Chat', ['doc1', 'doc2']);

listChats(cursor?, limit?)

Lists chats with pagination support.

const { chats, has_more, next_cursor } = await chatSDK.listChats();

getChatHistory(chatId)

Gets a specific chat with its message history.

const chatHistory = await chatSDK.getChatHistory('chat-id');

deleteChat(chatId)

Deletes a chat and all its messages.

await chatSDK.deleteChat('chat-id');

updateChatName(chatId, newName)

Updates the name of an existing chat.

await chatSDK.updateChatName('chat-id', 'New Chat Name');

Message Operations

sendMessage(message, options?)

Sends a message and returns the response.

const response = await chatSDK.sendMessage('Hello!', {
  chatId: 'chat-id',
  agentType: 'chat_agent',
  documentKeys: ['doc1'],
});

sendMessageStream(message, options?)

Sends a message with streaming response support.

await chatSDK.sendMessageStream('Tell me about AI', {
  chatId: 'chat-id',
  onChunk: (chunk) => {
    // Handle streaming text chunks
    console.log('Chunk:', chunk);
  },
  onMessageObject: (obj) => {
    // Handle structured message objects
    console.log('Message object:', obj);
  },
  onComplete: (message) => {
    // Handle completion
    console.log('Complete:', message);
  },
  onError: (error) => {
    // Handle errors
    console.error('Error:', error);
  },
});

Feedback

sendFeedback(messageId, chatId, feedback)

Sends user feedback (thumbs up/down) for a message.

await chatSDK.sendFeedback('message-id', 'chat-id', true); // thumbs up
await chatSDK.sendFeedback('message-id', 'chat-id', false); // thumbs down

Advanced Usage

File Uploads

const fileInput = document.getElementById('file') as HTMLInputElement;
const files = Array.from(fileInput.files || []);

await chatSDK.sendMessageStream('Analyze this image', {
  chatId: 'chat-id',
  images: files,
  onChunk: (chunk) => console.log(chunk),
});

Custom Agents

await chatSDK.sendMessage('Help me write code', {
  chatId: 'chat-id',
  agentType: 'chat_agent',
  agentId: 'custom-agent-id',
  modelName: 'gpt-4o',
});

Knowledge Base Integration

await chatSDK.sendMessage('What does our documentation say about X?', {
  chatId: 'chat-id',
  documentKeys: ['doc1', 'doc2', 'doc3'],
  useKnowledgebase: true,
});

Metadata

await chatSDK.sendMessage('Hello', {
  chatId: 'chat-id',
  metadata: {
    userId: 'user-123',
    sessionId: 'session-456',
    customField: 'value',
  },
});

Examples

See the /examples directory for complete working examples:

• basic-chat.ts - Simple chat implementation
• streaming-chat.ts - Real-time streaming chat
• file-upload.ts - Chat with file uploads
• react-integration.tsx - React component integration

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.