@voidrun/sdk 0.0.15 → 0.0.17

package/README.md

@@ -12,6 +12,7 @@ A powerful, type-safe SDK for interacting with VoidRun AI Sandboxes. Execute cod
 - 📁 **File Operations** - Create, read, delete, compress, and extract files
 - 👀 **File Watching** - Monitor file changes in real-time via WebSocket
 - 💻 **Pseudo-Terminal (PTY)** - Interactive terminal sessions (ephemeral & persistent)
+- 🧠 **Code Interpreter** - Easy multi-language code execution (Python, JavaScript, Bash, etc.)
 - 🔐 **Type-Safe** - Full TypeScript support with generated types from OpenAPI
 - ⚡ **WebSocket Support** - Real-time streaming for PTY, file watches, and execution
 - 🎯 **Promise-Based** - Modern async/await API
@@ -41,7 +42,7 @@ export API_KEY="your-api-key-here"
 ### Basic Usage
 
 ```typescript
-import { VoidRun } from '@voidrun/sdk';
+import { VoidRun } from "@voidrun/sdk";
 
 // Initialize the SDK
 const vr = new VoidRun({});
@@ -66,8 +67,8 @@ An isolated environment where you can execute code, manage files, and run termin
 ```typescript
 // Create a sandbox
 const sandbox = await vr.createSandbox({
-  mem: 1024,    // Memory in MB (optional, has defaults)
-  cpu: 1        // CPU cores (optional, has defaults)
+  mem: 1024, // Memory in MB (optional, has defaults)
+  cpu: 1, // CPU cores (optional, has defaults)
 });
 
 // List all sandboxes
@@ -86,52 +87,85 @@ await sandbox.remove();
 Execute commands and capture output, errors, and exit codes.
 
 ```typescript
-const result = await sandbox.exec({ command: 'ls -la /home' });
+const result = await sandbox.exec({ command: "ls -la /home" });
 
-console.log(result.data?.stdout);    // stdout
-console.log(result.data?.stderr);    // stderr
-console.log(result.data?.exitCode);  // exit code
+console.log(result.data?.stdout); // stdout
+console.log(result.data?.stderr); // stderr
+console.log(result.data?.exitCode); // exit code
 ```
 
+### Code Interpreter
+
+Execute code in multiple programming languages with a simple, intuitive API (similar to e2b or Daytona).
+
+```typescript
+// Initialize interpreter with your language
+await sandbox.interpreter.initialize("python");
+
+// Execute code
+const result = await sandbox.interpreter.execute("print(2 + 2)");
+if (result.success) {
+  console.log(result.output); // "4"
+}
+
+// Execute multiple snippets
+const results = await sandbox.interpreter.executeMultiple([
+  "x = 10",
+  "y = 20",
+  "print(x + y)",
+]);
+
+// Switch languages
+await sandbox.interpreter.reset("javascript");
+const jsResult = await sandbox.interpreter.execute("console.log(2 + 2)");
+
+// Clean up
+await sandbox.interpreter.close();
+```
+
+Supported languages: **Python**, **JavaScript**, **Node.js**, **Bash**, **Go**, **Ruby**, **Java**, **C#**
+
+See [Code Interpreter API](./CODE_INTERPRETER_API.md) for comprehensive documentation.
+
 ### File Operations
 
 Create, read, update, and manage files in the sandbox.
 
 ```typescript
 // Create a file
-await sandbox.fs.createFile('/tmp/hello.txt');
+await sandbox.fs.createFile("/tmp/hello.txt");
 
 // Upload content to file
-await sandbox.fs.uploadFile('/tmp/hello.txt', 'Hello, World!');
+await sandbox.fs.uploadFile("/tmp/hello.txt", "Hello, World!");
 
 // Read a file
-const buffer = await sandbox.fs.downloadFile('/tmp/hello.txt');
+const buffer = await sandbox.fs.downloadFile("/tmp/hello.txt");
 const content = buffer.toString();
 
 // Delete a file
-await sandbox.fs.deleteFile('/tmp/hello.txt');
+await sandbox.fs.deleteFile("/tmp/hello.txt");
 
 // List directory
-const result = await sandbox.fs.listFiles('/tmp');
+const result = await sandbox.fs.listFiles("/tmp");
 const files = result.data?.files;
 
 // Get file stats
-const stats = await sandbox.fs.statFile('/tmp/hello.txt');
+const stats = await sandbox.fs.statFile("/tmp/hello.txt");
 
 // Compress files
-await sandbox.fs.compressFile('/tmp', 'tar.gz');
+await sandbox.fs.compressFile("/tmp", "tar.gz");
 
 // Extract archive
-await sandbox.fs.extractArchive('/tmp/archive.tar.gz', '/tmp/extracted');
+await sandbox.fs.extractArchive("/tmp/archive.tar.gz", "/tmp/extracted");
 
 // Create directory
-await sandbox.fs.createDirectory('/tmp/mydir');
+await sandbox.fs.createDirectory("/tmp/mydir");
 
 // Move file
-await sandbox.fs.moveFile('/tmp/file.txt', '/tmp/newfile.txt');
+await sandbox.fs.moveFile("/tmp/file.txt", "/tmp/newfile.txt");
 
 // Copy file
-await sandbox.fs.copyFile('/tmp/file.txt', '/tmp/copy.txt');
+await sandbox.fs.copyFile("/tmp/file.txt", "/tmp/copy.txt");
 ```
 
 ### File Watching
