diff --git a/README.md b/README.md index e0d919e..2514c88 100644 --- a/README.md +++ b/README.md @@ -15,15 +15,15 @@ yarn add @base44/sdk ### Basic Setup ```javascript -import { createClient } from '@base44/sdk'; +import { createClient } from "@base44/sdk"; // Create a client instance const base44 = createClient({ - serverUrl: 'https://base44.app', // Optional, defaults to 'https://base44.app' - appId: 'your-app-id', // Required - token: 'your-user-token', // Optional, for user authentication - serviceToken: 'your-service-token', // Optional, for service role authentication - autoInitAuth: true, // Optional, defaults to true - auto-detects tokens from URL or localStorage + serverUrl: "https://base44.app", // Optional, defaults to 'https://base44.app' + appId: "your-app-id", // Required + token: "your-user-token", // Optional, for user authentication + serviceToken: "your-service-token", // Optional, for service role authentication + autoInitAuth: true, // Optional, defaults to true - auto-detects tokens from URL or localStorage }); ``` @@ -35,31 +35,31 @@ const products = await base44.entities.Product.list(); // Filter products by category const filteredProducts = await base44.entities.Product.filter({ - category: ['electronics', 'computers'] + category: ["electronics", "computers"], }); // Get a specific product -const product = await base44.entities.Product.get('product-id'); +const product = await base44.entities.Product.get("product-id"); // Create a new product const newProduct = await base44.entities.Product.create({ - name: 'New Product', + name: "New Product", price: 99.99, - category: 'electronics' + category: "electronics", }); // Update a product -const updatedProduct = await base44.entities.Product.update('product-id', { - price: 89.99 +const updatedProduct = await base44.entities.Product.update("product-id", { + price: 89.99, }); // Delete a product -await base44.entities.Product.delete('product-id'); +await base44.entities.Product.delete("product-id"); // Bulk create products const newProducts = await base44.entities.Product.bulkCreate([ - { name: 'Product 1', price: 19.99 }, - { name: 'Product 2', price: 29.99 } + { name: "Product 1", price: 19.99 }, + { name: "Product 2", price: 29.99 }, ]); ``` @@ -68,13 +68,13 @@ const newProducts = await base44.entities.Product.bulkCreate([ Service role authentication allows server-side applications to perform operations with elevated privileges. This is useful for administrative tasks, background jobs, and server-to-server communication. ```javascript -import { createClient } from '@base44/sdk'; +import { createClient } from "@base44/sdk"; // Create a client with service role token const base44 = createClient({ - appId: 'your-app-id', - token: 'user-token', // For user operations - serviceToken: 'service-token' // For service role operations + appId: "your-app-id", + token: "user-token", // For user operations + serviceToken: "service-token", // For service role operations }); // User operations (uses user token) @@ -90,7 +90,7 @@ const allEntities = await base44.asServiceRole.entities.User.list(); // Note: Service role does NOT have access to auth module for security // If no service token is provided, accessing asServiceRole throws an error -const clientWithoutService = createClient({ appId: 'your-app-id' }); +const clientWithoutService = createClient({ appId: "your-app-id" }); try { await clientWithoutService.asServiceRole.entities.User.list(); } catch (error) { @@ -103,20 +103,20 @@ try { For server-side applications, you can create a client from incoming HTTP requests: ```javascript -import { createClientFromRequest } from '@base44/sdk'; +import { createClientFromRequest } from "@base44/sdk"; // In your server handler (Express, Next.js, etc.) -app.get('/api/data', async (req, res) => { +app.get("/api/data", async (req, res) => { try { // Extract client configuration from request headers const base44 = createClientFromRequest(req); - + // Headers used: // - Authorization: Bearer // - Base44-Service-Authorization: Bearer // - Base44-App-Id: // - Base44-Api-Url: (optional) - + // Use appropriate authentication based on available tokens let data; if (base44.asServiceRole) { @@ -126,7 +126,7 @@ app.get('/api/data', async (req, res) => { // Only user token available - use user permissions data = await base44.entities.PublicData.list(); } - + res.json(data); } catch (error) { res.status(500).json({ error: error.message }); @@ -139,15 +139,15 @@ app.get('/api/data', async (req, res) => { ```javascript // Send an email using the Core integration const emailResult = await base44.integrations.Core.SendEmail({ - to: 'user@example.com', - subject: 'Hello from Base44', - body: 'This is a test email sent via the Base44 SDK' + to: "user@example.com", + subject: "Hello from Base44", + body: "This is a test email sent via the Base44 SDK", }); // Use a custom integration const result = await base44.integrations.CustomPackage.CustomEndpoint({ - param1: 'value1', - param2: 'value2' + param1: "value1", + param2: "value2", }); // Upload a file @@ -155,7 +155,7 @@ const fileInput = document.querySelector('input[type="file"]'); const file = fileInput.files[0]; const uploadResult = await base44.integrations.Core.UploadFile({ file, - metadata: { type: 'profile-picture' } + metadata: { type: "profile-picture" }, }); ``` @@ -168,45 +168,49 @@ The SDK provides comprehensive authentication capabilities to help you build sec To create a client with authentication: ```javascript -import { createClient } from '@base44/sdk'; -import { getAccessToken } from '@base44/sdk/utils/auth-utils'; +import { createClient } from "@base44/sdk"; +import { getAccessToken } from "@base44/sdk/utils/auth-utils"; // Create a client with authentication const base44 = createClient({ - appId: 'your-app-id', - token: getAccessToken() // Automatically retrieves token from localStorage or URL + appId: "your-app-id", + token: getAccessToken(), // Automatically retrieves token from localStorage or URL }); // Check authentication status const isAuthenticated = await base44.auth.isAuthenticated(); -console.log('Authenticated:', isAuthenticated); +console.log("Authenticated:", isAuthenticated); // Get current user information (requires authentication) if (isAuthenticated) { const user = await base44.auth.me(); - console.log('Current user:', user); + console.log("Current user:", user); } ``` ### Login and Logout ```javascript -import { createClient } from '@base44/sdk'; -import { getAccessToken, saveAccessToken, removeAccessToken } from '@base44/sdk/utils/auth-utils'; +import { createClient } from "@base44/sdk"; +import { + getAccessToken, + saveAccessToken, + removeAccessToken, +} from "@base44/sdk/utils/auth-utils"; -const base44 = createClient({ appId: 'your-app-id' }); +const base44 = createClient({ appId: "your-app-id" }); // Redirect to the login page // This will redirect to: base44.app/login?from_url=http://your-app.com/dashboard&app_id=your-app-id function handleLogin() { - base44.auth.login('/dashboard'); + base44.auth.login("/dashboard"); } // Handle successful login (on return from Base44 login) function handleLoginReturn() { const token = getAccessToken(); if (token) { - console.log('Successfully logged in with token:', token); + console.log("Successfully logged in with token:", token); // The token is automatically saved to localStorage and removed from URL } } @@ -214,7 +218,7 @@ function handleLoginReturn() { // Logout function handleLogout() { removeAccessToken(); - window.location.href = '/login'; + window.location.href = "/login"; } ``` @@ -223,10 +227,13 @@ function handleLogout() { Here's a complete example of implementing Base44 authentication in a React application: ```jsx -import React, { createContext, useContext, useEffect, useState } from 'react'; -import { Navigate, Outlet, Route, Routes, useLocation } from 'react-router-dom'; -import { createClient } from '@base44/sdk'; -import { getAccessToken, removeAccessToken } from '@base44/sdk/utils/auth-utils'; +import React, { createContext, useContext, useEffect, useState } from "react"; +import { Navigate, Outlet, Route, Routes, useLocation } from "react-router-dom"; +import { createClient } from "@base44/sdk"; +import { + getAccessToken, + removeAccessToken, +} from "@base44/sdk/utils/auth-utils"; // Create AuthContext const AuthContext = createContext(null); @@ -235,10 +242,10 @@ const AuthContext = createContext(null); function AuthProvider({ children }) { const [user, setUser] = useState(null); const [loading, setLoading] = useState(true); - const [client] = useState(() => - createClient({ - appId: 'your-app-id', - token: getAccessToken() + const [client] = useState(() => + createClient({ + appId: "your-app-id", + token: getAccessToken(), }) ); @@ -251,12 +258,12 @@ function AuthProvider({ children }) { setUser(userData); } } catch (error) { - console.error('Authentication error:', error); + console.error("Authentication error:", error); } finally { setLoading(false); } } - + loadUser(); }, [client]); @@ -267,7 +274,7 @@ function AuthProvider({ children }) { const logout = () => { removeAccessToken(); setUser(null); - window.location.href = '/login'; + window.location.href = "/login"; }; return ( @@ -281,7 +288,7 @@ function AuthProvider({ children }) { function useAuth() { const context = useContext(AuthContext); if (!context) { - throw new Error('useAuth must be used within an AuthProvider'); + throw new Error("useAuth must be used within an AuthProvider"); } return context; } @@ -323,12 +330,12 @@ function Dashboard() { async function loadTodos() { try { // Load user-specific data using the SDK - const items = await client.entities.Todo.filter({ - assignee: user.id + const items = await client.entities.Todo.filter({ + assignee: user.id, }); setTodos(items); } catch (error) { - console.error('Failed to load todos:', error); + console.error("Failed to load todos:", error); } finally { setLoading(false); } @@ -341,13 +348,13 @@ function Dashboard() {

