computesdk 1.10.3 → 1.11.1

package/dist/index.d.ts

@@ -250,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
  */
@@ -427,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
      */
@@ -438,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;
@@ -1957,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
@@ -2076,7 +2128,7 @@ interface FileResponse {
     };
 }
 /**
- * Command execution response
+ * Command execution response (used by both /run/command and /terminals/{id}/execute)
  */
 interface CommandExecutionResponse {
     message: string;
@@ -2084,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;
     };
 }
@@ -2142,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
  */
@@ -2629,9 +2665,10 @@ declare class Sandbox {
         command: string;
         shell?: string;
         background?: boolean;
+        stream?: boolean;
         cwd?: string;
         env?: Record<string, string>;
-    }): Promise<RunCommandResponse>;
+    }): Promise<CommandExecutionResponse>;
     /**
      * List files at the specified path
      */
@@ -2644,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
      */
@@ -2916,6 +2958,8 @@ declare class Sandbox {
      * @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
@@ -2931,12 +2975,20 @@ declare class Sandbox {
      *   background: true,
      *   env: { PORT: '3000' }
      * })
+     *
+     * // With streaming output
+     * await sandbox.runCommand('npm install', {
+     *   onStdout: (data) => console.log(data),
+     *   onStderr: (data) => console.error(data),
+     * })
      * ```
      */
     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;
@@ -2979,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>;
     /**
@@ -3076,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.js

@@ -538,6 +538,17 @@ var WebSocketManager = class {
       data: { terminal_id: terminalId, cols, rows }
     });
   }
+  /**
+   * 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) {
+    this.sendRaw({
+      type: "command:start",
+      data: { cmd_id: cmdId }
+    });
+  }
   on(event, handler) {
     if (!this.eventHandlers.has(event)) {
       this.eventHandlers.set(event, /* @__PURE__ */ new Set());
@@ -1011,6 +1022,7 @@ var TerminalInstance = class {
       throw new Error("Destroy handler not set");
     }
     await this._destroyHandler();
+    this._status = "stopped";
     this.cleanup();
   }
   /**
@@ -1916,7 +1928,8 @@ var Sandbox = class {
       headers: config.headers || {},
       timeout: config.timeout || 3e4,
       protocol: config.protocol || "binary",
-      metadata: config.metadata
+      metadata: config.metadata,
+      destroyHandler: config.destroyHandler
     };
     this.WebSocketImpl = config.WebSocket || globalThis.WebSocket;
     if (!this.WebSocketImpl) {
@@ -2339,18 +2352,24 @@ API request failed (${response.status}): ${error}`
    * Get file metadata (without content)
    */
   async getFile(path) {
-    return this.request(`/files/${encodeURIComponent(path)}`);
+    return this.request(`/files/${this.encodeFilePath(path)}`);
+  }
+  /**
+   * Encode a file path for use in URLs
+   * Strips leading slash and encodes each segment separately to preserve path structure
+   */
+  encodeFilePath(path) {
+    const pathWithoutLeadingSlash = path.startsWith("/") ? path.slice(1) : path;
+    const segments = pathWithoutLeadingSlash.split("/");
+    return segments.map((s) => encodeURIComponent(s)).join("/");
   }
   /**
    * Read file content
    */
   async readFile(path) {
     const params = new URLSearchParams({ content: "true" });
-    const pathWithoutLeadingSlash = path.startsWith("/") ? path.slice(1) : path;
-    const segments = pathWithoutLeadingSlash.split("/");
-    const encodedPath = segments.map((s) => encodeURIComponent(s)).join("/");
     const response = await this.request(
-      `/files/${encodedPath}?${params}`
+      `/files/${this.encodeFilePath(path)}?${params}`
     );
     return response.data.content || "";
   }
@@ -2367,7 +2386,7 @@ API request failed (${response.status}): ${error}`
    * Delete a file or directory
    */
   async deleteFile(path) {
-    return this.request(`/files/${encodeURIComponent(path)}`, {
+    return this.request(`/files/${this.encodeFilePath(path)}`, {
       method: "DELETE"
     });
   }
@@ -2386,7 +2405,7 @@ API request failed (${response.status}): ${error}`
         headers["Authorization"] = `Bearer ${this._token}`;
       }
       const response = await fetch(
-        `${this.config.sandboxUrl}/files/${encodeURIComponent(path)}`,
+        `${this.config.sandboxUrl}/files/${this.encodeFilePath(path)}`,
         {
           method: "HEAD",
           headers,
@@ -2908,6 +2927,8 @@ API request failed (${response.status}): ${error}`
    * @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
@@ -2923,10 +2944,77 @@ API request failed (${response.status}): ${error}`
    *   background: true, 
    *   env: { PORT: '3000' } 
    * })
