computer-agents 0.7.1 → 1.0.1

package/dist/ComputerAgentsClient.d.ts

@@ -0,0 +1,357 @@
+/**
+ * ComputerAgentsClient - The Official Computer Agents SDK
+ *
+ * A clean, simple SDK for interacting with the Computer Agents Cloud API.
+ * This SDK provides typed access to all API resources with streaming support.
+ *
+ * @example
+ * ```typescript
+ * import { ComputerAgentsClient } from 'computer-agents';
+ *
+ * const client = new ComputerAgentsClient({
+ *   apiKey: process.env.COMPUTER_AGENTS_API_KEY
+ * });
+ *
+ * // Execute a task (simplest usage)
+ * const result = await client.run('Create a REST API with Flask', {
+ *   environmentId: 'env_xxx',
+ *   onEvent: (event) => console.log(event.type)
+ * });
+ *
+ * // Or use the thread API for multi-turn conversations
+ * const thread = await client.threads.create({
+ *   environmentId: 'env_xxx'
+ * });
+ *
+ * const response = await client.threads.sendMessage(thread.id, {
+ *   content: 'Create a REST API',
+ *   onEvent: (event) => console.log(event)
+ * });
+ * ```
+ */
+import { ApiClientError } from './cloud/ApiClient';
+import type { ApiClientConfig } from './cloud/ApiClient';
+import { EnvironmentsResource, ThreadsResource, AgentsResource, BudgetResource, BillingResource, SchedulesResource, GitResource, FilesResource } from './cloud/resources';
+import type { HealthCheck, Metrics, Project, Environment, MessageStreamEvent } from './cloud/types';
+export { ApiClientError };
+export type { ApiClientConfig };
+/**
+ * Configuration for ComputerAgentsClient
+ */
+export interface ComputerAgentsClientConfig {
+    /**
+     * API key for authentication (required)
+     * Can also be set via COMPUTER_AGENTS_API_KEY environment variable
+     */
+    apiKey?: string;
+    /**
+     * Base URL for the API
+     * @default 'https://api.computer-agents.com'
+     */
+    baseUrl?: string;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Request timeout in milliseconds
+     * @default 60000 (1 minute)
+     */
+    timeout?: number;
+}
+/**
+ * Options for the run() convenience method
+ */
+export interface RunOptions {
+    /**
+     * Environment ID to execute in (required)
+     */
+    environmentId: string;
+    /**
+     * Thread ID to continue (optional - creates new thread if not provided)
+     */
+    threadId?: string;
+    /**
+     * Agent configuration override
+     */
+    agentConfig?: {
+        model?: string;
+        instructions?: string;
+        reasoningEffort?: 'none' | 'low' | 'medium' | 'high';
+    };
+    /**
+     * Callback for streaming events
+     */
+    onEvent?: (event: MessageStreamEvent) => void;
+    /**
+     * Execution timeout in milliseconds
+     * @default 600000 (10 minutes)
+     */
+    timeout?: number;
+}
+/**
+ * Result from the run() method
+ */
+export interface RunResult {
+    /**
+     * The final response content
+     */
+    content: string;
+    /**
+     * The thread ID (for continuing conversations)
+     */
+    threadId: string;
+    /**
+     * Run details if available
+     */
+    run?: {
+        id: string;
+        status: string;
+        tokens?: {
+            input: number;
+            output: number;
+        };
+    };
+}
+/**
+ * ComputerAgentsClient - Complete SDK for Computer Agents Cloud API
+ *
+ * This is the main entry point for the SDK. It provides access to all API
+ * resources through typed methods:
+ *
+ * - `threads` - Conversation management with SSE streaming
+ * - `environments` - Environment configuration and container lifecycle
+ * - `agents` - Agent configuration
+ * - `files` - File management (via projects resource)
+ * - `schedules` - Scheduled task management
+ * - `billing` - Budget and usage tracking
+ * - `git` - Git operations on workspaces
+ *
+ * For simple use cases, use the `run()` method which handles thread
+ * creation and streaming automatically.
+ */
+export declare class ComputerAgentsClient {
+    /**
+     * Thread (conversation) management
+     *
+     * Create threads for multi-turn conversations with agents.
+     * Use sendMessage() for SSE streaming execution.
+     *
+     * @example
+     * ```typescript
+     * const thread = await client.threads.create({
+     *   environmentId: 'env_xxx'
+     * });
+     *
+     * const result = await client.threads.sendMessage(thread.id, {
+     *   content: 'Fix the TypeScript errors',
+     *   onEvent: (event) => console.log(event)
+     * });
+     * ```
+     */
+    readonly threads: ThreadsResource;
+    /**
+     * Environment management
+     *
+     * Create and manage isolated execution environments.
+     * Environments define variables, secrets, MCP servers, and setup scripts.
+     *
+     * @example
+     * ```typescript
+     * const env = await client.environments.create({
+     *   name: 'production',
+     *   internetAccess: true
+     * });
+     * ```
+     */
+    readonly environments: EnvironmentsResource;
+    /**
+     * Agent configuration
+     *
+     * Create and manage agent configurations with models, instructions, and skills.
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.agents.create({
+     *   name: 'Code Assistant',
+     *   model: 'gpt-4o',
+     *   instructions: 'You are a helpful coding assistant.'
+     * });
+     * ```
+     */
+    readonly agents: AgentsResource;
+    /**
+     * File operations
+     *
+     * Upload, download, and manage files in environment workspaces.
+     * Files are scoped to environments.
+     *
+     * @example
+     * ```typescript
+     * // List files in an environment
+     * const files = await client.files.listFiles('env_xxx');
+     *
+     * // Upload a file
+     * await client.files.uploadFile({
+     *   environmentId: 'env_xxx',
+     *   filename: 'app.py',
+     *   path: 'src',
+     *   content: 'print("hello")'
+     * });
+     *
+     * // Download a file
+     * const content = await client.files.getFile('env_xxx', 'src/app.py');
+     *
+     * // Delete a file
+     * await client.files.deleteFile('env_xxx', 'src/app.py');
+     *
+     * // Move/rename a file
+     * await client.files.moveFile({
+     *   environmentId: 'env_xxx',
+     *   sourcePath: 'old.py',
+     *   destPath: 'new.py'
+     * });
+     * ```
+     */
+    readonly files: FilesResource;
+    /**
+     * Scheduled tasks
+     *
+     * Create and manage scheduled task execution.
+     *
+     * @example
+     * ```typescript
+     * const schedule = await client.schedules.create({
+     *   name: 'Daily Report',
+     *   agentId: 'agent_xxx',
+     *   agentName: 'Reporter',
+     *   task: 'Generate daily report',
+     *   scheduleType: 'recurring',
+     *   cronExpression: '0 9 * * *'
+     * });
+     * ```
+     */
+    readonly schedules: SchedulesResource;
+    /**
+     * Budget management
+     *
+     * Check and manage execution budgets.
+     *
+     * @example
+     * ```typescript
+     * const status = await client.budget.getStatus();
+     * const canRun = await client.budget.canExecute();
+     * ```
+     */
+    readonly budget: BudgetResource;
+    /**
+     * Billing and usage
+     *
+     * Access billing records and usage statistics.
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.billing.getStats({ period: 'month' });
+     * const records = await client.billing.listRecords({ limit: 10 });
+     * ```
+     */
+    readonly billing: BillingResource;
+    /**
+     * Git operations
+     *
+     * Perform git operations on cloud workspaces.
+     *
+     * @example
+     * ```typescript
+     * const diff = await client.git.diff('env_xxx');
+     * await client.git.commit('env_xxx', { message: 'Add feature' });
+     * await client.git.push('env_xxx');
+     * ```
+     */
+    readonly git: GitResource;
+    constructor(config?: ComputerAgentsClientConfig);
+    /**
+     * Execute a task with automatic thread management
+     *
+     * This is the simplest way to run an agent task. It handles:
+     * - Creating a thread (if threadId not provided)
+     * - Sending the message with SSE streaming
+     * - Returning the result with thread ID for follow-ups
+     *
+     * @param task - The task to execute (e.g., "Create a REST API with Flask")
+     * @param options - Execution options including environmentId (required)
+     * @returns The execution result with content and thread ID
+     *
+     * @example
+     * ```typescript
+     * // Simple one-shot execution
+     * const result = await client.run('Create hello.py', {
+     *   environmentId: 'env_xxx'
+     * });
+     * console.log(result.content);
+     *
+     * // With streaming progress
+     * const result = await client.run('Build a REST API', {
+     *   environmentId: 'env_xxx',
+     *   onEvent: (event) => {
+     *     if (event.type === 'response.item.completed') {
+     *       console.log(event.item);
+     *     }
+     *   }
+     * });
+     *
+     * // Continue the conversation
+     * const followUp = await client.run('Add authentication', {
+     *   environmentId: 'env_xxx',
+     *   threadId: result.threadId
+     * });
+     * ```
+     */
+    run(task: string, options: RunOptions): Promise<RunResult>;
+    /**
+     * Quick setup with default environment
+     *
+     * Creates a default environment if none exists, returning both
+     * the project and environment ready for execution.
+     *
+     * @example
+     * ```typescript
+     * const { project, environment } = await client.quickSetup({
+     *   internetAccess: true
+     * });
+     *
+     * // Ready to execute
+     * await client.run('Hello world!', {
+     *   environmentId: environment.id
+     * });
+     * ```
+     */
+    quickSetup(options?: {
+        internetAccess?: boolean;
+        environmentName?: string;
+    }): Promise<{
+        project: Project;
+        environment: Environment;
+    }>;
+    /**
+     * Check API health status
+     */
+    health(): Promise<HealthCheck>;
+    /**
+     * Get API metrics
+     */
+    metrics(): Promise<Metrics>;
+    /**
+     * Get API base URL
+     */
+    getBaseUrl(): string;
+}
+/**
+ * @deprecated Use ComputerAgentsClient instead
+ */
+export { ComputerAgentsClient as CloudClient };
+/**
+ * @deprecated Use ComputerAgentsClient instead
+ */
+export { ComputerAgentsClient as TestbaseClient };

