computesdk 1.10.3 → 1.11.1

package/dist/index.mjs

@@ -485,6 +485,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());
@@ -958,6 +969,7 @@ var TerminalInstance = class {
       throw new Error("Destroy handler not set");
     }
     await this._destroyHandler();
+    this._status = "stopped";
     this.cleanup();
   }
   /**
@@ -1863,7 +1875,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) {
@@ -2286,18 +2299,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 || "";
   }
@@ -2314,7 +2333,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"
     });
   }
@@ -2333,7 +2352,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,
@@ -2855,6 +2874,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
@@ -2870,10 +2891,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
@@ -2926,9 +3014,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
@@ -3367,9 +3461,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`
     );
@@ -3377,7 +3479,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
@@ -3465,6 +3567,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;
@@ -3493,7 +3623,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;
@@ -3514,7 +3649,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;
@@ -3542,14 +3682,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`);
         }
@@ -3564,7 +3705,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;
@@ -3574,13 +3720,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;
         }
@@ -3595,7 +3742,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;
@@ -3636,7 +3788,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`