computesdk 1.10.2 → 1.11.0

package/README.md

@@ -40,8 +40,11 @@ For more control, use `setConfig()` to explicitly configure the provider:
 import { compute } from 'computesdk';
 
 compute.setConfig({
-  provider: 'e2b',
-  e2b: { apiKey: 'your_api_key' }
+  provider: 'your-provider',
+  apiKey: process.env.COMPUTESDK_API_KEY,
+  'your-provider': {
+    apiKey: process.env.YOUR_PROVIDER_API_KEY
+  }
 });
 
 const sandbox = await compute.sandbox.create();
@@ -84,8 +87,11 @@ Configure the gateway with explicit provider settings.
 
 ```typescript
 compute.setConfig({
-  provider: 'e2b',
-  e2b: { apiKey: 'your_api_key' }
+  provider: 'your-provider',
+  apiKey: process.env.COMPUTESDK_API_KEY,
+  'your-provider': {
+    apiKey: process.env.YOUR_PROVIDER_API_KEY
+  }
 });
 ```
 
@@ -95,6 +101,7 @@ compute.setConfig({
 // E2B
 compute.setConfig({
   provider: 'e2b',
+  apiKey: process.env.COMPUTESDK_API_KEY,
   e2b: { 
     apiKey: 'e2b_xxx',
     templateId: 'optional_template' 
@@ -104,6 +111,7 @@ compute.setConfig({
 // Modal
 compute.setConfig({
   provider: 'modal',
+  apiKey: process.env.COMPUTESDK_API_KEY,
   modal: { 
     tokenId: 'ak-xxx',
     tokenSecret: 'as-xxx'
@@ -113,6 +121,7 @@ compute.setConfig({
 // Railway
 compute.setConfig({
   provider: 'railway',
+  apiKey: process.env.COMPUTESDK_API_KEY,
   railway: { 
     apiToken: 'your_token',
     projectId: 'project_id',
@@ -123,12 +132,14 @@ compute.setConfig({
 // Daytona
 compute.setConfig({
   provider: 'daytona',
+  apiKey: process.env.COMPUTESDK_API_KEY,
   daytona: { apiKey: 'your_api_key' }
 });
 
 // Vercel
 compute.setConfig({
   provider: 'vercel',
+  apiKey: process.env.COMPUTESDK_API_KEY,
   vercel: { 
     token: 'your_token',
     teamId: 'team_xxx',

package/dist/index.d.mts

@@ -132,8 +132,13 @@ interface Sandbox$1 {
     readonly provider: string;
     /** Execute code in the sandbox */
     runCode(code: string, runtime?: Runtime): Promise<CodeResult$1>;
-    /** Execute shell commands */
-    runCommand(commandOrArray: string | [string, ...string[]], argsOrOptions?: string[] | RunCommandOptions, maybeOptions?: RunCommandOptions): Promise<CommandResult$1>;
+    /**
+     * Execute shell command
+     *
+     * Send raw command string to the sandbox - no preprocessing.
+     * The provider/server handles shell invocation and execution details.
+     */
+    runCommand(command: string, options?: RunCommandOptions): Promise<CommandResult$1>;
     /** Get information about the sandbox */
     getInfo(): Promise<SandboxInfo$1>;
     /** Get URL for accessing the sandbox on a specific port */
@@ -245,6 +250,42 @@ interface TerminalErrorMessage {
         error: string;
     };
 }
+/**
+ * Command stdout streaming message (exec mode with stream: true)
+ */
+interface CommandStdoutMessage {
+    type: 'command:stdout';
+    channel: string;
+    data: {
+        terminal_id: string;
+        cmd_id: string;
+        output: string;
+    };
+}
+/**
+ * Command stderr streaming message (exec mode with stream: true)
+ */
+interface CommandStderrMessage {
+    type: 'command:stderr';
+    channel: string;
+    data: {
+        terminal_id: string;
+        cmd_id: string;
+        output: string;
+    };
+}
+/**
+ * Command exit message (exec mode with stream: true)
+ */
+interface CommandExitMessage {
+    type: 'command:exit';
+    channel: string;
+    data: {
+        terminal_id: string;
+        cmd_id: string;
+        exit_code: number;
+    };
+}
 /**
  * File watcher created notification
  */
@@ -422,6 +463,12 @@ declare class WebSocketManager {
      * Resize terminal window
      */
     resizeTerminal(terminalId: string, cols: number, rows: number): void;
+    /**
+     * Start a pending streaming command
+     * Used in two-phase streaming flow: HTTP request creates pending command,
+     * then this signal triggers execution after client has subscribed.
+     */
+    startCommand(cmdId: string): void;
     /**
      * Register event handler
      */
@@ -433,6 +480,9 @@ declare class WebSocketManager {
     on(event: 'terminal:output', handler: MessageHandler<TerminalOutputMessage>): void;
     on(event: 'terminal:destroyed', handler: MessageHandler<TerminalDestroyedMessage>): void;
     on(event: 'terminal:error', handler: MessageHandler<TerminalErrorMessage>): void;
+    on(event: 'command:stdout', handler: MessageHandler<CommandStdoutMessage>): void;
+    on(event: 'command:stderr', handler: MessageHandler<CommandStderrMessage>): void;
+    on(event: 'command:exit', handler: MessageHandler<CommandExitMessage>): void;
     on(event: 'watcher:created', handler: MessageHandler<WatcherCreatedMessage>): void;
     on(event: 'file:changed', handler: MessageHandler<FileChangedMessage>): void;
     on(event: 'watcher:destroyed', handler: MessageHandler<WatcherDestroyedMessage>): void;
@@ -1695,6 +1745,10 @@ interface CommandRunOptions {
     shell?: string;
     /** Run in background (optional) */
     background?: boolean;
+    /** Working directory for the command (optional) */
+    cwd?: string;
+    /** Environment variables (optional) */
+    env?: Record<string, string>;
 }
 /**
  * Run - Resource namespace for executing code and commands
@@ -1740,6 +1794,8 @@ declare class Run {
      * @param options - Execution options
      * @param options.shell - Shell to use (optional)
      * @param options.background - Run in background (optional)
+     * @param options.cwd - Working directory for the command (optional)
+     * @param options.env - Environment variables (optional)
      * @returns Command execution result with stdout, stderr, exit code, and duration
      */
     command(command: string, options?: CommandRunOptions): Promise<CommandResult>;
@@ -1946,6 +2002,13 @@ interface SandboxConfig {
     protocol?: 'json' | 'binary';
     /** Optional metadata associated with the sandbox */
     metadata?: Record<string, unknown>;
+    /**
+     * Handler called when destroy() is invoked.
+     * If provided, this is called to destroy the sandbox (e.g., via gateway API).
+     * If not provided, destroy() only disconnects the WebSocket.
+     * @internal
+     */
+    destroyHandler?: () => Promise<void>;
 }
 /**
  * Health check response
@@ -2065,7 +2128,7 @@ interface FileResponse {
     };
 }
 /**
- * Command execution response
+ * Command execution response (used by both /run/command and /terminals/{id}/execute)
  */
 interface CommandExecutionResponse {
     message: string;
@@ -2073,12 +2136,12 @@ interface CommandExecutionResponse {
         terminal_id?: string;
         cmd_id?: string;
         command: string;
-        output?: string;
         stdout: string;
         stderr: string;
         exit_code?: number;
         duration_ms?: number;
         status?: 'running' | 'completed' | 'failed';
+        channel?: string;
         pty?: boolean;
     };
 }
@@ -2131,22 +2194,6 @@ interface CodeExecutionResponse {
         language: string;
     };
 }
-/**
- * Run command response (POST /run/command)
- */
-interface RunCommandResponse {
-    message: string;
-    data: {
-        terminal_id?: string;
-        cmd_id?: string;
-        command: string;
-        stdout: string;
-        stderr: string;
-        exit_code?: number;
-        duration_ms?: number;
-        status?: 'running' | 'completed' | 'failed';
-    };
-}
 /**
  * File watcher information
  */
@@ -2598,12 +2645,14 @@ declare class Sandbox {
      */
     runCodeRequest(code: string, language?: string): Promise<CodeExecutionResponse>;
     /**
-     * Execute a shell command (POST /run/command)
+     * Execute a command and get the result
+     * Lower-level method that returns the raw API response
      *
-     * @param options - Command options
-     * @param options.command - The command to execute
+     * @param options.command - Command to execute
      * @param options.shell - Shell to use (optional)
      * @param options.background - Run in background (optional)
+     * @param options.cwd - Working directory for the command (optional)
+     * @param options.env - Environment variables (optional)
      * @returns Command execution result
      *
      * @example
@@ -2616,7 +2665,10 @@ declare class Sandbox {
         command: string;
         shell?: string;
         background?: boolean;
-    }): Promise<RunCommandResponse>;
+        stream?: boolean;
+        cwd?: string;
+        env?: Record<string, string>;
+    }): Promise<CommandExecutionResponse>;
     /**
      * List files at the specified path
      */
@@ -2629,6 +2681,11 @@ declare class Sandbox {
      * Get file metadata (without content)
      */
     getFile(path: string): Promise<FileResponse>;
+    /**
+     * Encode a file path for use in URLs
+     * Strips leading slash and encodes each segment separately to preserve path structure
+     */
+    private encodeFilePath;
     /**
      * Read file content
      */
@@ -2891,21 +2948,47 @@ declare class Sandbox {
         language: string;
     }>;
     /**
-     * Execute shell command in the sandbox (convenience method)
+     * Execute shell command in the sandbox
      *
-     * Delegates to sandbox.run.command() - prefer using that directly for new code.
+     * Sends clean command string to server - no preprocessing or shell wrapping.
+     * The server handles shell invocation, working directory, and backgrounding.
      *
-     * @param command - The command to execute (string or array form)
-     * @param argsOrOptions - Arguments array or options object
-     * @param maybeOptions - Options when using (command, args, options) form
+     * @param command - The command to execute (raw string, e.g., "npm install")
+     * @param options - Execution options
+     * @param options.background - Run in background (server uses goroutines)
+     * @param options.cwd - Working directory (server uses cmd.Dir)
+     * @param options.env - Environment variables (server uses cmd.Env)
+     * @param options.onStdout - Callback for streaming stdout data
+     * @param options.onStderr - Callback for streaming stderr data
      * @returns Command execution result
+     *
+     * @example
+     * ```typescript
+     * // Simple command
+     * await sandbox.runCommand('ls -la')
+     *
+     * // With working directory
+     * await sandbox.runCommand('npm install', { cwd: '/app' })
+     *
+     * // Background with env vars
+     * await sandbox.runCommand('node server.js', {
+     *   background: true,
+     *   env: { PORT: '3000' }
+     * })
+     *
+     * // With streaming output
+     * await sandbox.runCommand('npm install', {
+     *   onStdout: (data) => console.log(data),
+     *   onStderr: (data) => console.error(data),
+     * })
+     * ```
      */
-    runCommand(commandOrArray: string | [string, ...string[]], argsOrOptions?: string[] | {
-        background?: boolean;
-        cwd?: string;
-    }, maybeOptions?: {
+    runCommand(command: string, options?: {
         background?: boolean;
         cwd?: string;
+        env?: Record<string, string>;
+        onStdout?: (data: string) => void;
+        onStderr?: (data: string) => void;
     }): Promise<{
         stdout: string;
         stderr: string;
@@ -2948,6 +3031,9 @@ declare class Sandbox {
     getInstance(): this;
     /**
      * Destroy the sandbox (Sandbox interface method)
+     *
+     * If a destroyHandler was provided (e.g., from gateway), calls it to destroy
+     * the sandbox on the backend. Otherwise, only disconnects the WebSocket.
      */
     destroy(): Promise<void>;
     /**
@@ -3045,8 +3131,13 @@ declare function getMissingEnvVars(provider: ProviderName): string[];
 interface ExplicitComputeConfig {
     /** Provider name to use */
     provider: ProviderName;
+    /**
+     * ComputeSDK API key (required for gateway mode)
+     * @deprecated Use `computesdkApiKey` for clarity
+     */
+    apiKey?: string;
     /** ComputeSDK API key (required for gateway mode) */
-    apiKey: string;
+    computesdkApiKey?: string;
     /** Optional gateway URL override */
     gatewayUrl?: string;
     /** Provider-specific configurations */

package/dist/index.d.ts

@@ -132,8 +132,13 @@ interface Sandbox$1 {
     readonly provider: string;
     /** Execute code in the sandbox */
     runCode(code: string, runtime?: Runtime): Promise<CodeResult$1>;
-    /** Execute shell commands */
-    runCommand(commandOrArray: string | [string, ...string[]], argsOrOptions?: string[] | RunCommandOptions, maybeOptions?: RunCommandOptions): Promise<CommandResult$1>;
+    /**
+     * Execute shell command
+     *
+     * Send raw command string to the sandbox - no preprocessing.
+     * The provider/server handles shell invocation and execution details.
+     */
+    runCommand(command: string, options?: RunCommandOptions): Promise<CommandResult$1>;
     /** Get information about the sandbox */
     getInfo(): Promise<SandboxInfo$1>;
     /** Get URL for accessing the sandbox on a specific port */
@@ -245,6 +250,42 @@ interface TerminalErrorMessage {
         error: string;
     };
 }
+/**
+ * Command stdout streaming message (exec mode with stream: true)
+ */
+interface CommandStdoutMessage {
+    type: 'command:stdout';
+    channel: string;
+    data: {
+        terminal_id: string;
+        cmd_id: string;
+        output: string;
+    };
+}
+/**
+ * Command stderr streaming message (exec mode with stream: true)
+ */
+interface CommandStderrMessage {
+    type: 'command:stderr';
+    channel: string;
+    data: {
+        terminal_id: string;
+        cmd_id: string;
+        output: string;
+    };
+}
+/**
+ * Command exit message (exec mode with stream: true)
+ */
+interface CommandExitMessage {
+    type: 'command:exit';
+    channel: string;
+    data: {
+        terminal_id: string;
+        cmd_id: string;
+        exit_code: number;
+    };
+}
 /**
  * File watcher created notification
  */
@@ -422,6 +463,12 @@ declare class WebSocketManager {
      * Resize terminal window
      */
     resizeTerminal(terminalId: string, cols: number, rows: number): void;
+    /**
+     * Start a pending streaming command
+     * Used in two-phase streaming flow: HTTP request creates pending command,
+     * then this signal triggers execution after client has subscribed.
+     */
+    startCommand(cmdId: string): void;
     /**
      * Register event handler
      */
@@ -433,6 +480,9 @@ declare class WebSocketManager {
     on(event: 'terminal:output', handler: MessageHandler<TerminalOutputMessage>): void;
     on(event: 'terminal:destroyed', handler: MessageHandler<TerminalDestroyedMessage>): void;
     on(event: 'terminal:error', handler: MessageHandler<TerminalErrorMessage>): void;
+    on(event: 'command:stdout', handler: MessageHandler<CommandStdoutMessage>): void;
+    on(event: 'command:stderr', handler: MessageHandler<CommandStderrMessage>): void;
+    on(event: 'command:exit', handler: MessageHandler<CommandExitMessage>): void;
     on(event: 'watcher:created', handler: MessageHandler<WatcherCreatedMessage>): void;
     on(event: 'file:changed', handler: MessageHandler<FileChangedMessage>): void;
     on(event: 'watcher:destroyed', handler: MessageHandler<WatcherDestroyedMessage>): void;
@@ -1695,6 +1745,10 @@ interface CommandRunOptions {
     shell?: string;
     /** Run in background (optional) */
     background?: boolean;
+    /** Working directory for the command (optional) */
+    cwd?: string;
+    /** Environment variables (optional) */
+    env?: Record<string, string>;
 }
 /**
  * Run - Resource namespace for executing code and commands
@@ -1740,6 +1794,8 @@ declare class Run {
      * @param options - Execution options
      * @param options.shell - Shell to use (optional)
      * @param options.background - Run in background (optional)
+     * @param options.cwd - Working directory for the command (optional)
+     * @param options.env - Environment variables (optional)
      * @returns Command execution result with stdout, stderr, exit code, and duration
      */
     command(command: string, options?: CommandRunOptions): Promise<CommandResult>;
@@ -1946,6 +2002,13 @@ interface SandboxConfig {
     protocol?: 'json' | 'binary';
     /** Optional metadata associated with the sandbox */
     metadata?: Record<string, unknown>;
+    /**
+     * Handler called when destroy() is invoked.
+     * If provided, this is called to destroy the sandbox (e.g., via gateway API).
+     * If not provided, destroy() only disconnects the WebSocket.
+     * @internal
+     */
+    destroyHandler?: () => Promise<void>;
 }
 /**
  * Health check response
@@ -2065,7 +2128,7 @@ interface FileResponse {
     };
 }
 /**
- * Command execution response
+ * Command execution response (used by both /run/command and /terminals/{id}/execute)
  */
 interface CommandExecutionResponse {
     message: string;
@@ -2073,12 +2136,12 @@ interface CommandExecutionResponse {
         terminal_id?: string;
         cmd_id?: string;
         command: string;
-        output?: string;
         stdout: string;
         stderr: string;
         exit_code?: number;
         duration_ms?: number;
         status?: 'running' | 'completed' | 'failed';
+        channel?: string;
         pty?: boolean;
     };
 }
@@ -2131,22 +2194,6 @@ interface CodeExecutionResponse {
         language: string;
     };
 }
-/**
- * Run command response (POST /run/command)
- */
-interface RunCommandResponse {
-    message: string;
-    data: {
-        terminal_id?: string;
-        cmd_id?: string;
-        command: string;
-        stdout: string;
-        stderr: string;
-        exit_code?: number;
-        duration_ms?: number;
-        status?: 'running' | 'completed' | 'failed';
-    };
-}
 /**
  * File watcher information
  */
@@ -2598,12 +2645,14 @@ declare class Sandbox {
      */
     runCodeRequest(code: string, language?: string): Promise<CodeExecutionResponse>;
     /**
-     * Execute a shell command (POST /run/command)
+     * Execute a command and get the result
+     * Lower-level method that returns the raw API response
      *
-     * @param options - Command options
-     * @param options.command - The command to execute
+     * @param options.command - Command to execute
      * @param options.shell - Shell to use (optional)
      * @param options.background - Run in background (optional)
+     * @param options.cwd - Working directory for the command (optional)
+     * @param options.env - Environment variables (optional)
      * @returns Command execution result
      *
      * @example
@@ -2616,7 +2665,10 @@ declare class Sandbox {
         command: string;
         shell?: string;
         background?: boolean;
-    }): Promise<RunCommandResponse>;
+        stream?: boolean;
+        cwd?: string;
+        env?: Record<string, string>;
+    }): Promise<CommandExecutionResponse>;
     /**
      * List files at the specified path
      */
@@ -2629,6 +2681,11 @@ declare class Sandbox {
      * Get file metadata (without content)
      */
     getFile(path: string): Promise<FileResponse>;
+    /**
+     * Encode a file path for use in URLs
+     * Strips leading slash and encodes each segment separately to preserve path structure
+     */
+    private encodeFilePath;
     /**
      * Read file content
      */
@@ -2891,21 +2948,47 @@ declare class Sandbox {
         language: string;
     }>;
     /**
-     * Execute shell command in the sandbox (convenience method)
+     * Execute shell command in the sandbox
      *
-     * Delegates to sandbox.run.command() - prefer using that directly for new code.
+     * Sends clean command string to server - no preprocessing or shell wrapping.
+     * The server handles shell invocation, working directory, and backgrounding.
      *
-     * @param command - The command to execute (string or array form)
-     * @param argsOrOptions - Arguments array or options object
-     * @param maybeOptions - Options when using (command, args, options) form
+     * @param command - The command to execute (raw string, e.g., "npm install")
+     * @param options - Execution options
+     * @param options.background - Run in background (server uses goroutines)
+     * @param options.cwd - Working directory (server uses cmd.Dir)
+     * @param options.env - Environment variables (server uses cmd.Env)
+     * @param options.onStdout - Callback for streaming stdout data
+     * @param options.onStderr - Callback for streaming stderr data
      * @returns Command execution result
+     *
+     * @example
+     * ```typescript
+     * // Simple command
+     * await sandbox.runCommand('ls -la')
+     *
+     * // With working directory
+     * await sandbox.runCommand('npm install', { cwd: '/app' })
+     *
+     * // Background with env vars
+     * await sandbox.runCommand('node server.js', {
+     *   background: true,
+     *   env: { PORT: '3000' }
+     * })
+     *
+     * // With streaming output
+     * await sandbox.runCommand('npm install', {
+     *   onStdout: (data) => console.log(data),
+     *   onStderr: (data) => console.error(data),
+     * })
+     * ```
      */
-    runCommand(commandOrArray: string | [string, ...string[]], argsOrOptions?: string[] | {
-        background?: boolean;
-        cwd?: string;
-    }, maybeOptions?: {
+    runCommand(command: string, options?: {
         background?: boolean;
         cwd?: string;
+        env?: Record<string, string>;
+        onStdout?: (data: string) => void;
+        onStderr?: (data: string) => void;
     }): Promise<{
         stdout: string;
         stderr: string;
@@ -2948,6 +3031,9 @@ declare class Sandbox {
     getInstance(): this;
     /**
      * Destroy the sandbox (Sandbox interface method)
+     *
+     * If a destroyHandler was provided (e.g., from gateway), calls it to destroy
+     * the sandbox on the backend. Otherwise, only disconnects the WebSocket.
      */
     destroy(): Promise<void>;
     /**
@@ -3045,8 +3131,13 @@ declare function getMissingEnvVars(provider: ProviderName): string[];
 interface ExplicitComputeConfig {
     /** Provider name to use */
     provider: ProviderName;
+    /**
+     * ComputeSDK API key (required for gateway mode)
+     * @deprecated Use `computesdkApiKey` for clarity
+     */
+    apiKey?: string;
     /** ComputeSDK API key (required for gateway mode) */
-    apiKey: string;
+    computesdkApiKey?: string;
     /** Optional gateway URL override */
     gatewayUrl?: string;
     /** Provider-specific configurations */