package/dist/ComputerAgentsClient.js

@@ -0,0 +1,359 @@
+"use strict";
+/**
+ * ComputerAgentsClient - The Official Computer Agents SDK
+ *
+ * A clean, simple SDK for interacting with the Computer Agents Cloud API.
+ * This SDK provides typed access to all API resources with streaming support.
+ *
+ * @example
+ * ```typescript
+ * import { ComputerAgentsClient } from 'computer-agents';
+ *
+ * const client = new ComputerAgentsClient({
+ *   apiKey: process.env.COMPUTER_AGENTS_API_KEY
+ * });
+ *
+ * // Execute a task (simplest usage)
+ * const result = await client.run('Create a REST API with Flask', {
+ *   environmentId: 'env_xxx',
+ *   onEvent: (event) => console.log(event.type)
+ * });
+ *
+ * // Or use the thread API for multi-turn conversations
+ * const thread = await client.threads.create({
+ *   environmentId: 'env_xxx'
+ * });
+ *
+ * const response = await client.threads.sendMessage(thread.id, {
+ *   content: 'Create a REST API',
+ *   onEvent: (event) => console.log(event)
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TestbaseClient = exports.CloudClient = exports.ComputerAgentsClient = exports.ApiClientError = void 0;
+const ApiClient_1 = require("./cloud/ApiClient");
+Object.defineProperty(exports, "ApiClientError", { enumerable: true, get: function () { return ApiClient_1.ApiClientError; } });
+const resources_1 = require("./cloud/resources");
+/**
+ * ComputerAgentsClient - Complete SDK for Computer Agents Cloud API
+ *
+ * This is the main entry point for the SDK. It provides access to all API
+ * resources through typed methods:
+ *
+ * - `threads` - Conversation management with SSE streaming
+ * - `environments` - Environment configuration and container lifecycle
+ * - `agents` - Agent configuration
+ * - `files` - File management (via projects resource)
+ * - `schedules` - Scheduled task management
+ * - `billing` - Budget and usage tracking
+ * - `git` - Git operations on workspaces
+ *
+ * For simple use cases, use the `run()` method which handles thread
+ * creation and streaming automatically.
+ */
+class ComputerAgentsClient {
+    /**
+     * Low-level API client (for advanced usage)
+     * @internal
+     */
+    api;
+    /**
+     * Thread (conversation) management
+     *
+     * Create threads for multi-turn conversations with agents.
+     * Use sendMessage() for SSE streaming execution.
+     *
+     * @example
+     * ```typescript
+     * const thread = await client.threads.create({
+     *   environmentId: 'env_xxx'
+     * });
+     *
+     * const result = await client.threads.sendMessage(thread.id, {
+     *   content: 'Fix the TypeScript errors',
+     *   onEvent: (event) => console.log(event)
+     * });
+     * ```
+     */
+    threads;
+    /**
+     * Environment management
+     *
+     * Create and manage isolated execution environments.
+     * Environments define variables, secrets, MCP servers, and setup scripts.
+     *
+     * @example
+     * ```typescript
+     * const env = await client.environments.create({
+     *   name: 'production',
+     *   internetAccess: true
+     * });
+     * ```
+     */
+    environments;
+    /**
+     * Agent configuration
+     *
+     * Create and manage agent configurations with models, instructions, and skills.
+     *
+     * @example
+     * ```typescript
+     * const agent = await client.agents.create({
+     *   name: 'Code Assistant',
+     *   model: 'gpt-4o',
+     *   instructions: 'You are a helpful coding assistant.'
+     * });
+     * ```
+     */
+    agents;
+    /**
+     * File operations
+     *
+     * Upload, download, and manage files in environment workspaces.
+     * Files are scoped to environments.
+     *
+     * @example
+     * ```typescript
+     * // List files in an environment
+     * const files = await client.files.listFiles('env_xxx');
+     *
+     * // Upload a file
+     * await client.files.uploadFile({
+     *   environmentId: 'env_xxx',
+     *   filename: 'app.py',
+     *   path: 'src',
+     *   content: 'print("hello")'
+     * });
+     *
+     * // Download a file
+     * const content = await client.files.getFile('env_xxx', 'src/app.py');
+     *
+     * // Delete a file
+     * await client.files.deleteFile('env_xxx', 'src/app.py');
+     *
+     * // Move/rename a file
+     * await client.files.moveFile({
+     *   environmentId: 'env_xxx',
+     *   sourcePath: 'old.py',
+     *   destPath: 'new.py'
+     * });
+     * ```
+     */
+    files;
+    /**
+     * Scheduled tasks
+     *
+     * Create and manage scheduled task execution.
+     *
+     * @example
+     * ```typescript
+     * const schedule = await client.schedules.create({
+     *   name: 'Daily Report',
+     *   agentId: 'agent_xxx',
+     *   agentName: 'Reporter',
+     *   task: 'Generate daily report',
+     *   scheduleType: 'recurring',
+     *   cronExpression: '0 9 * * *'
+     * });
+     * ```
+     */
+    schedules;
+    /**
+     * Budget management
+     *
+     * Check and manage execution budgets.
+     *
+     * @example
+     * ```typescript
+     * const status = await client.budget.getStatus();
+     * const canRun = await client.budget.canExecute();
+     * ```
+     */
+    budget;
+    /**
+     * Billing and usage
+     *
+     * Access billing records and usage statistics.
+     *
+     * @example
+     * ```typescript
+     * const stats = await client.billing.getStats({ period: 'month' });
+     * const records = await client.billing.listRecords({ limit: 10 });
+     * ```
+     */
+    billing;
+    /**
+     * Git operations
+     *
+     * Perform git operations on cloud workspaces.
+     *
+     * @example
+     * ```typescript
+     * const diff = await client.git.diff('env_xxx');
+     * await client.git.commit('env_xxx', { message: 'Add feature' });
+     * await client.git.push('env_xxx');
+     * ```
+     */
+    git;
+    /**
+     * Run tracking (internal)
+     * @internal
+     */
+    runs;
+    /**
+     * Project access (internal - use files for file operations)
+     * @internal
+     */
+    projects;
+    constructor(config = {}) {
+        // Get API key from config or environment variable
+        const apiKey = config.apiKey
+            || process.env.COMPUTER_AGENTS_API_KEY
+            || process.env.TESTBASE_API_KEY;
+        if (!apiKey) {
+            throw new Error('ComputerAgentsClient requires an API key. Provide it via:\n' +
+                '1. Constructor: new ComputerAgentsClient({ apiKey: "..." })\n' +
+                '2. Environment variable: COMPUTER_AGENTS_API_KEY');
+        }
+        // Create low-level API client
+        this.api = new ApiClient_1.ApiClient({
+            apiKey,
+            baseUrl: config.baseUrl,
+            timeout: config.timeout,
+            debug: config.debug,
+        });
+        // Initialize all resource managers
+        this.threads = new resources_1.ThreadsResource(this.api);
+        this.environments = new resources_1.EnvironmentsResource(this.api);
+        this.agents = new resources_1.AgentsResource(this.api);
+        this.files = new resources_1.FilesResource(this.api);
+        this.schedules = new resources_1.SchedulesResource(this.api);
+        this.budget = new resources_1.BudgetResource(this.api);
+        this.billing = new resources_1.BillingResource(this.api);
+        this.git = new resources_1.GitResource(this.api);
+        this.runs = new resources_1.RunsResource(this.api);
+        this.projects = new resources_1.ProjectsResource(this.api);
+    }
+    // =========================================================================
+    // High-Level Convenience Methods
+    // =========================================================================
+    /**
+     * Execute a task with automatic thread management
+     *
+     * This is the simplest way to run an agent task. It handles:
+     * - Creating a thread (if threadId not provided)
+     * - Sending the message with SSE streaming
+     * - Returning the result with thread ID for follow-ups
+     *
+     * @param task - The task to execute (e.g., "Create a REST API with Flask")
+     * @param options - Execution options including environmentId (required)
+     * @returns The execution result with content and thread ID
+     *
+     * @example
+     * ```typescript
+     * // Simple one-shot execution
+     * const result = await client.run('Create hello.py', {
+     *   environmentId: 'env_xxx'
+     * });
+     * console.log(result.content);
+     *
+     * // With streaming progress
+     * const result = await client.run('Build a REST API', {
+     *   environmentId: 'env_xxx',
+     *   onEvent: (event) => {
+     *     if (event.type === 'response.item.completed') {
+     *       console.log(event.item);
+     *     }
+     *   }
+     * });
+     *
+     * // Continue the conversation
+     * const followUp = await client.run('Add authentication', {
+     *   environmentId: 'env_xxx',
+     *   threadId: result.threadId
+     * });
+     * ```
+     */
+    async run(task, options) {
+        // Create or reuse thread
+        let threadId = options.threadId;
+        if (!threadId) {
+            const thread = await this.threads.create({
+                environmentId: options.environmentId,
+            });
+            threadId = thread.id;
+        }
+        // Send message and stream response
+        const result = await this.threads.sendMessage(threadId, {
+            content: task,
+            agentConfig: options.agentConfig,
+            onEvent: options.onEvent,
+            timeout: options.timeout,
+        });
+        return {
+            content: result.content,
+            threadId,
+            run: result.run,
+        };
+    }
+    /**
+     * Quick setup with default environment
+     *
+     * Creates a default environment if none exists, returning both
+     * the project and environment ready for execution.
+     *
+     * @example
+     * ```typescript
+     * const { project, environment } = await client.quickSetup({
+     *   internetAccess: true
+     * });
+     *
+     * // Ready to execute
+     * await client.run('Hello world!', {
+     *   environmentId: environment.id
+     * });
+     * ```
+     */
+    async quickSetup(options = {}) {
+        // Get the project (bound to API key)
+        const project = await this.projects.get();
+        // Check for existing default environment
+        const environments = await this.environments.list();
+        let environment = environments.find(e => e.isDefault);
+        // Create default environment if none exists
+        if (!environment) {
+            environment = await this.environments.create({
+                name: options.environmentName || 'default',
+                internetAccess: options.internetAccess ?? true,
+                isDefault: true,
+            });
+        }
+        return { project, environment };
+    }
+    // =========================================================================
+    // Health & Monitoring
+    // =========================================================================
+    /**
+     * Check API health status
+     */
+    async health() {
+        return this.api.get('/health');
+    }
+    /**
+     * Get API metrics
+     */
+    async metrics() {
+        return this.api.get('/metrics');
+    }
+    /**
+     * Get API base URL
+     */
+    getBaseUrl() {
+        return this.api.getBaseUrl();
+    }
+}
+exports.ComputerAgentsClient = ComputerAgentsClient;
+exports.CloudClient = ComputerAgentsClient;
+exports.TestbaseClient = ComputerAgentsClient;
+//# sourceMappingURL=ComputerAgentsClient.js.map