convo-ai-sdk 1.0.0

package/README.md

@@ -0,0 +1,114 @@
+# convo-ai-sdk
+
+This SDK provides a client for interacting with the Convo AI chat service, enabling real-time conversational AI experiences in your applications.
+
+## Installation
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+## Usage
+
+### Initialization
+
+First, import the `ChatClient` and initialize it with your `ClientOptions`. You can provide either an `apiKey` for production or a `testAgentId` for development.
+
+```typescript
+import { ChatClient } from './src/index'; // Adjust path as needed
+
+const chatClient = new ChatClient({
+  apiKey: 'YOUR_API_KEY', // Or testAgentId: 'YOUR_TEST_AGENT_ID'
+  identifier: 'user-123', // Optional: A unique identifier for the user
+  dynamicVariables: {
+    userName: 'John Doe',
+    // ... other dynamic variables
+  }
+});
+```
+
+### Connecting to the Chat Service
+
+Connect to the chat service. If you have an existing `sessionToken`, you can pass it to `connect` to resume a conversation.
+
+```typescript
+await chatClient.connect();
+// Or to resume a session:
+// await chatClient.connect('YOUR_SESSION_TOKEN');
+```
+
+### Sending Messages
+
+Send messages to the chat service using the `sendMessage` method.
+
+```typescript
+await chatClient.sendMessage('Hello, how are you?');
+```
+
+### Handling Events
+
+The `ChatClient` emits various events that you can listen to:
+
+- `statusChange`: Notifies when the connection status changes (`disconnected`, `connecting`, `connected`, `error`).
+- `message`: Emitted for every new message (user, assistant, system, tool).
+- `messageStart`: When a new assistant message starts streaming.
+- `messageData`: For streaming chunks of assistant message content.
+- `messageDone`: When an assistant message has finished streaming.
+- `toolCall`: When the assistant requests a tool to be called.
+- `thought`: When the assistant provides a thought process.
+- `historyLoaded`: When conversation history is loaded.
+- `configLoaded`: When chat configuration is loaded.
+- `reset`: When the chat is reset.
+
+```typescript
+chatClient.on('statusChange', (status) => {
+  console.log('Connection status:', status);
+});
+
+chatClient.on('message', (message) => {
+  console.log('New message:', message);
+});
+
+chatClient.on('messageData', (chunk) => {
+  process.stdout.write(chunk); // For streaming output
+});
+
+chatClient.on('toolCall', (toolCall) => {
+  console.log('Tool call requested:', toolCall);
+  // Implement logic to execute the tool and send the result
+  // chatClient.sendToolResult(toolCall.id, toolCall.name, 'Tool execution result');
+});
+```
+
+### Sending Tool Results
+
+If the AI requests a tool call, you can execute the tool and send its result back to the chat service using `sendToolResult`.
+
+```typescript
+// Example of handling a tool call
+chatClient.on('toolCall', async (toolCall) => {
+  console.log('Tool call requested:', toolCall);
+  // Simulate tool execution
+  const toolResult = `Executed tool ${toolCall.name} with args ${JSON.stringify(toolCall.args)}`;
+  await chatClient.sendToolResult(toolCall.id, toolCall.name, toolResult);
+});
+```
+
+### Disconnecting and Resetting
+
+```typescript
+chatClient.disconnect();
+chatClient.resetChat(); // Disconnects, clears messages, and reconnects
+```
+
+## Building the SDK
+
+To build the TypeScript source files into JavaScript:
+
+```bash
+bun run build
+```
+
+This project was created using `bun init` in bun v1.2.16. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+import type { ConnectionStatus, ChatMessage, ChatConfig, ClientOptions, ChatEvent } from './types';
+export declare class ChatClient {
+    private options;
+    private listeners;
+    status: ConnectionStatus;
+    messages: ChatMessage[];
+    config: Partial<ChatConfig>;
+    constructor(options: ClientOptions);
+    private _emit;
+    private _setStatus;
+    private _addMessage;
+    private _loadGreeting;
+    private _loadHistory;
+    on<T>(event: ChatEvent, callback: (data: T) => void): void;
+    connect(sessionToken?: string): Promise<void>;
+    sendToolResult(toolCallId: string, toolCallName: any, result: any): Promise<void>;
+    sendMessage(text: string): Promise<void>;
+    sendStreamMessage(message: ChatMessage): Promise<void>;
+    disconnect(): void;
+    resetChat(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,298 @@
+const DEFAULT_HTTP_ENDPOINT = 'https://wzy5woofwf.execute-api.eu-west-1.amazonaws.com/Prod';
+export class ChatClient {
+    options;
+    listeners = {};
+    status = 'disconnected';
+    messages = [];
+    config = {};
+    constructor(options) {
+        this.options = {
+            apiKey: options.apiKey || '',
+            testAgentId: options.testAgentId || '',
+            identifier: options.identifier || '',
+            dynamicVariables: options.dynamicVariables || {},
+            httpApiEndpoint: options.httpApiEndpoint || DEFAULT_HTTP_ENDPOINT
+        };
+    }
+    _emit(event, data) {
+        if (this.listeners[event]) {
+            this.listeners[event]?.forEach(callback => callback(data));
+        }
+    }
+    _setStatus(newStatus) {
+        this.status = newStatus;
+        this._emit('statusChange', this.status);
+    }
+    _addMessage(message) {
+        this.messages.push(message);
+    }
+    async _loadGreeting(wlcMsg, emit = true) {
+        if (wlcMsg) {
+            const welcomeMessage = {
+                id: 'system-welcome',
+                data: { content: wlcMsg },
+                from: 'system',
+                timestamp: Date.now(),
+            };
+            this._addMessage(welcomeMessage);
+            if (emit) {
+                this._emit('message', welcomeMessage);
+            }
+        }
+    }
+    async _loadHistory(conversationId, sessionToken) {
+        try {
+            const response = await fetch(`${this.options.httpApiEndpoint}/conversations/${conversationId}/history`, {
+                method: 'GET',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${sessionToken}`
+                },
+            });
+            if (response.status === 403) {
+                this.resetChat();
+                console.warn('Chat SDK Warning: Access forbidden, resetting chat.');
+                return;
+            }
+            if (!response.ok) {
+                console.error('Chat SDK Error: Failed to fetch history, status:', response.status);
+                throw new Error('Failed to fetch history');
+            }
+            const history = await response.json();
+            history.forEach((msg) => {
+                const chatMessage = {
+                    id: msg.messageId,
+                    data: msg.data,
+                    from: msg.senderType,
+                    timestamp: msg.timestamp,
+                };
+                this._addMessage(chatMessage);
+            });
+            this._emit('historyLoaded', this.messages);
+        }
+        catch (error) {
+            console.error('Chat SDK Error:', error);
+            this._setStatus('disconnected');
+        }
+    }
+    on(event, callback) {
+        if (!this.listeners[event]) {
+            this.listeners[event] = [];
+        }
+        this.listeners[event]?.push(callback);
+    }
+    async connect(sessionToken) {
+        if (this.status === 'connected' || this.status === 'connecting') {
+            return;
+        }
+        this._setStatus('connecting');
+        let sessionInitiated = false;
+        if (sessionToken) {
+            // we need to decode the session token and extract the necessary information
+            try {
+                const decodedToken = JSON.parse(atob(sessionToken.split('.')[1]));
+                this.config = {
+                    sessionToken,
+                    conversationId: decodedToken.conversationId,
+                    streamApiEndpoint: decodedToken.streamApiEndpoint,
+                    agentSettings: decodedToken.agentSettings || {},
+                };
+                if (!this.config.streamApiEndpoint) {
+                    console.error('Chat SDK Error: Stream API endpoint not available in session token.');
+                    this._setStatus('error');
+                    return;
+                }
+            }
+            catch (error) {
+                console.error('Chat SDK Error: Invalid session token format.', error);
+                this._setStatus('error');
+                return;
+            }
+            sessionInitiated = false;
+        }
+        else {
+            try {
+                const headers = {
+                    'Content-Type': 'application/json',
+                    'x-identifier': this.options.identifier || '',
+                };
+                if (this.options.testAgentId) {
+                    headers['x-test-agent-id'] = this.options.testAgentId;
+                }
+                else {
+                    headers['x-api-key'] = this.options.apiKey;
+                }
+                const response = await fetch(`${this.options.httpApiEndpoint}/session/initiate`, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify({
+                        dynamicVariables: this.options.dynamicVariables,
+                    }),
+                });
+                if (!response.ok)
+                    throw new Error('Failed to initiate session or fetch config');
+                const responseData = await response.json();
+                sessionToken = responseData.sessionToken;
+                this.config = {
+                    sessionToken,
+                    conversationId: responseData.conversationId,
+                    streamApiEndpoint: responseData.streamApiEndpoint,
+                    agentSettings: responseData.agentSettings,
+                };
+            }
+            catch (error) {
+                console.error('Chat SDK Error:', error);
+                this._setStatus('error');
+                return;
+            }
+            sessionInitiated = true;
+        }
+        this._emit('configLoaded', this.config);
+        const agentSettings = this.config.agentSettings || {};
+        const conversationId = this.config.conversationId || '';
+        if (!this.config.streamApiEndpoint) {
+            console.error('Chat SDK Error: Stream API endpoint not available.');
+            this._setStatus('error');
+            return;
+        }
+        if (agentSettings?.config?.showGreeting !== false) {
+            const welcomeMsg = agentSettings?.config?.greetingMessage || null;
+            if (welcomeMsg) {
+                await this._loadGreeting(welcomeMsg, !(sessionToken && conversationId && !sessionInitiated));
+            }
+        }
+        if (sessionToken && conversationId && !sessionInitiated) {
+            await this._loadHistory(conversationId, sessionToken);
+        }
+        this._setStatus('connected');
+    }
+    async sendToolResult(toolCallId, toolCallName, result) {
+        if (this.status !== 'connected') {
+            console.error('Cannot send tool result, not connected.');
+            return;
+        }
+        const toolMessage = {
+            id: `tool-${Date.now()}`,
+            data: { toolCallId: toolCallId, toolCallName: toolCallName, content: result },
+            from: 'tool',
+            timestamp: Date.now(),
+        };
+        // this._addMessage(toolMessage);
+        // this._emit('message', toolMessage);
+        await this.sendStreamMessage(toolMessage);
+    }
+    async sendMessage(text) {
+        if (this.status !== 'connected') {
+            console.error('Cannot send message, not connected.');
+            return;
+        }
+        const userMessage = {
+            id: `local-${Date.now()}`,
+            data: { content: text },
+            from: 'user',
+            timestamp: Date.now(),
+        };
+        this._addMessage(userMessage);
+        this._emit('message', userMessage);
+        await this.sendStreamMessage(userMessage);
+    }
+    async sendStreamMessage(message) {
+        if (this.status !== 'connected') {
+            console.error('Cannot send stream message, not connected.');
+            return;
+        }
+        let input = {
+            type: message.from,
+            content: message.data.content || '',
+        };
+        if (message.from === 'tool') {
+            input.toolCallId = message.data.toolCallId;
+            input.toolName = message.data.toolCallName;
+        }
+        const response = await fetch(this.config.streamApiEndpoint + 'conversation', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${this.config.sessionToken}`,
+                'Accept': 'text/event-stream'
+            },
+            body: JSON.stringify(input)
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error! status: ${response.status}`);
+        }
+        if (!response.body) {
+            throw new Error('Response body is null');
+        }
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder('utf-8');
+        let buffer = '';
+        let currentMessage = null;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            buffer += decoder.decode(value, { stream: true });
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || '';
+            for (const line of lines) {
+                try {
+                    if (line.startsWith('thought: ')) {
+                        const data = JSON.parse(line.substring(9));
+                        this._emit('thought', data);
+                    }
+                    else if (line.startsWith('start: ')) {
+                        if (currentMessage) {
+                            this._addMessage(currentMessage);
+                            this._emit('messageDone', currentMessage);
+                        }
+                        const data = JSON.parse(line.substring(7));
+                        currentMessage = {
+                            id: data.messageId,
+                            data: { content: '' },
+                            from: 'assistant',
+                            timestamp: data.timestamp || Date.now(),
+                        };
+                        this._emit('messageStart', currentMessage);
+                    }
+                    else if (line.startsWith('data: ') && currentMessage) {
+                        const data = JSON.parse(line.substring(6));
+                        currentMessage.data.content += data.p;
+                        if (data.p) {
+                            this._emit('messageData', data.p);
+                        }
+                    }
+                    else if (line.startsWith('tool_call: ')) {
+                        const data = JSON.parse(line.substring(11));
+                        this._emit('toolCall', data);
+                    }
+                    else if (line.startsWith('error: ')) {
+                        const error = JSON.parse(line.substring(7));
+                        this._emit('messageError', error);
+                        currentMessage = null;
+                        break;
+                    }
+                    else if (line.startsWith('done') && currentMessage) {
+                        this._addMessage(currentMessage);
+                        this._emit('messageDone', currentMessage);
+                        currentMessage = null;
+                        break;
+                    }
+                }
+                catch (e) {
+                    console.warn('Could not parse event data as JSON:', line);
+                }
+            }
+        }
+    }
+    disconnect() {
+        this._setStatus('disconnected');
+    }
+    async resetChat() {
+        this.disconnect();
+        this.messages = [];
+        this._emit('reset', null);
+        await this.connect();
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'error';
+export interface ChatMessage {
+    id: string | number;
+    data: any;
+    from: 'user' | 'assistant' | 'system' | 'tool';
+    timestamp: number;
+}
+export interface ChatConfig {
+    conversationId: string;
+    sessionToken: string;
+    streamApiEndpoint: string;
+    agentSettings?: any;
+}
+export interface ClientOptions {
+    apiKey?: string;
+    testAgentId?: string;
+    httpApiEndpoint?: string;
+    identifier?: string;
+    dynamicVariables?: Record<string, any>;
+}
+export type ChatEvent = 'statusChange' | 'message' | 'configLoaded' | 'historyLoaded' | 'messageStart' | 'messageData' | 'messageDone' | 'messageError' | 'toolCall' | 'thought' | 'reset';

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "convo-ai-sdk",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "SDK for Convo AI",
+  "repository": {
+    "type": "git",
+    "url": "git@gitlab.dengun.org:convoai/convo-ai-sdk.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "n": "^10.2.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5.8.3"
+  }
+}