Welcome, {user.name}!

- +

Your Todos

{loading ? (
Loading todos...
) : (
    - {todos.map(todo => ( + {todos.map((todo) => (
  • {todo.title}
    • ))}
@@ -359,11 +366,11 @@ function Dashboard() { // Login Page function LoginPage() { const { login, user } = useAuth(); - + if (user) { return ; } - + return (

Login Required

@@ -395,21 +402,21 @@ function App() { This SDK includes TypeScript definitions out of the box: ```typescript -import { createClient, Base44Error } from '@base44/sdk'; -import type { Entity, Base44Client, AuthModule } from '@base44/sdk'; +import { createClient, Base44Error } from "@base44/sdk"; +import type { Entity, Base44Client, AuthModule } from "@base44/sdk"; // Create a typed client const base44: Base44Client = createClient({ - appId: 'your-app-id' + appId: "your-app-id", }); // Using the entities module with type safety async function fetchProducts() { try { const products: Entity[] = await base44.entities.Product.list(); - console.log(products.map(p => p.name)); - - const product: Entity = await base44.entities.Product.get('product-id'); + console.log(products.map((p) => p.name)); + + const product: Entity = await base44.entities.Product.get("product-id"); console.log(product.name); } catch (error) { if (error instanceof Base44Error) { @@ -421,8 +428,8 @@ async function fetchProducts() { // Service role operations with TypeScript async function adminOperations() { const base44 = createClient({ - appId: 'your-app-id', - serviceToken: 'service-token' + appId: "your-app-id", + serviceToken: "service-token", }); // TypeScript knows asServiceRole requires a service token @@ -440,19 +447,19 @@ async function adminOperations() { async function handleAuth(auth: AuthModule) { // Check authentication const isAuthenticated: boolean = await auth.isAuthenticated(); - + if (isAuthenticated) { // Get user info const user: Entity = await auth.me(); console.log(`Logged in as: ${user.name}, Role: ${user.role}`); - + // Update user const updatedUser: Entity = await auth.updateMe({ - preferences: { theme: 'dark' } + preferences: { theme: "dark" }, }); } else { // Redirect to login - auth.login('/dashboard'); + auth.login("/dashboard"); } } @@ -469,9 +476,9 @@ You can define your own entity interfaces for better type safety: interface User extends Entity { name: string; email: string; - role: 'admin' | 'editor' | 'viewer'; + role: "admin" | "editor" | "viewer"; preferences?: { - theme: 'light' | 'dark'; + theme: "light" | "dark"; notifications: boolean; }; } @@ -485,13 +492,13 @@ interface Product extends Entity { // Use your custom interfaces with the SDK async function getLoggedInUser(): Promise { - const base44 = createClient({ appId: 'your-app-id' }); - + const base44 = createClient({ appId: "your-app-id" }); + try { - const user = await base44.auth.me() as User; + const user = (await base44.auth.me()) as User; return user; } catch (error) { - console.error('Failed to get user:', error); + console.error("Failed to get user:", error); return null; } } @@ -500,24 +507,24 @@ async function getLoggedInUser(): Promise { function useBase44User() { const [user, setUser] = useState(null); const [loading, setLoading] = useState(true); - + useEffect(() => { - const base44 = createClient({ appId: 'your-app-id' }); - + const base44 = createClient({ appId: "your-app-id" }); + async function fetchUser() { try { - const userData = await base44.auth.me() as User; + const userData = (await base44.auth.me()) as User; setUser(userData); } catch (error) { - console.error('Auth error:', error); + console.error("Auth error:", error); } finally { setLoading(false); } } - + fetchUser(); }, []); - + return { user, loading }; } ``` @@ -527,9 +534,9 @@ function useBase44User() { The SDK provides a custom `Base44Error` class for error handling: ```javascript -import { createClient, Base44Error } from '@base44/sdk'; +import { createClient, Base44Error } from "@base44/sdk"; -const base44 = createClient({ appId: 'your-app-id' }); +const base44 = createClient({ appId: "your-app-id" }); try { const result = await base44.entities.NonExistentEntity.list(); @@ -540,7 +547,7 @@ try { console.error(`Code: ${error.code}`); console.error(`Data: ${JSON.stringify(error.data)}`); } else { - console.error('Unexpected error:', error); + console.error("Unexpected error:", error); } } ``` @@ -555,8 +562,8 @@ const result = await base44.functions.myFunction(); // Invoke a function with parameters const result = await base44.functions.calculateTotal({ - items: ['item1', 'item2'], - discount: 0.1 + items: ["item1", "item2"], + discount: 0.1, }); // Functions are automatically authenticated with the user token @@ -564,6 +571,447 @@ const result = await base44.functions.calculateTotal({ const serviceResult = await base44.asServiceRole.functions.adminFunction(); ``` +## AI Agents + +The SDK provides comprehensive support for AI agent conversations with real-time messaging capabilities. + +### Basic Agent Setup + +```javascript +import { createClient } from "@base44/sdk"; + +// Create a client with agents support +const base44 = createClient({ + appId: "your-app-id", + token: "your-auth-token", + agents: { + enableWebSocket: true, // Enable real-time updates + socketUrl: "wss://base44.app/ws", // Optional: custom WebSocket URL + }, +}); +``` + +### Working with Agent Conversations + +```javascript +// Create a new conversation with an agent +const conversation = await base44.agents.createConversation({ + agent_name: "customer-support-agent", + metadata: { + source: "web-app", + priority: "normal", + customer_id: "cust_12345", + }, +}); + +// Send a message to the agent +const response = await base44.agents.sendMessage(conversation.id, { + role: "user", + content: "Hello! I need help with my account.", + metadata: { + timestamp: new Date().toISOString(), + }, +}); + +// Get conversation history +const fullConversation = await base44.agents.getConversation(conversation.id); +console.log("Messages:", fullConversation.messages); + +// List all conversations +const conversations = await base44.agents.listConversations({ + limit: 10, + sort: { created_at: -1 }, +}); +``` + +### Real-Time Agent Conversations + +```javascript +// Subscribe to real-time updates for a conversation +const unsubscribe = base44.agents.subscribeToConversation( + conversation.id, + (updatedConversation) => { + console.log("New messages:", updatedConversation.messages); + + // Handle new agent responses + const lastMessage = + updatedConversation.messages[updatedConversation.messages.length - 1]; + if (lastMessage?.role === "assistant") { + displayAgentMessage(lastMessage.content); + } + } +); + +// Send a message and receive real-time responses +await base44.agents.sendMessage(conversation.id, { + role: "user", + content: "Can you help me with billing questions?", +}); + +// Clean up subscription when done +unsubscribe(); +``` + +### Advanced Agent Usage + +```javascript +// Filter conversations by agent type +const supportConversations = await base44.agents.listConversations({ + query: { agent_name: "support-agent" }, + limit: 20, +}); + +// Update conversation metadata +await base44.agents.updateConversation(conversation.id, { + metadata: { + status: "resolved", + satisfaction_rating: 5, + resolution_time: "5 minutes", + }, +}); + +// Delete a specific message from conversation +await base44.agents.deleteMessage(conversation.id, "message-id"); + +// Check WebSocket connection status +const status = base44.agents.getWebSocketStatus(); +console.log("WebSocket enabled:", status.enabled); +console.log("WebSocket connected:", status.connected); + +// Manually control WebSocket connection +if (status.enabled && !status.connected) { + await base44.agents.connectWebSocket(); +} + +// Disconnect WebSocket when done +base44.agents.disconnectWebSocket(); +``` + +### TypeScript Support for Agents + +```typescript +import { + createClient, + AgentConversation, + Message, + CreateConversationPayload, +} from "@base44/sdk"; + +// Define custom conversation metadata interface +interface CustomerSupportMetadata { + customer_id: string; + priority: "low" | "normal" | "high" | "urgent"; + department: "sales" | "support" | "technical"; + source: "web" | "mobile" | "email"; +} + +// Create typed conversation +const conversation: AgentConversation = await base44.agents.createConversation({ + agent_name: "support-agent", + metadata: { + customer_id: "cust_123", + priority: "high", + department: "support", + source: "web", + } as CustomerSupportMetadata, +}); + +// Send typed message +const message: Omit = { + role: "user", + content: "I need help with my order", + timestamp: new Date().toISOString(), + metadata: { + intent: "order_inquiry", + order_id: "ord_456", + }, +}; + +const response: Message = await base44.agents.sendMessage( + conversation.id, + message +); +``` + +### Customer Service Chatbot Example + +```javascript +class CustomerServiceBot { + constructor(base44Client) { + this.client = base44Client; + this.activeConversations = new Map(); + } + + async startConversation(customerId, initialMessage) { + // Create conversation with customer context + const conversation = await this.client.agents.createConversation({ + agent_name: "customer-service-bot", + metadata: { + customer_id: customerId, + session_start: new Date().toISOString(), + channel: "web-chat", + }, + }); + + // Set up real-time message handling + const unsubscribe = this.client.agents.subscribeToConversation( + conversation.id, + (updatedConversation) => { + this.handleConversationUpdate(updatedConversation); + } + ); + + // Store conversation reference + this.activeConversations.set(conversation.id, { + conversation, + unsubscribe, + customerId, + }); + + // Send initial message + await this.client.agents.sendMessage(conversation.id, { + role: "user", + content: initialMessage, + metadata: { message_type: "initial_inquiry" }, + }); + + return conversation.id; + } + + handleConversationUpdate(conversation) { + const lastMessage = conversation.messages[conversation.messages.length - 1]; + + if (lastMessage?.role === "assistant") { + // Display agent response to user + this.displayMessage(conversation.id, lastMessage); + + // Check for escalation keywords + if (this.shouldEscalate(lastMessage.content)) { + this.escalateToHuman(conversation.id); + } + } + } + + shouldEscalate(messageContent) { + const escalationKeywords = [ + "human agent", + "supervisor", + "manager", + "escalate", + ]; + return escalationKeywords.some((keyword) => + messageContent.toLowerCase().includes(keyword) + ); + } + + async escalateToHuman(conversationId) { + await this.client.agents.updateConversation(conversationId, { + metadata: { + escalated: true, + escalation_time: new Date().toISOString(), + status: "pending_human_agent", + }, + }); + + console.log(`Conversation ${conversationId} escalated to human agent`); + } + + async endConversation(conversationId) { + const conversationData = this.activeConversations.get(conversationId); + if (conversationData) { + // Clean up subscription + conversationData.unsubscribe(); + + // Update conversation status + await this.client.agents.updateConversation(conversationId, { + metadata: { + status: "completed", + session_end: new Date().toISOString(), + }, + }); + + this.activeConversations.delete(conversationId); + } + } + + displayMessage(conversationId, message) { + // Implement your UI message display logic here + console.log(`[${conversationId}] Agent: ${message.content}`); + } +} + +// Usage +const customerBot = new CustomerServiceBot(base44); +const conversationId = await customerBot.startConversation( + "customer_123", + "Hi, I have a problem with my recent order" +); +``` + +### Multi-Agent System Example + +```javascript +class MultiAgentRouter { + constructor(base44Client) { + this.client = base44Client; + this.agents = { + sales: "sales-agent", + support: "support-agent", + technical: "technical-agent", + }; + } + + async routeQuery(userQuery, customerContext) { + // Determine the best agent based on query content + const department = this.classifyQuery(userQuery); + const agentName = this.agents[department]; + + // Create conversation with appropriate agent + const conversation = await this.client.agents.createConversation({ + agent_name: agentName, + metadata: { + ...customerContext, + department, + routing_reason: `Auto-routed based on query classification`, + original_query: userQuery, + }, + }); + + // Send initial message + await this.client.agents.sendMessage(conversation.id, { + role: "user", + content: userQuery, + metadata: { + routing_department: department, + confidence: this.getClassificationConfidence(userQuery, department), + }, + }); + + return { conversationId: conversation.id, department, agent: agentName }; + } + + classifyQuery(query) { + const lowerQuery = query.toLowerCase(); + + if ( + lowerQuery.includes("buy") || + lowerQuery.includes("price") || + lowerQuery.includes("plan") + ) { + return "sales"; + } + if ( + lowerQuery.includes("api") || + lowerQuery.includes("integration") || + lowerQuery.includes("code") + ) { + return "technical"; + } + return "support"; // Default to support + } + + getClassificationConfidence(query, department) { + // Simple confidence scoring (you could use ML models here) + const keywords = { + sales: ["buy", "purchase", "price", "plan", "upgrade", "billing"], + technical: ["api", "integration", "code", "sdk", "development", "bug"], + support: ["help", "problem", "issue", "account", "login", "password"], + }; + + const queryWords = query.toLowerCase().split(" "); + const matches = keywords[department].filter((keyword) => + queryWords.some((word) => word.includes(keyword)) + ); + + return Math.min(matches.length * 0.3, 1.0); + } +} + +// Usage +const router = new MultiAgentRouter(base44); +const result = await router.routeQuery( + "I want to upgrade to your enterprise plan", + { customer_id: "cust_789", tier: "premium" } +); + +console.log( + `Routed to ${result.department} (${result.agent}): ${result.conversationId}` +); +``` + +### Error Handling with Agents + +```javascript +import { Base44Error } from "@base44/sdk"; + +async function robustAgentInteraction() { + const maxRetries = 3; + let retryCount = 0; + + while (retryCount < maxRetries) { + try { + // Attempt to create conversation + const conversation = await base44.agents.createConversation({ + agent_name: "support-agent", + }); + + // Send message with retry logic + const response = await base44.agents.sendMessage(conversation.id, { + role: "user", + content: "Hello, I need assistance", + }); + + console.log("Successfully sent message:", response); + return conversation; + } catch (error) { + retryCount++; + + if (error instanceof Base44Error) { + console.error(`Agent API Error (${error.status}): ${error.message}`); + + // Don't retry on client errors (4xx) + if (error.status >= 400 && error.status < 500) { + throw error; + } + } else { + console.error("Network or other error:", error); + } + + if (retryCount >= maxRetries) { + throw new Error( + `Failed to create agent conversation after ${maxRetries} attempts` + ); + } + + // Exponential backoff + const delay = Math.pow(2, retryCount) * 1000; + console.log( + `Retrying in ${delay}ms... (attempt ${retryCount + 1}/${maxRetries})` + ); + await new Promise((resolve) => setTimeout(resolve, delay)); + } + } +} + +// WebSocket error handling +base44.agents.subscribeToConversation( + conversationId, + (conversation) => { + // Handle successful updates + console.log("Conversation updated:", conversation.id); + }, + (error) => { + // Handle WebSocket errors + console.error("WebSocket error:", error); + + // Attempt to reconnect + setTimeout(() => { + base44.agents.connectWebSocket().catch(console.error); + }, 5000); + } +); +``` + ## Testing The SDK includes comprehensive tests to ensure reliability. @@ -590,6 +1038,7 @@ E2E tests require access to a Base44 API. To run these tests: 1. Copy `tests/.env.example` to `tests/.env` 2. Fill in your Base44 API credentials in the `.env` file: + ``` BASE44_SERVER_URL=https://base44.app BASE44_APP_ID=your_app_id_here @@ -603,25 +1052,25 @@ E2E tests require access to a Base44 API. To run these tests: You can use the provided test utilities for writing your own tests: ```javascript -const { createClient } = require('@base44/sdk'); -const { getTestConfig } = require('@base44/sdk/tests/utils/test-config'); +const { createClient } = require("@base44/sdk"); +const { getTestConfig } = require("@base44/sdk/tests/utils/test-config"); -describe('My Tests', () => { +describe("My Tests", () => { let base44; - + beforeAll(() => { const config = getTestConfig(); base44 = createClient({ serverUrl: config.serverUrl, appId: config.appId, }); - + if (config.token) { base44.setToken(config.token); } }); - - test('My test', async () => { + + test("My test", async () => { const todos = await base44.entities.Todo.filter({}, 10); expect(Array.isArray(todos)).toBe(true); expect(todos.length).toBeGreaterThan(0); @@ -631,4 +1080,4 @@ describe('My Tests', () => { ## License -MIT \ No newline at end of file +MIT diff --git a/examples/agents-typescript-usage.ts b/examples/agents-typescript-usage.ts new file mode 100644 index 0000000..9525ea3 --- /dev/null +++ b/examples/agents-typescript-usage.ts @@ -0,0 +1,410 @@ +import { + createClient, + AgentConversation, + Message, + CreateConversationPayload, + AgentsModuleConfig, +} from "@base44/sdk"; + +// TypeScript example with full type safety +interface CustomerContext { + customerId: string; + tier: "basic" | "premium" | "enterprise"; + previousInteractions: number; +} + +interface ConversationMetadata { + source: "web" | "mobile" | "api"; + priority: "low" | "normal" | "high" | "urgent"; + department: string; + customerContext?: CustomerContext; +} + +class AgentChatManager { + private client: ReturnType; + private activeConversations: Map = new Map(); + private subscriptions: Map void> = new Map(); + + constructor(appId: string, token: string, agentsConfig?: AgentsModuleConfig) { + this.client = createClient({ + appId, + token, + agents: { + enableWebSocket: true, + ...agentsConfig, + }, + }); + } + + /** + * Create a new conversation with typed metadata + */ + async createTypedConversation( + agentName: string, + metadata: ConversationMetadata + ): Promise { + const payload: CreateConversationPayload = { + agent_name: agentName, + metadata: metadata as Record, + }; + + const conversation = await this.client.agents.createConversation(payload); + this.activeConversations.set(conversation.id, conversation); + return conversation; + } + + /** + * Send a typed message to an agent + */ + async sendTypedMessage( + conversationId: string, + content: string, + metadata?: Record + ): Promise { + const message: Omit = { + role: "user", + content, + timestamp: new Date().toISOString(), + metadata: { + ...metadata, + client_version: "1.0.0", + user_agent: + typeof window !== "undefined" ? navigator.userAgent : "server", + }, + }; + + return await this.client.agents.sendMessage(conversationId, message); + } + + /** + * Subscribe to conversation updates with typed callbacks + */ + subscribeToConversation( + conversationId: string, + onUpdate: (conversation: AgentConversation) => void, + onError?: (error: Error) => void + ): void { + try { + const unsubscribe = this.client.agents.subscribeToConversation( + conversationId, + (conversation) => { + // Update local cache + this.activeConversations.set(conversationId, conversation); + onUpdate(conversation); + } + ); + + this.subscriptions.set(conversationId, unsubscribe); + } catch (error) { + if (onError) { + onError(error as Error); + } else { + console.error("Subscription error:", error); + } + } + } + + /** + * Get conversation with type safety + */ + async getConversationSafely( + conversationId: string + ): Promise { + try { + return await this.client.agents.getConversation(conversationId); + } catch (error) { + console.error(`Failed to get conversation ${conversationId}:`, error); + return null; + } + } + + /** + * List conversations with filtering + */ + async listConversationsByAgent( + agentName: string, + limit: number = 50 + ): Promise { + return await this.client.agents.listConversations({ + query: { agent_name: agentName }, + limit, + sort: { created_at: -1 }, + }); + } + + /** + * Clean up all subscriptions + */ + cleanup(): void { + this.subscriptions.forEach((unsubscribe) => unsubscribe()); + this.subscriptions.clear(); + this.activeConversations.clear(); + this.client.agents.disconnectWebSocket(); + } + + /** + * Get active conversation count + */ + getActiveConversationCount(): number { + return this.activeConversations.size; + } + + /** + * Get WebSocket status + */ + getConnectionStatus(): { enabled: boolean; connected: boolean } { + return this.client.agents.getWebSocketStatus(); + } +} + +// Usage examples with the typed manager +async function typedUsageExample() { + const chatManager = new AgentChatManager("your-app-id", "your-token"); + + try { + // Create a conversation with typed metadata + const conversation = await chatManager.createTypedConversation( + "customer-support-agent", + { + source: "web", + priority: "normal", + department: "support", + customerContext: { + customerId: "cust_12345", + tier: "premium", + previousInteractions: 3, + }, + } + ); + + console.log("Created conversation:", conversation.id); + + // Subscribe to updates + chatManager.subscribeToConversation( + conversation.id, + (updatedConversation) => { + console.log(`Conversation ${updatedConversation.id} updated:`, { + messageCount: updatedConversation.messages.length, + lastMessage: + updatedConversation.messages[ + updatedConversation.messages.length - 1 + ]?.content, + }); + }, + (error) => { + console.error("Subscription error:", error); + } + ); + + // Send messages with metadata + await chatManager.sendTypedMessage( + conversation.id, + "Hello! I need help with my premium account.", + { + intent: "account_help", + category: "billing", + } + ); + + // List conversations by agent + const supportConversations = await chatManager.listConversationsByAgent( + "customer-support-agent", + 10 + ); + + console.log(`Found ${supportConversations.length} support conversations`); + + // Clean up after 30 seconds + setTimeout(() => { + chatManager.cleanup(); + console.log("Chat manager cleaned up"); + }, 30000); + } catch (error) { + console.error("Typed usage error:", error); + chatManager.cleanup(); + } +} + +// Multi-agent conversation example +interface AgentConfig { + name: string; + department: string; + specialties: string[]; +} + +class MultiAgentManager { + private chatManager: AgentChatManager; + private agents: AgentConfig[] = [ + { + name: "sales-agent", + department: "sales", + specialties: ["pricing", "plans", "demos"], + }, + { + name: "support-agent", + department: "support", + specialties: ["technical-issues", "account-help", "billing"], + }, + { + name: "technical-agent", + department: "engineering", + specialties: ["api-integration", "troubleshooting", "development"], + }, + ]; + + constructor(appId: string, token: string) { + this.chatManager = new AgentChatManager(appId, token); + } + + /** + * Route user query to appropriate agent based on intent + */ + async routeToAgent( + userQuery: string, + customerContext: CustomerContext + ): Promise { + const intent = this.detectIntent(userQuery); + const agent = this.selectAgent(intent); + + const conversation = await this.chatManager.createTypedConversation( + agent.name, + { + source: "web", + priority: this.determinePriority(customerContext), + department: agent.department, + customerContext, + } + ); + + // Send initial message + await this.chatManager.sendTypedMessage(conversation.id, userQuery, { + intent, + routing_agent: agent.name, + routing_reason: `Selected based on specialties: ${agent.specialties.join( + ", " + )}`, + }); + + return conversation; + } + + private detectIntent(query: string): string { + const lowerQuery = query.toLowerCase(); + + if ( + lowerQuery.includes("price") || + lowerQuery.includes("plan") || + lowerQuery.includes("buy") + ) { + return "sales_inquiry"; + } + if ( + lowerQuery.includes("api") || + lowerQuery.includes("integration") || + lowerQuery.includes("code") + ) { + return "technical_support"; + } + if ( + lowerQuery.includes("problem") || + lowerQuery.includes("issue") || + lowerQuery.includes("help") + ) { + return "general_support"; + } + + return "general_inquiry"; + } + + private selectAgent(intent: string): AgentConfig { + switch (intent) { + case "sales_inquiry": + return this.agents.find((a) => a.name === "sales-agent")!; + case "technical_support": + return this.agents.find((a) => a.name === "technical-agent")!; + default: + return this.agents.find((a) => a.name === "support-agent")!; + } + } + + private determinePriority( + context: CustomerContext + ): "low" | "normal" | "high" | "urgent" { + if (context.tier === "enterprise") return "high"; + if (context.tier === "premium") return "normal"; + return "low"; + } + + cleanup(): void { + this.chatManager.cleanup(); + } +} + +// Example usage of multi-agent system +async function multiAgentExample() { + const multiAgent = new MultiAgentManager("your-app-id", "your-token"); + + const customerContext: CustomerContext = { + customerId: "cust_67890", + tier: "enterprise", + previousInteractions: 5, + }; + + try { + // Route different queries to different agents + const queries = [ + "I want to upgrade to your enterprise plan", + "I'm having trouble with the API integration", + "My account dashboard is not loading properly", + ]; + + const conversations = await Promise.all( + queries.map((query) => multiAgent.routeToAgent(query, customerContext)) + ); + + console.log( + "Created conversations:", + conversations.map((c) => ({ + id: c.id, + agent: c.agent_name, + department: (c.metadata as ConversationMetadata).department, + })) + ); + + // Clean up after processing + setTimeout(() => { + multiAgent.cleanup(); + }, 30000); + } catch (error) { + console.error("Multi-agent example error:", error); + multiAgent.cleanup(); + } +} + +// Export for use in other modules +export { + AgentChatManager, + MultiAgentManager, + typedUsageExample, + multiAgentExample, + type CustomerContext, + type ConversationMetadata, +}; + +// Run examples if this file is executed directly +if ( + typeof window === "undefined" && + import.meta.url === `file://${process.argv[1]}` +) { + console.log("Running TypeScript Agents Examples..."); + + typedUsageExample().then(() => { + console.log("Typed usage example completed"); + }); + + setTimeout(() => { + multiAgentExample().then(() => { + console.log("Multi-agent example completed"); + }); + }, 5000); +} diff --git a/examples/agents-usage.js b/examples/agents-usage.js new file mode 100644 index 0000000..e7e8627 --- /dev/null +++ b/examples/agents-usage.js @@ -0,0 +1,325 @@ +import { createClient } from '@base44/sdk'; + +// Basic agents usage example +async function basicAgentsUsage() { + // Create client with agents support + const client = createClient({ + appId: 'your-app-id', + token: 'your-auth-token', + agents: { + enableWebSocket: true, // Enable real-time updates + socketUrl: 'wss://base44.app/ws' // Optional: custom WebSocket URL + } + }); + + try { + // 1. List existing conversations + console.log('Listing conversations...'); + const conversations = await client.agents.listConversations({ + limit: 10, + sort: { created_at: -1 } // Sort by newest first + }); + console.log(`Found ${conversations.length} conversations`); + + // 2. Create a new conversation with an agent + console.log('Creating new conversation...'); + const conversation = await client.agents.createConversation({ + agent_name: 'customer-support-agent', + metadata: { + source: 'web-app', + user_context: 'premium-user' + } + }); + console.log(`Created conversation: ${conversation.id}`); + + // 3. Send a message to the agent + console.log('Sending message to agent...'); + const userMessage = { + role: 'user', + content: 'Hello! I need help with my account settings.', + metadata: { + timestamp: new Date().toISOString() + } + }; + + const response = await client.agents.sendMessage(conversation.id, userMessage); + console.log('Agent response:', response); + + // 4. Subscribe to real-time updates (if WebSocket is enabled) + console.log('Subscribing to conversation updates...'); + const unsubscribe = client.agents.subscribeToConversation( + conversation.id, + (updatedConversation) => { + console.log('Conversation updated:', { + id: updatedConversation.id, + messageCount: updatedConversation.messages.length, + lastMessage: updatedConversation.messages[updatedConversation.messages.length - 1] + }); + } + ); + + // 5. Send another message to see real-time updates + setTimeout(async () => { + await client.agents.sendMessage(conversation.id, { + role: 'user', + content: 'Can you also help me understand the billing cycle?' + }); + }, 2000); + + // 6. Clean up subscription after 30 seconds + setTimeout(() => { + unsubscribe(); + console.log('Unsubscribed from conversation updates'); + }, 30000); + + } catch (error) { + console.error('Error:', error); + } +} + +// Advanced agents usage with conversation management +async function advancedAgentsUsage() { + const client = createClient({ + appId: 'your-app-id', + token: 'your-auth-token', + agents: { + enableWebSocket: true + } + }); + + try { + // Create multiple conversations with different agents + const agents = ['sales-agent', 'support-agent', 'technical-agent']; + const conversations = []; + + for (const agentName of agents) { + const conversation = await client.agents.createConversation({ + agent_name: agentName, + metadata: { + department: agentName.split('-')[0], + priority: 'normal' + } + }); + conversations.push(conversation); + console.log(`Created conversation with ${agentName}: ${conversation.id}`); + } + + // Send different messages to each agent + const messages = [ + 'I\'m interested in your premium plan pricing', + 'I\'m having trouble logging into my account', + 'I need help integrating your API with my system' + ]; + + const responses = await Promise.all( + conversations.map((conv, index) => + client.agents.sendMessage(conv.id, { + role: 'user', + content: messages[index] + }) + ) + ); + + console.log('All agent responses received:', responses.length); + + // Update conversation metadata based on responses + for (let i = 0; i < conversations.length; i++) { + await client.agents.updateConversation(conversations[i].id, { + metadata: { + ...conversations[i].metadata, + status: 'active', + last_response_at: new Date().toISOString() + } + }); + } + + // Get updated conversations + const updatedConversations = await Promise.all( + conversations.map(conv => client.agents.getConversation(conv.id)) + ); + + console.log('Updated conversations:', updatedConversations.map(conv => ({ + id: conv.id, + agent: conv.agent_name, + messageCount: conv.messages.length, + status: conv.metadata.status + }))); + + } catch (error) { + console.error('Advanced usage error:', error); + } +} + +// Customer service chatbot example +async function customerServiceExample() { + const client = createClient({ + appId: 'your-app-id', + token: 'your-auth-token', + agents: { enableWebSocket: true } + }); + + // Simulate a customer service session + const conversation = await client.agents.createConversation({ + agent_name: 'customer-service-bot', + metadata: { + customer_id: 'cust_12345', + session_start: new Date().toISOString(), + channel: 'web-chat' + } + }); + + // Set up real-time message handling + const unsubscribe = client.agents.subscribeToConversation( + conversation.id, + (updatedConversation) => { + const lastMessage = updatedConversation.messages[updatedConversation.messages.length - 1]; + if (lastMessage?.role === 'assistant') { + console.log('🤖 Agent:', lastMessage.content); + + // Check if agent is asking for escalation + if (lastMessage.content.toLowerCase().includes('transfer') || + lastMessage.content.toLowerCase().includes('human agent')) { + console.log('🔄 Escalating to human agent...'); + // Here you would implement escalation logic + } + } + } + ); + + // Simulate customer conversation flow + const customerMessages = [ + 'Hi, I have a problem with my recent order', + 'My order number is ORD-12345 and it was supposed to arrive yesterday', + 'Yes, I can provide my email address: customer@example.com', + 'I would like a refund please', + 'Thank you for your help!' + ]; + + for (let i = 0; i < customerMessages.length; i++) { + console.log(`👤 Customer: ${customerMessages[i]}`); + + await client.agents.sendMessage(conversation.id, { + role: 'user', + content: customerMessages[i], + metadata: { + timestamp: new Date().toISOString(), + message_number: i + 1 + } + }); + + // Wait for agent response before sending next message + await new Promise(resolve => setTimeout(resolve, 3000)); + } + + // Clean up + setTimeout(() => { + unsubscribe(); + console.log('Customer service session ended'); + }, 20000); +} + +// Error handling and retry example +async function errorHandlingExample() { + const client = createClient({ + appId: 'your-app-id', + token: 'your-auth-token', + agents: { enableWebSocket: true } + }); + + const maxRetries = 3; + let retryCount = 0; + + async function sendMessageWithRetry(conversationId, message) { + while (retryCount < maxRetries) { + try { + return await client.agents.sendMessage(conversationId, message); + } catch (error) { + retryCount++; + console.log(`Attempt ${retryCount} failed:`, error.message); + + if (retryCount >= maxRetries) { + throw new Error(`Failed to send message after ${maxRetries} attempts: ${error.message}`); + } + + // Exponential backoff + const delay = Math.pow(2, retryCount) * 1000; + console.log(`Retrying in ${delay}ms...`); + await new Promise(resolve => setTimeout(resolve, delay)); + } + } + } + + try { + const conversation = await client.agents.createConversation({ + agent_name: 'support-agent' + }); + + const response = await sendMessageWithRetry(conversation.id, { + role: 'user', + content: 'This message should be sent with retry logic' + }); + + console.log('Message sent successfully:', response); + } catch (error) { + console.error('Final error:', error); + } +} + +// WebSocket status monitoring +function webSocketStatusExample() { + const client = createClient({ + appId: 'your-app-id', + token: 'your-auth-token', + agents: { enableWebSocket: true } + }); + + // Check WebSocket status + const status = client.agents.getWebSocketStatus(); + console.log('WebSocket status:', status); + + if (status.enabled && !status.connected) { + console.log('Connecting WebSocket...'); + client.agents.connectWebSocket() + .then(() => { + console.log('WebSocket connected successfully'); + const newStatus = client.agents.getWebSocketStatus(); + console.log('Updated status:', newStatus); + }) + .catch(error => { + console.error('WebSocket connection failed:', error); + }); + } + + // Monitor connection status + setInterval(() => { + const currentStatus = client.agents.getWebSocketStatus(); + if (!currentStatus.connected && currentStatus.enabled) { + console.log('WebSocket disconnected, attempting to reconnect...'); + client.agents.connectWebSocket().catch(console.error); + } + }, 10000); // Check every 10 seconds +} + +// Run examples +if (import.meta.url === `file://${process.argv[1]}`) { + console.log('Running Basic Agents Usage Example...'); + basicAgentsUsage(); + + setTimeout(() => { + console.log('\nRunning Advanced Agents Usage Example...'); + advancedAgentsUsage(); + }, 5000); + + setTimeout(() => { + console.log('\nRunning Customer Service Example...'); + customerServiceExample(); + }, 10000); +} + +export { + basicAgentsUsage, + advancedAgentsUsage, + customerServiceExample, + errorHandlingExample, + webSocketStatusExample +}; diff --git a/src/client.ts b/src/client.ts index a4e8049..c0a7faa 100644 --- a/src/client.ts +++ b/src/client.ts @@ -5,6 +5,7 @@ import { createAuthModule } from "./modules/auth.js"; import { createSsoModule } from "./modules/sso.js"; import { getAccessToken } from "./utils/auth-utils.js"; import { createFunctionsModule } from "./modules/functions.js"; +import { createAgentsModule, AgentsModuleConfig } from "./modules/agents.js"; /** * Create a Base44 client instance @@ -14,6 +15,7 @@ import { createFunctionsModule } from "./modules/functions.js"; * @param {string} [config.token] - Authentication token * @param {string} [config.serviceToken] - Service role authentication token * @param {boolean} [config.requiresAuth=false] - Whether the app requires authentication + * @param {AgentsModuleConfig} [config.agents] - Configuration for agents module * @returns {Object} Base44 client instance */ export function createClient(config: { @@ -22,6 +24,7 @@ export function createClient(config: { token?: string; serviceToken?: string; requiresAuth?: boolean; + agents?: AgentsModuleConfig; }) { const { serverUrl = "https://base44.app", @@ -29,6 +32,7 @@ export function createClient(config: { token, serviceToken, requiresAuth = false, + agents = {}, } = config; const axiosClient = createAxiosClient({ @@ -80,6 +84,7 @@ export function createClient(config: { integrations: createIntegrationsModule(axiosClient, appId), auth: createAuthModule(axiosClient, functionsAxiosClient, appId), functions: createFunctionsModule(functionsAxiosClient, appId), + agents: createAgentsModule(axiosClient, appId, agents), }; const serviceRoleModules = { @@ -87,6 +92,7 @@ export function createClient(config: { integrations: createIntegrationsModule(serviceRoleAxiosClient, appId), sso: createSsoModule(serviceRoleAxiosClient, appId, token), functions: createFunctionsModule(serviceRoleFunctionsAxiosClient, appId), + agents: createAgentsModule(serviceRoleAxiosClient, appId, agents), }; // Always try to get token from localStorage or URL parameters @@ -144,10 +150,12 @@ export function createClient(config: { */ get asServiceRole() { if (!serviceToken) { - throw new Error('Service token is required to use asServiceRole. Please provide a serviceToken when creating the client.'); + throw new Error( + "Service token is required to use asServiceRole. Please provide a serviceToken when creating the client." + ); } return serviceRoleModules; - } + }, }; return client; @@ -172,17 +180,29 @@ export function createClientFromRequest(request: Request) { let userToken: string | undefined; if (serviceRoleAuthHeader !== null) { - if (serviceRoleAuthHeader === '' || !serviceRoleAuthHeader.startsWith('Bearer ') || serviceRoleAuthHeader.split(' ').length !== 2) { - throw new Error('Invalid authorization header format. Expected "Bearer "'); + if ( + serviceRoleAuthHeader === "" || + !serviceRoleAuthHeader.startsWith("Bearer ") || + serviceRoleAuthHeader.split(" ").length !== 2 + ) { + throw new Error( + 'Invalid authorization header format. Expected "Bearer "' + ); } - serviceRoleToken = serviceRoleAuthHeader.split(' ')[1]; + serviceRoleToken = serviceRoleAuthHeader.split(" ")[1]; } if (authHeader !== null) { - if (authHeader === '' || !authHeader.startsWith('Bearer ') || authHeader.split(' ').length !== 2) { - throw new Error('Invalid authorization header format. Expected "Bearer "'); + if ( + authHeader === "" || + !authHeader.startsWith("Bearer ") || + authHeader.split(" ").length !== 2 + ) { + throw new Error( + 'Invalid authorization header format. Expected "Bearer "' + ); } - userToken = authHeader.split(' ')[1]; + userToken = authHeader.split(" ")[1]; } return createClient({ diff --git a/src/index.ts b/src/index.ts index 2002286..9696ae2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -7,6 +7,16 @@ import { getLoginUrl, } from "./utils/auth-utils.js"; +export type { + Message, + AgentConversation, + CreateConversationPayload, + UpdateConversationPayload, + FilterParams, + AgentsModuleConfig, + AgentsModule, +} from "./modules/agents.js"; + export { createClient, createClientFromRequest, diff --git a/src/modules/agents.ts b/src/modules/agents.ts new file mode 100644 index 0000000..53a105a --- /dev/null +++ b/src/modules/agents.ts @@ -0,0 +1,386 @@ +import { AxiosInstance } from "axios"; + +export interface Message { + id: string; + role: "user" | "assistant"; + content: string; + timestamp?: string; + metadata?: Record; +} + +export interface AgentConversation { + id: string; + app_id: string; + created_by_id: string; + agent_name: string; + messages: Message[]; + metadata: Record; + created_at?: string; + updated_at?: string; +} + +export interface CreateConversationPayload { + agent_name: string; + metadata?: Record; +} + +export interface UpdateConversationPayload { + metadata?: Record; +} + +export interface FilterParams { + query?: Record; + sort?: Record; + limit?: number; + skip?: number; +} + +export interface AgentsModuleConfig { + enableWebSocket?: boolean; + socketUrl?: string; +} + +/** + * WebSocket manager for real-time agent conversations + */ +class AgentWebSocketManager { + private socket: WebSocket | null = null; + private listeners: Map void>> = new Map(); + private reconnectAttempts = 0; + private maxReconnectAttempts = 5; + private reconnectDelay = 1000; + private socketUrl: string; + private appId: string; + private token?: string; + + constructor(socketUrl: string, appId: string, token?: string) { + this.socketUrl = socketUrl; + this.appId = appId; + this.token = token; + } + + connect(): Promise { + return new Promise((resolve, reject) => { + // Check if WebSocket is available (browser environment) + if (typeof WebSocket === "undefined") { + reject(new Error("WebSocket is not available in this environment")); + return; + } + + if (this.socket?.readyState === WebSocket.OPEN) { + resolve(); + return; + } + + try { + const wsUrl = new URL(this.socketUrl); + wsUrl.searchParams.set("appId", this.appId); + if (this.token) { + wsUrl.searchParams.set("token", this.token); + } + + this.socket = new WebSocket(wsUrl.toString()); + + this.socket.onopen = () => { + this.reconnectAttempts = 0; + resolve(); + }; + + this.socket.onmessage = (event) => { + try { + const data = JSON.parse(event.data); + this.handleMessage(data); + } catch (error) { + console.error("Failed to parse WebSocket message:", error); + } + }; + + this.socket.onclose = () => { + this.attemptReconnect(); + }; + + this.socket.onerror = (error) => { + console.error("WebSocket error:", error); + reject(error); + }; + } catch (error) { + reject(error); + } + }); + } + + private handleMessage(data: any) { + if (data.event === "update_model" && data.data?.room) { + const listeners = this.listeners.get(data.data.room); + if (listeners) { + const parsedData = + typeof data.data.data === "string" + ? JSON.parse(data.data.data) + : data.data.data; + listeners.forEach((callback) => callback(parsedData)); + } + } + } + + private attemptReconnect() { + if (this.reconnectAttempts >= this.maxReconnectAttempts) { + console.error("Max reconnection attempts reached"); + return; + } + + this.reconnectAttempts++; + const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1); + + setTimeout(() => { + console.log( + `Attempting to reconnect (${this.reconnectAttempts}/${this.maxReconnectAttempts})...` + ); + this.connect().catch((error) => { + console.error("Reconnection failed:", error); + }); + }, delay); + } + + subscribe( + room: string, + callback: (data: AgentConversation) => void + ): () => void { + if (!this.listeners.has(room)) { + this.listeners.set(room, new Set()); + } + this.listeners.get(room)!.add(callback); + + // Send subscription message if connected + if ( + typeof WebSocket !== "undefined" && + this.socket && + this.socket.readyState === WebSocket.OPEN && + this.socket.send + ) { + this.socket.send( + JSON.stringify({ + type: "subscribe", + room: room, + }) + ); + } + + // Return unsubscribe function + return () => { + const roomListeners = this.listeners.get(room); + if (roomListeners) { + roomListeners.delete(callback); + if (roomListeners.size === 0) { + this.listeners.delete(room); + // Send unsubscribe message if connected + if ( + typeof WebSocket !== "undefined" && + this.socket && + this.socket.readyState === WebSocket.OPEN && + this.socket.send + ) { + this.socket.send( + JSON.stringify({ + type: "unsubscribe", + room: room, + }) + ); + } + } + } + }; + } + + disconnect() { + if (this.socket) { + this.socket.close(); + this.socket = null; + } + this.listeners.clear(); + } + + isConnected(): boolean { + if (typeof WebSocket === "undefined") { + return false; + } + return this.socket?.readyState === WebSocket.OPEN; + } +} + +/** + * Create agents module for managing AI agent conversations + */ +export function createAgentsModule( + axiosClient: AxiosInstance, + appId: string, + config: AgentsModuleConfig = {} +) { + let webSocketManager: AgentWebSocketManager | null = null; + let currentConversation: AgentConversation | null = null; + + // Initialize WebSocket if enabled + if (config.enableWebSocket) { + const socketUrl = config.socketUrl || "wss://base44.app/ws"; + // Extract token from axios client if available + const token = + axiosClient.defaults.headers.common?.Authorization?.toString().replace( + "Bearer ", + "" + ); + webSocketManager = new AgentWebSocketManager(socketUrl, appId, token); + } + + return { + /** + * List all conversations for the current user + */ + async listConversations( + filterParams?: FilterParams + ): Promise { + const response = await axiosClient.get( + `/apps/${appId}/agents/conversations`, + { + params: filterParams, + } + ); + return response as unknown as AgentConversation[]; + }, + + /** + * Get a specific conversation by ID + */ + async getConversation(conversationId: string): Promise { + const response = await axiosClient.get( + `/apps/${appId}/agents/conversations/${conversationId}` + ); + return response as unknown as AgentConversation; + }, + + /** + * Create a new agent conversation + */ + async createConversation( + payload: CreateConversationPayload + ): Promise { + const response = await axiosClient.post( + `/apps/${appId}/agents/conversations`, + payload + ); + return response as unknown as AgentConversation; + }, + + /** + * Update conversation metadata + */ + async updateConversation( + conversationId: string, + payload: UpdateConversationPayload + ): Promise { + const response = await axiosClient.put( + `/apps/${appId}/agents/conversations/${conversationId}`, + payload + ); + return response as unknown as AgentConversation; + }, + + /** + * Send a message to an agent and get response + */ + async sendMessage( + conversationId: string, + message: Omit + ): Promise { + // Update current conversation for WebSocket tracking + if (currentConversation?.id === conversationId) { + currentConversation.messages = [ + ...currentConversation.messages, + { ...message, id: "temp-" + Date.now() }, + ]; + } + + const response = await axiosClient.post( + `/apps/${appId}/agents/conversations/${conversationId}/messages`, + message + ); + return response as unknown as Message; + }, + + /** + * Delete a message from a conversation + */ + async deleteMessage( + conversationId: string, + messageId: string + ): Promise { + await axiosClient.delete( + `/apps/${appId}/agents/conversations/${conversationId}/messages/${messageId}` + ); + }, + + /** + * Subscribe to real-time updates for a conversation + * Requires WebSocket to be enabled in config + */ + subscribeToConversation( + conversationId: string, + onUpdate: (conversation: AgentConversation) => void + ): () => void { + if (!webSocketManager) { + throw new Error( + "WebSocket is not enabled. Set enableWebSocket: true in agents config" + ); + } + + // Connect WebSocket if not already connected + if (!webSocketManager.isConnected()) { + webSocketManager.connect().catch((error) => { + console.error("Failed to connect WebSocket:", error); + }); + } + + return webSocketManager.subscribe( + `/agent-conversations/${conversationId}`, + (data) => { + // Update current conversation reference + if (data.id === conversationId) { + currentConversation = data; + } + onUpdate(data); + } + ); + }, + + /** + * Get WebSocket connection status + */ + getWebSocketStatus(): { enabled: boolean; connected: boolean } { + return { + enabled: !!webSocketManager, + connected: webSocketManager?.isConnected() || false, + }; + }, + + /** + * Manually connect WebSocket + */ + async connectWebSocket(): Promise { + if (!webSocketManager) { + throw new Error( + "WebSocket is not enabled. Set enableWebSocket: true in agents config" + ); + } + await webSocketManager.connect(); + }, + + /** + * Disconnect WebSocket + */ + disconnectWebSocket(): void { + if (webSocketManager) { + webSocketManager.disconnect(); + } + }, + }; +} + +export type AgentsModule = ReturnType; diff --git a/tests/unit/agents.test.ts b/tests/unit/agents.test.ts new file mode 100644 index 0000000..03c7d24 --- /dev/null +++ b/tests/unit/agents.test.ts @@ -0,0 +1,301 @@ +import { describe, it, expect, vi, beforeEach, afterEach } from "vitest"; +import nock from "nock"; +import { createClient } from "../../src/index.js"; +import type { + Message, + AgentConversation, + CreateConversationPayload, +} from "../../src/modules/agents.js"; + +// Mock WebSocket - initially undefined to simulate server environment +let mockWebSocketClass: any = undefined; + +describe("Agents Module", () => { + let base44: ReturnType; + let scope: nock.Scope; + const appId = "test-app-id"; + const serverUrl = "https://api.base44.com"; + + beforeEach(() => { + vi.clearAllMocks(); + + // Reset WebSocket mock to undefined (simulating server environment) + global.WebSocket = mockWebSocketClass; + + // Create a new client for each test + base44 = createClient({ + serverUrl, + appId, + token: "test-token", + }); + + // Create a nock scope for mocking API calls + scope = nock(serverUrl); + + // Disable net connect to ensure all requests are mocked + nock.disableNetConnect(); + + // Enable request debugging for Nock + nock.emitter.on("no match", (req) => { + console.log(`Nock: No match for ${req.method} ${req.path}`); + console.log("Headers:", req.getHeaders()); + }); + }); + + afterEach(() => { + // Clean up WebSocket connections + if (base44.agents.getWebSocketStatus().enabled) { + base44.agents.disconnectWebSocket(); + } + + // Clean up any pending mocks + nock.cleanAll(); + nock.emitter.removeAllListeners("no match"); + nock.enableNetConnect(); + }); + + describe("listConversations", () => { + it("should fetch conversations with filter params", async () => { + const mockConversations: AgentConversation[] = [ + { + id: "1", + app_id: appId, + created_by_id: "user1", + agent_name: "test-agent", + messages: [], + metadata: {}, + }, + ]; + + scope + .get(`/api/apps/${appId}/agents/conversations`) + .query({ limit: 10, skip: 0 }) + .reply(function (uri, requestBody) { + console.log("Nock intercepted request:", uri); + console.log("Request body:", requestBody); + console.log("Returning:", mockConversations); + return [200, mockConversations]; + }); + + const filterParams = { limit: 10, skip: 0 }; + + + const result = await base44.agents.listConversations(filterParams); + + // Check if result is the expected value + expect(result).toEqual(mockConversations); + // expect(scope.isDone()).toBe(true); + }); + + it("should fetch conversations without filter params", async () => { + const mockConversations: AgentConversation[] = []; + + scope + .get(`/api/apps/${appId}/agents/conversations`) + .reply(200, mockConversations); + + const result = await base44.agents.listConversations(); + + expect(result).toEqual(mockConversations); + expect(scope.isDone()).toBe(true); + }); + }); + + describe("getConversation", () => { + it("should fetch a specific conversation", async () => { + const conversationId = "conv-123"; + const mockConversation: AgentConversation = { + id: conversationId, + app_id: appId, + created_by_id: "user1", + agent_name: "test-agent", + messages: [], + metadata: {}, + }; + + scope + .get(`/api/apps/${appId}/agents/conversations/${conversationId}`) + .reply(200, mockConversation); + + const result = await base44.agents.getConversation(conversationId); + + expect(result).toEqual(mockConversation); + expect(scope.isDone()).toBe(true); + }); + }); + + describe("createConversation", () => { + it("should create a new conversation", async () => { + const payload: CreateConversationPayload = { + agent_name: "test-agent", + metadata: { key: "value" }, + }; + + const mockConversation: AgentConversation = { + id: "new-conv-123", + app_id: appId, + created_by_id: "user1", + agent_name: payload.agent_name, + messages: [], + metadata: payload.metadata || {}, + }; + + scope + .post( + `/api/apps/${appId}/agents/conversations`, + payload as Record + ) + .reply(200, mockConversation); + + const result = await base44.agents.createConversation(payload); + + expect(result).toEqual(mockConversation); + expect(scope.isDone()).toBe(true); + }); + }); + + describe("updateConversation", () => { + it("should update conversation metadata", async () => { + const conversationId = "conv-123"; + const payload = { metadata: { updated: true } }; + + const mockConversation: AgentConversation = { + id: conversationId, + app_id: appId, + created_by_id: "user1", + agent_name: "test-agent", + messages: [], + metadata: payload.metadata, + }; + + scope + .put( + `/api/apps/${appId}/agents/conversations/${conversationId}`, + payload + ) + .reply(200, mockConversation); + + const result = await base44.agents.updateConversation( + conversationId, + payload + ); + + expect(result).toEqual(mockConversation); + expect(scope.isDone()).toBe(true); + }); + }); + + describe("sendMessage", () => { + it("should send a message to an agent", async () => { + const conversationId = "conv-123"; + const message: Omit = { + role: "user", + content: "Hello, agent!", + metadata: {}, + }; + + const mockResponse: Message = { + id: "msg-123", + ...message, + }; + + scope + .post( + `/api/apps/${appId}/agents/conversations/${conversationId}/messages`, + message + ) + .reply(200, mockResponse); + + const result = await base44.agents.sendMessage(conversationId, message); + + expect(result).toEqual(mockResponse); + expect(scope.isDone()).toBe(true); + }); + }); + + describe("deleteMessage", () => { + it("should delete a message from a conversation", async () => { + const conversationId = "conv-123"; + const messageId = "msg-123"; + + scope + .delete( + `/api/apps/${appId}/agents/conversations/${conversationId}/messages/${messageId}` + ) + .reply(200); + + await base44.agents.deleteMessage(conversationId, messageId); + + expect(scope.isDone()).toBe(true); + }); + }); + + describe("WebSocket functionality", () => { + it("should throw error when WebSocket is not enabled", () => { + expect(() => { + base44.agents.subscribeToConversation("conv-123", () => {}); + }).toThrow( + "WebSocket is not enabled. Set enableWebSocket: true in agents config" + ); + }); + + it("should return correct WebSocket status when disabled", () => { + const status = base44.agents.getWebSocketStatus(); + expect(status).toEqual({ + enabled: false, + connected: false, + }); + }); + + it("should throw error when trying to connect WebSocket when not enabled", async () => { + await expect(base44.agents.connectWebSocket()).rejects.toThrow( + "WebSocket is not enabled. Set enableWebSocket: true in agents config" + ); + }); + }); + + describe("WebSocket enabled", () => { + let base44WithWS: ReturnType; + + beforeEach(() => { + // Mock WebSocket for browser environment tests + global.WebSocket = vi.fn(() => ({ + readyState: 0, // CONNECTING initially + send: vi.fn(), + close: vi.fn(), + addEventListener: vi.fn(), + removeEventListener: vi.fn(), + onopen: null, + onmessage: null, + onclose: null, + onerror: null, + })) as any; + + // Create client with WebSocket enabled + base44WithWS = createClient({ + serverUrl, + appId, + token: "test-token", + agents: { + enableWebSocket: true, + socketUrl: "wss://test.example.com/ws", + }, + }); + }); + + afterEach(() => { + base44WithWS.agents.disconnectWebSocket(); + // Reset WebSocket mock + global.WebSocket = mockWebSocketClass; + }); + + it("should return correct WebSocket status when enabled", () => { + const status = base44WithWS.agents.getWebSocketStatus(); + expect(status.enabled).toBe(true); + // Don't test connected status as it depends on mock WebSocket implementation + }); + + + + }); +});