@antipopp/agno-client 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 antipopp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,294 @@
+# @antipopp/agno-client
+
+Core stateful client library for Agno agents with streaming support.
+
+## Installation
+
+```bash
+npm install @antipopp/agno-client
+```
+
+## Features
+
+- ✅ **Stateful Management** - Manages messages, sessions, and configuration
+- ✅ **Event-Driven** - Subscribe to real-time updates via EventEmitter
+- ✅ **Streaming Support** - Real-time streaming of agent responses
+- ✅ **Session Management** - Load and manage conversation sessions
+- ✅ **Type-Safe** - Full TypeScript support with comprehensive types
+- ✅ **Framework Agnostic** - Works with any JavaScript/TypeScript project
+
+## Quick Start
+
+```typescript
+import { AgnoClient } from '@antipopp/agno-client';
+
+// Create a client instance
+const client = new AgnoClient({
+  endpoint: 'http://localhost:7777',
+  mode: 'agent',
+  agentId: 'your-agent-id',
+  authToken: 'optional-auth-token',
+});
+
+// Listen to message updates
+client.on('message:update', (messages) => {
+  console.log('New messages:', messages);
+});
+
+// Listen to errors
+client.on('message:error', (error) => {
+  console.error('Error:', error);
+});
+
+// Send a message
+await client.sendMessage('Hello, agent!');
+
+// Get current messages
+const messages = client.getMessages();
+
+// Clear chat
+client.clearMessages();
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new AgnoClient(config: AgnoClientConfig)
+```
+
+**Config Options:**
+- `endpoint` (string, required) - Base endpoint URL
+- `authToken` (string, optional) - Authentication token
+- `mode` ('agent' | 'team', optional) - Operation mode (default: 'agent')
+- `agentId` (string, optional) - Agent ID (required if mode is 'agent')
+- `teamId` (string, optional) - Team ID (required if mode is 'team')
+- `dbId` (string, optional) - Database ID
+- `sessionId` (string, optional) - Current session ID
+
+### Methods
+
+#### `sendMessage(message, options?)`
+
+Send a message to the agent/team.
+
+```typescript
+await client.sendMessage('Hello!');
+
+// With FormData (for file uploads)
+const formData = new FormData();
+formData.append('message', 'Hello!');
+formData.append('file', fileBlob);
+await client.sendMessage(formData);
+
+// With custom headers
+await client.sendMessage('Hello!', {
+  headers: { 'X-Custom-Header': 'value' }
+});
+```
+
+#### `getMessages()`
+
+Get current messages.
+
+```typescript
+const messages: ChatMessage[] = client.getMessages();
+```
+
+#### `clearMessages()`
+
+Clear all messages and reset session.
+
+```typescript
+client.clearMessages();
+```
+
+#### `loadSession(sessionId)`
+
+Load a specific session.
+
+```typescript
+const messages = await client.loadSession('session-id');
+```
+
+#### `fetchSessions()`
+
+Fetch all sessions for current agent/team.
+
+```typescript
+const sessions = await client.fetchSessions();
+```
+
+#### `initialize()`
+
+Initialize client (check status and fetch agents/teams).
+
+```typescript
+const { agents, teams } = await client.initialize();
+```
+
+#### `updateConfig(updates)`
+
+Update client configuration.
+
+```typescript
+client.updateConfig({
+  agentId: 'new-agent-id',
+  authToken: 'new-token',
+});
+```
+
+### Events
+
+Subscribe to events using `client.on(event, handler)`:
+
+- `message:update` - Emitted when messages are updated during streaming
+- `message:complete` - Emitted when a message stream completes
+- `message:error` - Emitted when an error occurs
+- `session:loaded` - Emitted when a session is loaded
+- `session:created` - Emitted when a new session is created
+- `stream:start` - Emitted when streaming starts
+- `stream:end` - Emitted when streaming ends
+- `state:change` - Emitted when client state changes
+- `config:change` - Emitted when configuration changes
+
+```typescript
+// Subscribe to events
+client.on('message:update', (messages) => {
+  console.log('Messages:', messages);
+});
+
+// Unsubscribe from events
+const handler = (messages) => console.log(messages);
+client.on('message:update', handler);
+client.off('message:update', handler);
+```
+
+## Utilities
+
+### Logger
+
+The package includes a secure Logger utility for production-safe debugging:
+
+```typescript
+import { Logger } from '@antipopp/agno-client';
+
+// Debug and info messages only log in development mode
+Logger.debug('Debug message', { someData: 'value' });
+Logger.info('Client initialized', { endpoint: 'http://localhost:7777' });
+
+// Warnings and errors always log
+Logger.warn('Connection issue detected');
+Logger.error('Failed to send message', error);
+
+// Sensitive data is automatically sanitized
+Logger.debug('Config loaded', {
+  endpoint: 'http://localhost:7777',
+  authToken: 'secret-token'  // Will be logged as [REDACTED]
+});
+```
+
+**Features:**
+- **Automatic sanitization** - Sensitive fields (authToken, Authorization, token, password, apiKey) are automatically redacted
+- **Environment-aware** - Debug/info logs only appear in development mode (NODE_ENV === 'development')
+- **Always-on errors** - Warnings and errors always log, even in production
+- **Production-safe** - Prevents accidental exposure of secrets in production logs
+
+**Sanitized Fields:**
+- `authToken`, `Authorization`, `token`, `password`, `apiKey` and any field containing these words (case-insensitive)
+
+## Advanced Usage
+
+### Session Management
+
+```typescript
+// Fetch all sessions
+const sessions = await client.fetchSessions();
+
+// Load a specific session
+const messages = await client.loadSession(sessions[0].session_id);
+
+// Current session ID
+const sessionId = client.getConfig().sessionId;
+```
+
+### State Management
+
+```typescript
+// Get current state
+const state = client.getState();
+console.log(state.isStreaming);
+console.log(state.isEndpointActive);
+console.log(state.agents);
+console.log(state.teams);
+```
+
+### Error Handling
+
+```typescript
+client.on('message:error', (error) => {
+  console.error('Streaming error:', error);
+});
+
+try {
+  await client.sendMessage('Hello!');
+} catch (error) {
+  console.error('Failed to send:', error);
+}
+```
+
+### Request Cancellation
+
+Use `AbortController` to cancel ongoing requests. This is essential for preventing memory leaks when components unmount or users navigate away during streaming:
+
+```typescript
+const controller = new AbortController();
+
+// Pass signal to sendMessage options
+await client.sendMessage('Hello!', {
+  signal: controller.signal
+});
+
+// Cancel the request (e.g., on component unmount)
+controller.abort();
+```
+
+**React Example:**
+
+```typescript
+import { useEffect } from 'react';
+import { AgnoClient } from '@antipopp/agno-client';
+
+function ChatComponent() {
+  const client = new AgnoClient(config);
+
+  useEffect(() => {
+    const controller = new AbortController();
+
+    // Send message with abort signal
+    client.sendMessage('Hello!', {
+      signal: controller.signal
+    });
+
+    // Cleanup: cancel request on unmount
+    return () => {
+      controller.abort();
+    };
+  }, []);
+
+  return <div>Chat</div>;
+}
+```
+
+**Use Cases:**
+- **Component unmounting** - Cancel requests when user navigates away
+- **Request timeouts** - Implement custom timeout logic
+- **User cancellation** - Allow users to cancel long-running requests
+- **Preventing memory leaks** - Ensure streaming stops when components are destroyed
+
+**Note:** Aborted requests will not trigger the `onError` callback - they complete silently.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,120 @@
+import EventEmitter from 'eventemitter3';
+import { AgnoClientConfig, ChatMessage, ClientState, SessionEntry, ToolCall, AgentDetails, TeamDetails } from '@antipopp/agno-types';
+export { AgentDetails, AgnoClientConfig, AudioData, ChatMessage, ClientState, ImageData, MessageExtraData, ResponseAudioData, RunEvent, RunResponse, RunResponseContent, SessionEntry, TeamDetails, ToolCall, VideoData } from '@antipopp/agno-types';
+
+/**
+ * Main Agno client class
+ * Provides stateful management of agent/team interactions with streaming support
+ */
+declare class AgnoClient extends EventEmitter {
+    private messageStore;
+    private configManager;
+    private sessionManager;
+    private eventProcessor;
+    private state;
+    constructor(config: AgnoClientConfig);
+    /**
+     * Get current messages
+     */
+    getMessages(): ChatMessage[];
+    /**
+     * Get current configuration
+     */
+    getConfig(): AgnoClientConfig;
+    /**
+     * Get current state
+     */
+    getState(): ClientState;
+    /**
+     * Update configuration
+     */
+    updateConfig(updates: Partial<AgnoClientConfig>): void;
+    /**
+     * Clear all messages
+     */
+    clearMessages(): void;
+    /**
+     * Send a message to the agent/team (streaming)
+     */
+    sendMessage(message: string | FormData, options?: {
+        headers?: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * Handle streaming chunk
+     */
+    private handleChunk;
+    /**
+     * Handle error
+     */
+    private handleError;
+    /**
+     * Load a session
+     */
+    loadSession(sessionId: string): Promise<ChatMessage[]>;
+    /**
+     * Fetch all sessions
+     */
+    fetchSessions(): Promise<SessionEntry[]>;
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Delete a team session
+     */
+    deleteTeamSession(teamId: string, sessionId: string): Promise<void>;
+    /**
+     * Continue a paused run after executing external tools
+     */
+    continueRun(tools: ToolCall[], options?: {
+        headers?: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * Check endpoint status
+     */
+    checkStatus(): Promise<boolean>;
+    /**
+     * Fetch agents from endpoint
+     */
+    fetchAgents(): Promise<AgentDetails[]>;
+    /**
+     * Fetch teams from endpoint
+     */
+    fetchTeams(): Promise<TeamDetails[]>;
+    /**
+     * Initialize client (check status and fetch agents/teams)
+     * Automatically selects the first available agent or team if none is configured
+     */
+    initialize(): Promise<{
+        agents: AgentDetails[];
+        teams: TeamDetails[];
+    }>;
+}
+
+/**
+ * Logger utility with sensitive data sanitization
+ * Only logs in development mode to prevent auth token exposure
+ */
+/**
+ * Logger class with sanitization and environment-aware logging
+ */
+declare class Logger {
+    /**
+     * Log debug information (only in development)
+     */
+    static debug(message: string, data?: unknown): void;
+    /**
+     * Log informational messages (only in development)
+     */
+    static info(message: string, data?: unknown): void;
+    /**
+     * Log warnings (always logs)
+     */
+    static warn(message: string, data?: unknown): void;
+    /**
+     * Log errors (always logs)
+     */
+    static error(message: string, data?: unknown): void;
+}
+
+export { AgnoClient, Logger };

package/dist/index.d.ts

@@ -0,0 +1,120 @@
+import EventEmitter from 'eventemitter3';
+import { AgnoClientConfig, ChatMessage, ClientState, SessionEntry, ToolCall, AgentDetails, TeamDetails } from '@antipopp/agno-types';
+export { AgentDetails, AgnoClientConfig, AudioData, ChatMessage, ClientState, ImageData, MessageExtraData, ResponseAudioData, RunEvent, RunResponse, RunResponseContent, SessionEntry, TeamDetails, ToolCall, VideoData } from '@antipopp/agno-types';
+
+/**
+ * Main Agno client class
+ * Provides stateful management of agent/team interactions with streaming support
+ */
+declare class AgnoClient extends EventEmitter {
+    private messageStore;
+    private configManager;
+    private sessionManager;
+    private eventProcessor;
+    private state;
+    constructor(config: AgnoClientConfig);
+    /**
+     * Get current messages
+     */
+    getMessages(): ChatMessage[];
+    /**
+     * Get current configuration
+     */
+    getConfig(): AgnoClientConfig;
+    /**
+     * Get current state
+     */
+    getState(): ClientState;
+    /**
+     * Update configuration
+     */
+    updateConfig(updates: Partial<AgnoClientConfig>): void;
+    /**
+     * Clear all messages
+     */
+    clearMessages(): void;
+    /**
+     * Send a message to the agent/team (streaming)
+     */
+    sendMessage(message: string | FormData, options?: {
+        headers?: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * Handle streaming chunk
+     */
+    private handleChunk;
+    /**
+     * Handle error
+     */
+    private handleError;
+    /**
+     * Load a session
+     */
+    loadSession(sessionId: string): Promise<ChatMessage[]>;
+    /**
+     * Fetch all sessions
+     */
+    fetchSessions(): Promise<SessionEntry[]>;
+    /**
+     * Delete a session
+     */
+    deleteSession(sessionId: string): Promise<void>;
+    /**
+     * Delete a team session
+     */
+    deleteTeamSession(teamId: string, sessionId: string): Promise<void>;
+    /**
+     * Continue a paused run after executing external tools
+     */
+    continueRun(tools: ToolCall[], options?: {
+        headers?: Record<string, string>;
+    }): Promise<void>;
+    /**
+     * Check endpoint status
+     */
+    checkStatus(): Promise<boolean>;
+    /**
+     * Fetch agents from endpoint
+     */
+    fetchAgents(): Promise<AgentDetails[]>;
+    /**
+     * Fetch teams from endpoint
+     */
+    fetchTeams(): Promise<TeamDetails[]>;
+    /**
+     * Initialize client (check status and fetch agents/teams)
+     * Automatically selects the first available agent or team if none is configured
+     */
+    initialize(): Promise<{
+        agents: AgentDetails[];
+        teams: TeamDetails[];
+    }>;
+}
+
+/**
+ * Logger utility with sensitive data sanitization
+ * Only logs in development mode to prevent auth token exposure
+ */
+/**
+ * Logger class with sanitization and environment-aware logging
+ */
+declare class Logger {
+    /**
+     * Log debug information (only in development)
+     */
+    static debug(message: string, data?: unknown): void;
+    /**
+     * Log informational messages (only in development)
+     */
+    static info(message: string, data?: unknown): void;
+    /**
+     * Log warnings (always logs)
+     */
+    static warn(message: string, data?: unknown): void;
+    /**
+     * Log errors (always logs)
+     */
+    static error(message: string, data?: unknown): void;
+}
+
+export { AgnoClient, Logger };