+   * 
+   * // With streaming output
+   * await sandbox.runCommand('npm install', {
+   *   onStdout: (data) => console.log(data),
+   *   onStderr: (data) => console.error(data),
+   * })
    * ```
    */
   async runCommand(command, options) {
-    return this.run.command(command, options);
+    const hasStreamingCallbacks = options?.onStdout || options?.onStderr;
+    if (!hasStreamingCallbacks) {
+      return this.run.command(command, options);
+    }
+    const ws = await this.ensureWebSocket();
+    const result = await this.runCommandRequest({
+      command,
+      stream: true,
+      cwd: options?.cwd,
+      env: options?.env
+    });
+    const { cmd_id, channel } = result.data;
+    if (!cmd_id || !channel) {
+      throw new Error("Server did not return streaming channel info");
+    }
+    ws.subscribe(channel);
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 0;
+    let resolvePromise = null;
+    const cleanup = () => {
+      ws.off("command:stdout", handleStdout);
+      ws.off("command:stderr", handleStderr);
+      ws.off("command:exit", handleExit);
+      ws.unsubscribe(channel);
+    };
+    const handleStdout = (msg) => {
+      if (msg.channel === channel && msg.data.cmd_id === cmd_id) {
+        stdout += msg.data.output;
+        options?.onStdout?.(msg.data.output);
+      }
+    };
+    const handleStderr = (msg) => {
+      if (msg.channel === channel && msg.data.cmd_id === cmd_id) {
+        stderr += msg.data.output;
+        options?.onStderr?.(msg.data.output);
+      }
+    };
+    const handleExit = (msg) => {
+      if (msg.channel === channel && msg.data.cmd_id === cmd_id) {
+        exitCode = msg.data.exit_code;
+        cleanup();
+        if (resolvePromise) {
+          resolvePromise({ stdout, stderr, exitCode, durationMs: 0 });
+        }
+      }
+    };
+    ws.on("command:stdout", handleStdout);
+    ws.on("command:stderr", handleStderr);
+    ws.on("command:exit", handleExit);
+    ws.startCommand(cmd_id);
+    if (options?.background) {
+      return {
+        stdout: "",
+        stderr: "",
+        exitCode: 0,
+        durationMs: 0
+      };
+    }
+    return new Promise((resolve) => {
+      resolvePromise = resolve;
+    });
   }
   /**
    * Get server information
@@ -2979,9 +3067,15 @@ API request failed (${response.status}): ${error}`
   }
   /**
    * 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.
    */
   async destroy() {
     await this.disconnect();
+    if (this.config.destroyHandler) {
+      await this.config.destroyHandler();
+    }
   }
   /**
    * Disconnect WebSocket
@@ -3420,9 +3514,17 @@ function buildConfigExample(provider, authOptions) {
   return options.join("\n\n");
 }
 function createConfigFromExplicit(config) {
-  if (!config.apiKey) {
+  const computesdkApiKey = config.computesdkApiKey || config.apiKey;
+  if (!computesdkApiKey) {
     throw new Error(
-      `Missing ComputeSDK API key. The 'apiKey' field is required.
+      `Missing ComputeSDK API key. Set 'computesdkApiKey' in your config.
+
+Example:
+  compute.setConfig({
+    provider: 'e2b',
+    computesdkApiKey: process.env.COMPUTESDK_API_KEY,
+    e2b: { apiKey: process.env.E2B_API_KEY }
+  })
 
 Get your API key at: https://computesdk.com/dashboard`
     );
@@ -3430,7 +3532,7 @@ Get your API key at: https://computesdk.com/dashboard`
   validateProviderConfig(config);
   const providerHeaders = buildProviderHeaders2(config);
   return {
-    apiKey: config.apiKey,
+    apiKey: computesdkApiKey,
     gatewayUrl: config.gatewayUrl || GATEWAY_URL,
     provider: config.provider,
     providerHeaders
@@ -3518,6 +3620,34 @@ async function gatewayFetch(url, config, options = {}) {
     throw error;
   }
 }
+async function waitForSandboxStatus(config, endpoint, body, options = {}) {
+  const maxWaitMs = options.maxWaitMs ?? 6e4;
+  const initialDelayMs = 500;
+  const maxDelayMs = 2e3;
+  const backoffFactor = 1.5;
+  const startTime = Date.now();
+  let currentDelay = initialDelayMs;
+  while (Date.now() - startTime < maxWaitMs) {
+    const result = await gatewayFetch(endpoint, config, {
+      method: "POST",
+      body: JSON.stringify(body)
+    });
+    if (!result.success || !result.data) {
+      return result;
+    }
+    if (result.data.status !== "creating") {
+      return result;
+    }
+    if (process.env.COMPUTESDK_DEBUG) {
+      console.log(`[Compute] Sandbox still creating, waiting ${currentDelay}ms...`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, currentDelay));
+    currentDelay = Math.min(currentDelay * backoffFactor, maxDelayMs);
+  }
+  throw new Error(
+    `Sandbox is still being created after ${maxWaitMs}ms. This may indicate the sandbox failed to start. Check your provider dashboard.`
+  );
+}
 var ComputeManager = class {
   constructor() {
     this.config = null;
@@ -3546,7 +3676,12 @@ var ComputeManager = class {
             ...name && { name },
             ...namespace && { namespace }
           },
-          WebSocket: globalThis.WebSocket
+          WebSocket: globalThis.WebSocket,
+          destroyHandler: async () => {
+            await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
+              method: "DELETE"
+            });
+          }
         });
         await waitForComputeReady(sandbox);
         return sandbox;
@@ -3567,7 +3702,12 @@ var ComputeManager = class {
           provider,
           token: token || config.apiKey,
           metadata,
-          WebSocket: globalThis.WebSocket
+          WebSocket: globalThis.WebSocket,
+          destroyHandler: async () => {
+            await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
+              method: "DELETE"
+            });
+          }
         });
         await waitForComputeReady(sandbox);
         return sandbox;
@@ -3595,14 +3735,15 @@ var ComputeManager = class {
       findOrCreate: async (options) => {
         const config = this.getGatewayConfig();
         const { name, namespace, ...restOptions } = options;
-        const result = await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/find-or-create`, config, {
-          method: "POST",
-          body: JSON.stringify({
+        const result = await waitForSandboxStatus(
+          config,
+          `${config.gatewayUrl}/v1/sandboxes/find-or-create`,
+          {
             namespace: namespace || "default",
             name,
             ...restOptions
-          })
-        });
+          }
+        );
         if (!result.success || !result.data) {
           throw new Error(`Gateway returned invalid response`);
         }
@@ -3617,7 +3758,12 @@ var ComputeManager = class {
             name: result.data.name,
             namespace: result.data.namespace
           },
-          WebSocket: globalThis.WebSocket
+          WebSocket: globalThis.WebSocket,
+          destroyHandler: async () => {
+            await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
+              method: "DELETE"
+            });
+          }
         });
         await waitForComputeReady(sandbox);
         return sandbox;
@@ -3627,13 +3773,14 @@ var ComputeManager = class {
        */
       find: async (options) => {
         const config = this.getGatewayConfig();
-        const result = await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/find`, config, {
-          method: "POST",
-          body: JSON.stringify({
+        const result = await waitForSandboxStatus(
+          config,
+          `${config.gatewayUrl}/v1/sandboxes/find`,
+          {
             namespace: options.namespace || "default",
             name: options.name
-          })
-        });
+          }
+        );
         if (!result.success || !result.data) {
           return null;
         }
@@ -3648,7 +3795,12 @@ var ComputeManager = class {
             name,
             namespace
           },
-          WebSocket: globalThis.WebSocket
+          WebSocket: globalThis.WebSocket,
+          destroyHandler: async () => {
+            await gatewayFetch(`${config.gatewayUrl}/v1/sandboxes/${sandboxId}`, config, {
+              method: "DELETE"
+            });
+          }
         });
         await waitForComputeReady(sandbox);
         return sandbox;
@@ -3689,7 +3841,7 @@ var ComputeManager = class {
 
 Options:
 1. Zero-config: Set COMPUTESDK_API_KEY and provider credentials (e.g., E2B_API_KEY)
-2. Explicit: Call compute.setConfig({ provider: "e2b", apiKey: "...", e2b: { apiKey: "..." } })
+2. Explicit: Call compute.setConfig({ provider: "e2b", computesdkApiKey: "...", e2b: { apiKey: "..." } })
 3. Use provider directly: import { e2b } from '@computesdk/e2b'
 
 Docs: https://computesdk.com/docs/quickstart`