@@ -139,14 +173,14 @@ await sandbox.fs.copyFile('/tmp/file.txt', '/tmp/copy.txt');
 Monitor file changes in real-time.
 
 ```typescript
-const watcher = await sandbox.fs.watch('/app', {
+const watcher = await sandbox.fs.watch("/app", {
   recursive: true,
   onEvent: (event) => {
     console.log(`File changed: ${event.path} - ${event.type}`);
   },
   onError: (err) => {
-    console.error('Watch error:', err);
-  }
+    console.error("Watch error:", err);
+  },
 });
 
 // Stop watching
@@ -166,13 +200,13 @@ const pty = await sandbox.pty.connect({
     process.stdout.write(data);
   },
   onError: (err) => {
-    console.error('PTY error:', err);
-  }
+    console.error("PTY error:", err);
+  },
 });
 
 // Send commands
 pty.write('echo "Hello"\n');
-pty.write('pwd\n');
+pty.write("pwd\n");
 
 // Close connection
 pty.close();
@@ -190,7 +224,7 @@ const pty = await sandbox.pty.connect({
   sessionId,
   onData: (data) => {
     process.stdout.write(data);
-  }
+  },
 });
 
 // Send commands
@@ -204,7 +238,7 @@ const reconnected = await sandbox.pty.connect({
   sessionId,
   onData: (data) => {
     process.stdout.write(data); // Includes buffered output
-  }
+  },
 });
 ```
 
@@ -215,18 +249,18 @@ Run commands with automatic prompt detection:
 ```typescript
 const pty = await sandbox.pty.connect({ sessionId });
 
-const output = await pty.runCommand('echo $SHELL', {
+const output = await pty.runCommand("echo $SHELL", {
   timeout: 5000,
-  prompt: /[#$] $/  // Regex to detect shell prompt
+  prompt: /[#$] $/, // Regex to detect shell prompt
 });
 
-console.log('Output:', output);
+console.log("Output:", output);
 ```
 
 #### Resize Terminal
 
 ```typescript
-pty.resize(80, 24);  // columns, rows
+pty.resize(80, 24); // columns, rows
 ```
 
 #### Session Management
