computesdk 1.10.2 → 1.11.0

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());
@@ -728,7 +739,7 @@ var TerminalCommand = class {
    */
   async run(command, options) {
     const response = await this.runHandler(command, options?.background);
-    const cmd2 = new Command({
+    const cmd = new Command({
       cmdId: response.data.cmd_id || "",
       terminalId: this.terminalId,
       command: response.data.command,
@@ -739,9 +750,9 @@ var TerminalCommand = class {
       durationMs: response.data.duration_ms,
       startedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
-    cmd2.setWaitHandler((timeout) => this.waitHandler(cmd2.id, timeout));
-    cmd2.setRetrieveHandler(() => this.retrieveHandler(cmd2.id));
-    return cmd2;
+    cmd.setWaitHandler((timeout) => this.waitHandler(cmd.id, timeout));
+    cmd.setRetrieveHandler(() => this.retrieveHandler(cmd.id));
+    return cmd;
   }
   /**
    * List all commands executed in this terminal
@@ -750,7 +761,7 @@ var TerminalCommand = class {
   async list() {
     const response = await this.listHandler();
     return response.data.commands.map((item) => {
-      const cmd2 = new Command({
+      const cmd = new Command({
         cmdId: item.cmd_id,
         terminalId: this.terminalId,
         command: item.command,
@@ -764,9 +775,9 @@ var TerminalCommand = class {
         startedAt: item.started_at,
         finishedAt: item.finished_at
       });
-      cmd2.setWaitHandler((timeout) => this.waitHandler(cmd2.id, timeout));
-      cmd2.setRetrieveHandler(() => this.retrieveHandler(cmd2.id));
-      return cmd2;
+      cmd.setWaitHandler((timeout) => this.waitHandler(cmd.id, timeout));
+      cmd.setRetrieveHandler(() => this.retrieveHandler(cmd.id));
+      return cmd;
     });
   }
   /**
@@ -776,7 +787,7 @@ var TerminalCommand = class {
    */
   async retrieve(cmdId) {
     const response = await this.retrieveHandler(cmdId);
-    const cmd2 = new Command({
+    const cmd = new Command({
       cmdId: response.data.cmd_id,
       terminalId: this.terminalId,
       command: response.data.command,
@@ -788,9 +799,9 @@ var TerminalCommand = class {
       startedAt: response.data.started_at,
       finishedAt: response.data.finished_at
     });
-    cmd2.setWaitHandler((timeout) => this.waitHandler(cmd2.id, timeout));
-    cmd2.setRetrieveHandler(() => this.retrieveHandler(cmd2.id));
-    return cmd2;
+    cmd.setWaitHandler((timeout) => this.waitHandler(cmd.id, timeout));
+    cmd.setRetrieveHandler(() => this.retrieveHandler(cmd.id));
+    return cmd;
   }
 };
 
@@ -1011,6 +1022,7 @@ var TerminalInstance = class {
       throw new Error("Destroy handler not set");
     }
     await this._destroyHandler();
+    this._status = "stopped";
     this.cleanup();
   }
   /**
@@ -1810,6 +1822,8 @@ var Run = class {
    * @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
    */
   async command(command, options) {
@@ -1914,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) {
@@ -1935,7 +1950,7 @@ var Sandbox = class {
         await this.writeFile(path, content);
       },
       mkdir: async (path) => {
-        await this.runCommand((0, import_cmd.mkdir)(path));
+        await this.runCommand((0, import_cmd.escapeArgs)((0, import_cmd.mkdir)(path)));
       },
       readdir: async (path) => {
         const response = await this.listFiles(path);
@@ -1947,7 +1962,7 @@ var Sandbox = class {
         }));
       },
       exists: async (path) => {
-        const result = await this.runCommand(import_cmd.test.exists(path));
+        const result = await this.runCommand((0, import_cmd.escapeArgs)(import_cmd.test.exists(path)));
         return result.exitCode === 0;
       },
       remove: async (path) => {
@@ -1972,7 +1987,13 @@ var Sandbox = class {
         };
       },
       command: async (command, options) => {
-        const result = await this.runCommandRequest({ command, shell: options?.shell, background: options?.background });
+        const result = await this.runCommandRequest({
+          command,
+          shell: options?.shell,
+          background: options?.background,
+          cwd: options?.cwd,
+          env: options?.env
+        });
         return {
           stdout: result.data.stdout,
           stderr: result.data.stderr,
@@ -2286,12 +2307,14 @@ API request failed (${response.status}): ${error}`
     });
   }
   /**
-   * 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
@@ -2329,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 || "";
   }
@@ -2357,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"
     });
   }
@@ -2376,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,
@@ -2888,29 +2917,104 @@ API request failed (${response.status}): ${error}`
     return this.run.code(code, language ? { language } : void 0);
   }
   /**
-   * 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),
+   * })
+   * ```
    */
-  async runCommand(commandOrArray, argsOrOptions, maybeOptions) {
-    let commandParts;
-    let options;
-    if (Array.isArray(commandOrArray)) {
-      commandParts = commandOrArray;
-      options = argsOrOptions;
-    } else {
-      const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
-      commandParts = [commandOrArray, ...args];
-      options = Array.isArray(argsOrOptions) ? maybeOptions : argsOrOptions;
+  async runCommand(command, options) {
+    const hasStreamingCallbacks = options?.onStdout || options?.onStderr;
+    if (!hasStreamingCallbacks) {
+      return this.run.command(command, options);
     }
-    const finalCommand = (0, import_cmd.cmd)(commandParts, options);
-    const fullCommand = (0, import_cmd.escapeArgs)(finalCommand);
-    return this.run.command(fullCommand, { background: options?.background });
+    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
@@ -2963,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
@@ -3404,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`
     );
@@ -3414,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
@@ -3530,7 +3648,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;
@@ -3551,7 +3674,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;
@@ -3601,7 +3729,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;
@@ -3632,7 +3765,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;
@@ -3673,7 +3811,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`