@@ -250,11 +284,13 @@ new VoidRun(options?: VoidRunOptions)
 ```
 
 **Options:**
+
 - `apiKey?: string` - API key (defaults to `process.env.API_KEY`)
 - `baseUrl?: string` - Base API URL (defaults to `process.env.VOIDRUN_BASE_URL`)
 - `orgId?: string` - Organization ID (optional)
 
 **Methods:**
+
 - `createSandbox(options: SandboxOptions)` - Create a new sandbox
   - `name?: string` - Sandbox name
   - `templateId?: string` - Template ID
@@ -273,6 +309,7 @@ new VoidRun(options?: VoidRunOptions)
 Represents an isolated sandbox environment.
 
 **Properties:**
+
 - `id: string` - Sandbox ID
 - `name: string` - Sandbox name
 - `cpu: number` - CPU cores
@@ -286,6 +323,7 @@ Represents an isolated sandbox environment.
 - `pty: PTY` - PTY interface
 
 **Methods:**
+
 - `exec(request: ExecRequest)` - Execute a command
   - `request.command: string` - Command to execute
   - `request.cwd?: string` - Working directory (optional)
@@ -295,6 +333,7 @@ Represents an isolated sandbox environment.
 - `info()` - Get sandbox information
 
 **Exec Response:**
+
 ```typescript
 {
   data?: {
@@ -310,6 +349,7 @@ Represents an isolated sandbox environment.
 Manage files and directories.
 
 **Methods:**
+
 - `createFile(path: string)` - Create a file
 - `uploadFile(path: string, content: string)` - Upload file content
 - `uploadFileStream(path: string, stream: ReadableStream)` - Upload file as stream
@@ -335,6 +375,7 @@ Manage files and directories.
 Monitor file changes in real-time.
 
 **Methods:**
+
 - `watch(path: string, options: FileWatchOptions)` - Start watching a path
   - `recursive?: boolean` - Watch subdirectories
   - `onEvent(event: FileChangeEvent)` - Called on file change
@@ -342,6 +383,7 @@ Monitor file changes in real-time.
   - `onClose()` - Called when watcher closes (optional)
 
 **Watcher Methods:**
+
 - `close()` - Stop watching
 
 ### PTY Interface
@@ -349,6 +391,7 @@ Monitor file changes in real-time.
 Pseudo-terminal operations.
 
 **Methods:**
+
 - `list()` - List active sessions
 - `createSession()` - Create a persistent session
 - `connect(options: PtyOptions)` - Connect to PTY
@@ -359,6 +402,7 @@ Pseudo-terminal operations.
 - `deleteSession(sessionId: string)` - Delete a session
 
 **PtySession Methods:**
+
 - `write(data: string)` - Send data
 - `runCommand(cmd: string, options: RunCommandOptions)` - Execute with prompt detection
 - `resize(cols: number, rows: number)` - Resize terminal
@@ -369,20 +413,23 @@ Pseudo-terminal operations.
 ### Execute Python Script
 
 ```typescript
-import { VoidRun } from '@voidrun/sdk';
+import { VoidRun } from "@voidrun/sdk";
 
 const vr = new VoidRun({});
 const sandbox = await vr.createSandbox({ mem: 1024, cpu: 1 });
 
 // Create Python script
-await sandbox.fs.createFile('/tmp/script.py');
-await sandbox.fs.uploadFile('/tmp/script.py', `
+await sandbox.fs.createFile("/tmp/script.py");
+await sandbox.fs.uploadFile(
+  "/tmp/script.py",
+  `
 import sys
 print("Python version:", sys.version)
 print("Hello from Python!")
-`);
+`,
+);
 
-const result = await sandbox.exec({ command: 'python3 /tmp/script.py' });
+const result = await sandbox.exec({ command: "python3 /tmp/script.py" });
 console.log(result.data?.stdout);
 
 await sandbox.remove();
@@ -394,14 +441,14 @@ await sandbox.remove();
 const sandbox = await vr.createSandbox({ mem: 1024, cpu: 1 });
 
 // Watch for TypeScript file changes
-const watcher = await sandbox.fs.watch('/app/src', {
+const watcher = await sandbox.fs.watch("/app/src", {
   recursive: true,
   onEvent: async (event) => {
     console.log(`File ${event.type}: ${event.path}`);
-    
+
     // Auto-compile on change
-    await sandbox.exec({ command: 'npm run build' });
-  }
+    await sandbox.exec({ command: "npm run build" });
+  },
 });
 
 // Clean up
@@ -415,20 +462,20 @@ const sandbox = await vr.createSandbox({ mem: 2048, cpu: 2 });
 
 // Upload source code
 const sourceCode = `console.log('Hello World');`;
-await sandbox.fs.createFile('/app/main.js');
-await sandbox.fs.uploadFile('/app/main.js', sourceCode);
+await sandbox.fs.createFile("/app/main.js");
+await sandbox.fs.uploadFile("/app/main.js", sourceCode);
 
 // Install dependencies
-let result = await sandbox.exec({ command: 'npm install' });
-if (result.data?.exitCode !== 0) throw new Error('Install failed');
+let result = await sandbox.exec({ command: "npm install" });
+if (result.data?.exitCode !== 0) throw new Error("Install failed");
 
 // Run tests
-result = await sandbox.exec({ command: 'npm test' });
-console.log('Test output:', result.data?.stdout);
+result = await sandbox.exec({ command: "npm test" });
+console.log("Test output:", result.data?.stdout);
 
 // Build
-result = await sandbox.exec({ command: 'npm run build' });
-console.log('Build output:', result.data?.stdout);
+result = await sandbox.exec({ command: "npm run build" });
+console.log("Build output:", result.data?.stdout);
 
 await sandbox.remove();
 ```
@@ -445,18 +492,18 @@ const sessionId = sessionResp.data?.sessionId;
 const pty = await sandbox.pty.connect({
   sessionId,
   onData: (data) => process.stdout.write(data),
-  onClose: () => console.log('Shell closed')
+  onClose: () => console.log("Shell closed"),
 });
 
 // Interactive commands
-pty.write('npm init -y\n');
-await new Promise(r => setTimeout(r, 1000));
+pty.write("npm init -y\n");
+await new Promise((r) => setTimeout(r, 1000));
 
-pty.write('npm install express\n');
-await new Promise(r => setTimeout(r, 2000));
+pty.write("npm install express\n");
+await new Promise((r) => setTimeout(r, 2000));
 
 pty.write('node -e "console.log(process.version)"\n');
-await new Promise(r => setTimeout(r, 500));
+await new Promise((r) => setTimeout(r, 500));
 
 pty.close();
 await sandbox.remove();
@@ -497,12 +544,13 @@ try {
   // ...
 } catch (error) {
   if (error instanceof Error) {
-    console.error('Error:', error.message);
+    console.error("Error:", error.message);
   }
 }
 ```
 
 Common errors:
+
 - **Validation Error** - Invalid sandbox parameters
 - **Authentication Error** - Invalid or missing API key
 - **Not Found** - Sandbox or session doesn't exist
@@ -518,6 +566,7 @@ npx tsx --env-file=.env example/test-pty-comprehensive.ts
 ```
 
 Available examples:
+
 - `test-pty-comprehensive.ts` - Full PTY testing (9 scenarios)
 - `test-sandbox-exec.ts` - Code execution examples
 - `test-sandbox-fs.ts` - File system operations
@@ -559,13 +608,14 @@ export API_KEY="your-api-key"
 ### "Sandbox creation failed"
 
 Ensure your sandbox parameters are valid:
+
 - `mem`: minimum 1024 MB
 - `cpu`: minimum 1 core
 
 ```typescript
-const sandbox = await vr.createSandbox({ 
-  mem: 1024,  // At least 1GB
-  cpu: 1      // At least 1 core
+const sandbox = await vr.createSandbox({
+  mem: 1024, // At least 1GB
+  cpu: 1, // At least 1 core
 });
 ```
 
@@ -576,12 +626,12 @@ Increase timeout for slow systems:
 ```typescript
 const pty = await sandbox.pty.connect({
   sessionId,
-  onData: (data) => console.log(data)
+  onData: (data) => console.log(data),
 });
 
 // For runCommand
-const output = await pty.runCommand('slow-command', {
-  timeout: 30000  // 30 seconds
+const output = await pty.runCommand("slow-command", {
+  timeout: 30000, // 30 seconds
 });
 ```
 
@@ -591,16 +641,17 @@ Check the file path:
 
 ```typescript
 // List files to verify path
-const files = await sandbox.fs.listFiles('/app');
+const files = await sandbox.fs.listFiles("/app");
 console.log(files.data?.files);
 
 // Then access specific file
-const content = await sandbox.fs.readFile('/app/file.txt');
+const content = await sandbox.fs.readFile("/app/file.txt");
 ```
 
 ## API Documentation
 
 Full API documentation is available at:
+
 - [OpenAPI Spec](./openapi.yml)
 - [API Docs](./src/api-client/docs/)
 
@@ -621,11 +672,13 @@ ISC License - See LICENSE file for details
 ## Changelog
 
 ### v0.0.2
+
 - Fixed PTY session response field mapping
 - Added fallback logic for empty sessionId
 - Improved error handling and validation
 
 ### v0.0.1
+
 - Initial release
 - Sandbox management
 - File operations

package/dist/CodeInterpreter.d.ts

@@ -0,0 +1,77 @@
+import { Configuration } from './api-client/index.js';
+export type SupportedLanguage = 'python' | 'javascript' | 'node' | 'bash' | 'go' | 'ruby' | 'java' | 'csharp';
+export interface CodeExecutionOptions {
+    timeout?: number;
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export interface CodeExecutionResult {
+    success: boolean;
+    output: string;
+    error?: string;
+    exitCode?: number;
+}
+/**
+ * CodeInterpreter provides a simple API to execute code in various languages
+ * over a PTY session, similar to e2b or Daytona
+ */
+export declare class CodeInterpreter {
+    private sandboxId;
+    private config;
+    private ptySession;
+    private currentLanguage;
+    private isInitialized;
+    private readonly languageConfigs;
+    /**
+     * @internal
+     */
+    constructor(sandboxId: string, config: Configuration);
+    /**
+     * Initialize the code interpreter with a specific language
+     * @param language The programming language to use
+     * @param sessionId Optional existing PTY session ID
+     */
+    initialize(language: SupportedLanguage, sessionId?: string): Promise<void>;
+    /**
+     * Execute code in the initialized interpreter
+     * @param code The code to execute
+     * @param options Execution options
+     * @returns The execution result
+     */
+    execute(code: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
+    /**
+     * Execute multiple code snippets sequentially
+     * @param codeSnippets Array of code snippets to execute
+     * @param options Execution options
+     * @returns Array of execution results
+     */
+    executeMultiple(codeSnippets: string[], options?: CodeExecutionOptions): Promise<CodeExecutionResult[]>;
+    /**
+     * Execute code from a file
+     * @param filePath Path to the file containing code
+     * @param options Execution options
+     * @returns The execution result
+     */
+    executeFile(filePath: string, options?: CodeExecutionOptions): Promise<CodeExecutionResult>;
+    /**
+     * Get the current language
+     */
+    getCurrentLanguage(): SupportedLanguage | null;
+    /**
+     * Check if interpreter is initialized
+     */
+    isReady(): boolean;
+    /**
+     * Clean up the interpreter session
+     */
+    close(): Promise<void>;
+    /**
+     * Reset the interpreter for a new language
+     */
+    reset(newLanguage?: SupportedLanguage): Promise<void>;
+    /**
+     * Clean output by removing the input command and extra prompts
+     */
+    private cleanOutput;
+}
+//# sourceMappingURL=CodeInterpreter.d.ts.map

package/dist/CodeInterpreter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodeInterpreter.d.ts","sourceRoot":"","sources":["../src/CodeInterpreter.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAEtD,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE9G,MAAM,WAAW,oBAAoB;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAWD;;;GAGG;AACH,qBAAa,eAAe;IAoEpB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,MAAM;IApElB,OAAO,CAAC,UAAU,CAA2B;IAC7C,OAAO,CAAC,eAAe,CAAkC;IACzD,OAAO,CAAC,aAAa,CAAkB;IAEvC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAyD9B;IAEF;;OAEG;gBAES,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa;IAGjC;;;;OAIG;IACG,UAAU,CAAC,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA2ChF;;;;;OAKG;IACG,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA4F7F;;;;;OAKG;IACG,eAAe,CACjB,YAAY,EAAE,MAAM,EAAE,EACtB,OAAO,GAAE,oBAAyB,GACnC,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAQjC;;;;;OAKG;IACG,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAuBrG;;OAEG;IACH,kBAAkB,IAAI,iBAAiB,GAAG,IAAI;IAI9C;;OAEG;IACH,OAAO,IAAI,OAAO;IAIlB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B;;OAEG;IACG,KAAK,CAAC,WAAW,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3D;;OAEG;IACH,OAAO,CAAC,WAAW;CA2DtB"}