instavm 0.8.0 → 0.8.3

package/README.md

@@ -64,7 +64,7 @@ const client = new InstaVM('', {
 
 // Execute code locally without session management
 const result = await client.execute("print('Hello from local container!')");
-console.log(result.output);
+console.log(result.stdout);
 
 // Browser automation in local mode (no session required)
 const content = await client.browser.extractContent({
@@ -94,6 +94,9 @@ import { InstaVM } from 'instavm';
 
 const client = new InstaVM('your_api_key');
 
+// Create a session first (required for upload)
+await client.createSession();
+
 // Upload files to the execution environment
 const files = [
     {
@@ -110,7 +113,7 @@ console.log(result);
 const execution = await client.execute('python /remote/path/script.py', {
     language: 'bash'
 });
-console.log(execution.output);
+console.log(execution.stdout);
 ```
 
 ### File Download
@@ -170,13 +173,18 @@ import { InstaVM } from 'instavm';
 
 const client = new InstaVM('your_api_key');
 
-// Execute command asynchronously (returns task info)
+// Execute command asynchronously (returns task ID)
 const result = await client.executeAsync("sleep 5 && echo 'Long task complete!'", {
     language: 'bash'
 });
-
-console.log(`Task ${result.taskId} status: ${result.status}`);
-console.log(`Output so far: ${result.output}`);
+const taskId = result.taskId;
+console.log(`Task ${taskId} is running in background...`);
+
+// Poll for task result
+const taskResult = await client.getTaskResult(taskId, 2, 30);
+console.log('Task complete!');
+console.log(`Stdout: ${taskResult.stdout}`);
+console.log(`Stderr: ${taskResult.stderr}`);
 ```
 
 ## Browser Automation
@@ -319,7 +327,7 @@ data = {"terms": search_terms, "timestamp": "2024-01-01"}
 print(json.dumps(data))
 `);
 
-const searchData = JSON.parse(dataPrep.output.trim());
+const searchData = JSON.parse(dataPrep.stdout.trim());
 
 // Use browser to search and collect results
 const session = await client.browser.createSession();
@@ -359,7 +367,7 @@ top_words = sorted(word_counts.items(), key=lambda x: x[1], reverse=True)[:10]
 print("Top words:", top_words)
 `);
 
-console.log(analysis.output);
+console.log(analysis.stdout);
 await client.dispose();
 ```
 
@@ -385,7 +393,7 @@ print(f"Std: {data['numbers'].std():.2f}")
 print(f"Categories: {data['categories'].value_counts().to_dict()}")
 `);
 
-console.log(result.output);
+console.log(result.stdout);
 ```
 
 ### Bash Commands
@@ -404,7 +412,7 @@ echo "Memory Info:"
 free -h
 `, { language: 'bash' });
 
-console.log(sysInfo.output);
+console.log(sysInfo.stdout);
 ```
 
 ### Session Persistence
@@ -415,7 +423,19 @@ await client.execute('data = [1, 2, 3, 4, 5]');
 await client.execute('total = sum(data)');
 
 const result = await client.execute('print(f"Total: {total}, Average: {total/len(data)}")');
-console.log(result.output); // Output: Total: 15, Average: 3.0
+console.log(result.stdout); // Output: Total: 15, Average: 3.0
+```
+
+### Session Status Check
+
+```typescript
+// Check if current session is still active
+const isActive = await client.isSessionActive();
+console.log(`Session active: ${isActive}`);
+
+// Check specific session
+const isOtherActive = await client.isSessionActive('session-id-123');
+console.log(`Other session active: ${isOtherActive}`);
 ```
 
 ## Advanced Features
@@ -583,11 +603,12 @@ const client = new InstaVM('your_api_key', {
 ```typescript
 class InstaVM {
     constructor(apiKey: string, options?: InstaVMOptions)
-    
+
     // Code execution
     execute(command: string, options?: ExecuteOptions): Promise<ExecutionResult>
     executeAsync(command: string, options?: ExecuteOptions): Promise<AsyncExecutionResult>
-    
+    getTaskResult(taskId: string, pollInterval?: number, timeout?: number): Promise<TaskResult>
+
     // File operations
     upload(files: FileUpload[], options?: UploadOptions): Promise<UploadResult>
     download(filename: string, options?: DownloadOptions): Promise<DownloadResult>
@@ -595,14 +616,15 @@ class InstaVM {
     // Session management
     createSession(): Promise<string>
     closeSession(sessionId?: string): Promise<void>
+    isSessionActive(sessionId?: string): Promise<boolean>
     getUsage(sessionId?: string): Promise<UsageStats>
-    
+
     // Browser automation
     browser: BrowserManager
-    
+
     // Properties
     readonly sessionId: string | null
-    
+
     // Cleanup
     dispose(): Promise<void>
 }
@@ -681,13 +703,24 @@ class BrowserSession extends EventEmitter {
 
 ```typescript
 interface ExecutionResult {
-    output: string;
+    stdout: string;
+    stderr: string;
     success: boolean;
-    executionTime: number;
+    executionTime?: number;
+    cpuTime?: number;
+    createdAt?: string;
     sessionId?: string;
     error?: string;
 }
 
+interface TaskResult {
+    stdout: string;
+    stderr: string;
+    executionTime?: number;
+    cpuTime?: number;
+    createdAt?: string;
+}
+
 interface NavigationResult {
     success: boolean;
     url: string;
@@ -734,7 +767,7 @@ async function withInstaVM(apiKey: string, callback: (client: InstaVM) => Promis
 
 await withInstaVM('your_api_key', async (client) => {
     const result = await client.execute('print("Hello, World!")');
-    console.log(result.output);
+    console.log(result.stdout);
 });
 ```
 
@@ -828,7 +861,7 @@ async function main() {
     
     try {
         const result = await client.execute('print("Hello from CommonJS!")');
-        console.log(result.output);
+        console.log(result.stdout);
     } catch (error) {
         if (error instanceof AuthenticationError) {
             console.error('Authentication failed');
@@ -886,6 +919,17 @@ All rights reserved. No redistribution or modification permitted.
 
 ## Changelog
 
+### Version 0.8.3
+
+- ✅ **NEW**: `getTaskResult()` method - Poll for async task completion with configurable intervals
+- ✅ **NEW**: `isSessionActive()` method - Check if session is still active by querying VM status
+- ✅ **IMPROVED**: Execution result format - Now returns `stdout` and `stderr` separately (matching Python SDK)
+- ✅ **IMPROVED**: Enhanced execution results - Added `cpuTime`, `executionTime`, and `createdAt` fields
+- ✅ **IMPROVED**: Better error messages - Rate limit errors now show `detail` field from API response
+- ✅ **FIXED**: Session status check - Now uses `/v1/sessions/status/` endpoint for accurate VM status
+- ✅ **UPDATED**: closeSession behavior - Sessions auto-expire on server, no longer makes DELETE API call
+- ✅ Full parity with Python SDK v0.8.3
+
 ### Version 0.4.0
 
 - ✅ **NEW**: Local execution mode support - Run code execution against local containers

package/dist/index.d.mts

@@ -53,6 +53,10 @@ declare class HTTPClient {
      * POST request with form data (for file uploads)
      */
     postFormData<T = any>(url: string, formData: FormData, headers?: Record<string, string>): Promise<T>;
+    /**
+     * POST request with URL-encoded form data (like Python requests data= parameter)
+     */
+    postFormUrlEncoded<T = any>(url: string, data: any, headers?: Record<string, string>): Promise<T>;
     /**
      * GET request
      */
@@ -312,9 +316,12 @@ interface ExecuteOptions {
     sessionId?: string;
 }
 interface ExecutionResult {
-    output: string;
+    stdout: string;
+    stderr: string;
     success: boolean;
-    executionTime: number;
+    executionTime?: number;
+    cpuTime?: number;
+    createdAt?: string;
     sessionId?: string;
     error?: string;
 }
@@ -327,6 +334,13 @@ interface AsyncExecutionResult {
     sessionId?: string;
     error?: string;
 }
+interface TaskResult {
+    stdout: string;
+    stderr: string;
+    executionTime?: number;
+    cpuTime?: number;
+    createdAt?: string;
+}
 interface FileUpload {
     name: string;
     content: Buffer | string;
@@ -397,6 +411,16 @@ declare class InstaVM {
      * Execute code asynchronously
      */
     executeAsync(command: string, options?: ExecuteOptions): Promise<AsyncExecutionResult>;
+    /**
+     * Poll for async task result
+     *
+     * @param taskId - The task ID from executeAsync
+     * @param pollInterval - Seconds between polls (default: 1)
+     * @param timeout - Maximum seconds to wait (default: 60)
+     * @returns Task result with stdout, stderr, execution time, etc.
+     * @throws Error if task doesn't complete within timeout
+     */
+    getTaskResult(taskId: string, pollInterval?: number, timeout?: number): Promise<TaskResult>;
     /**
      * Upload files to the execution environment
      */
@@ -407,8 +431,15 @@ declare class InstaVM {
     createSession(): Promise<string>;
     /**
      * Close a session
+     * Note: Sessions auto-expire on the server side. This just clears local state.
      */
     closeSession(sessionId?: string): Promise<void>;
+    /**
+     * Check if current session is still active by checking VM status
+     *
+     * @returns true if session is active, false otherwise
+     */
+    isSessionActive(sessionId?: string): Promise<boolean>;
     /**
      * Get usage statistics for a session
      */

package/dist/index.d.ts

@@ -53,6 +53,10 @@ declare class HTTPClient {
      * POST request with form data (for file uploads)
      */
     postFormData<T = any>(url: string, formData: FormData, headers?: Record<string, string>): Promise<T>;
+    /**
+     * POST request with URL-encoded form data (like Python requests data= parameter)
+     */
+    postFormUrlEncoded<T = any>(url: string, data: any, headers?: Record<string, string>): Promise<T>;
     /**
      * GET request
      */
@@ -312,9 +316,12 @@ interface ExecuteOptions {
     sessionId?: string;
 }
 interface ExecutionResult {
-    output: string;
+    stdout: string;
+    stderr: string;
     success: boolean;
-    executionTime: number;
+    executionTime?: number;
+    cpuTime?: number;
+    createdAt?: string;
     sessionId?: string;
     error?: string;
 }
@@ -327,6 +334,13 @@ interface AsyncExecutionResult {
     sessionId?: string;
     error?: string;
 }
+interface TaskResult {
+    stdout: string;
+    stderr: string;
+    executionTime?: number;
+    cpuTime?: number;
+    createdAt?: string;
+}
 interface FileUpload {
     name: string;
     content: Buffer | string;
@@ -397,6 +411,16 @@ declare class InstaVM {
      * Execute code asynchronously
      */
     executeAsync(command: string, options?: ExecuteOptions): Promise<AsyncExecutionResult>;
+    /**
+     * Poll for async task result
+     *
+     * @param taskId - The task ID from executeAsync
+     * @param pollInterval - Seconds between polls (default: 1)
+     * @param timeout - Maximum seconds to wait (default: 60)
+     * @returns Task result with stdout, stderr, execution time, etc.
+     * @throws Error if task doesn't complete within timeout
+     */
+    getTaskResult(taskId: string, pollInterval?: number, timeout?: number): Promise<TaskResult>;
     /**
      * Upload files to the execution environment
      */
@@ -407,8 +431,15 @@ declare class InstaVM {
     createSession(): Promise<string>;
     /**
      * Close a session
+     * Note: Sessions auto-expire on the server side. This just clears local state.
      */
     closeSession(sessionId?: string): Promise<void>;
+    /**
+     * Check if current session is still active by checking VM status
+     *
+     * @returns true if session is active, false otherwise
+     */
+    isSessionActive(sessionId?: string): Promise<boolean>;
     /**
      * Get usage statistics for a session
      */

package/dist/index.js

@@ -211,7 +211,7 @@ var HTTPClient = class {
         const axiosError = error;
         const status = axiosError.response?.status;
         const data = axiosError.response?.data;
-        const message = data?.message || data?.error || axiosError.message;
+        const message = data?.message || data?.error || data?.detail || axiosError.message;
         switch (status) {
           case 401:
             throw new AuthenticationError(message, {
@@ -223,14 +223,16 @@ var HTTPClient = class {
               statusCode: status,
               response: data
             });
-          case 429:
+          case 429: {
             const retryAfter = parseInt(
               axiosError.response?.headers["retry-after"] || "60"
             );
-            throw new RateLimitError(message, retryAfter, {
+            const rateLimitMessage = data?.detail || message;
+            throw new RateLimitError(rateLimitMessage, retryAfter, {
               statusCode: status,
               response: data
             });
+          }
           case 500:
           case 502:
           case 503:
@@ -308,6 +310,7 @@ var HTTPClient = class {
    */
   async postFormData(url, formData, headers) {
     const requestHeaders = {
+      "X-API-Key": this.config.apiKey,
       ...formData.getHeaders(),
       ...headers
     };
@@ -318,6 +321,26 @@ var HTTPClient = class {
       headers: requestHeaders
     });
   }
+  /**
+   * POST request with URL-encoded form data (like Python requests data= parameter)
+   */
+  async postFormUrlEncoded(url, data, headers) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(data)) {
+      params.append(key, String(value));
+    }
+    const requestHeaders = {
+      "X-API-Key": this.config.apiKey,
+      "Content-Type": "application/x-www-form-urlencoded",
+      ...headers
+    };
+    return this.request({
+      method: "POST",
+      url,
+      data: params.toString(),
+      headers: requestHeaders
+    });
+  }
   /**
    * GET request
    */
@@ -970,9 +993,12 @@ var InstaVM = class {
         this._sessionId = response.session_id;
       }
       return {
-        output: response.stdout || response.output || "",
+        stdout: response.stdout || "",
+        stderr: response.stderr || "",
         success: response.success !== false,
-        executionTime: response.execution_time || 0,
+        executionTime: response.execution_time,
+        cpuTime: response.cpu_time,
+        createdAt: response.created_at,
         sessionId: response.session_id,
         error: response.error
       };
@@ -1028,11 +1054,58 @@ var InstaVM = class {
       );
     }
   }
+  /**
+   * Poll for async task result
+   *
+   * @param taskId - The task ID from executeAsync
+   * @param pollInterval - Seconds between polls (default: 1)
+   * @param timeout - Maximum seconds to wait (default: 60)
+   * @returns Task result with stdout, stderr, execution time, etc.
+   * @throws Error if task doesn't complete within timeout
+   */
+  async getTaskResult(taskId, pollInterval = 1, timeout = 60) {
+    this.ensureNotLocal("Async task result retrieval");
+    const startTime = Date.now();
+    while (Date.now() - startTime < timeout * 1e3) {
+      try {
+        const response = await this.httpClient.get(
+          `/v1/executions/${taskId}`,
+          void 0,
+          { "X-API-Key": this.httpClient.apiKey }
+        );
+        if (response.is_complete) {
+          return {
+            stdout: response.serialized_stdout || "",
+            stderr: response.serialized_stderr || "",
+            cpuTime: response.cpu_time,
+            executionTime: response.execution_time,
+            createdAt: response.created_at
+          };
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollInterval * 1e3));
+      } catch (error) {
+        if (error instanceof AuthenticationError || error instanceof RateLimitError || error instanceof NetworkError) {
+          throw error;
+        }
+        if (Date.now() - startTime >= timeout * 1e3) {
+          throw new ExecutionError(
+            `Failed to get task result: ${error instanceof Error ? error.message : String(error)}`
+          );
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollInterval * 1e3));
+      }
+    }
+    throw new ExecutionError(`Task ${taskId} timed out after ${timeout}s`);
+  }
   /**
    * Upload files to the execution environment
    */
   async upload(files, options = {}) {
     this.ensureNotLocal("File upload");
+    const sessionId = options.sessionId || this._sessionId;
+    if (!sessionId) {
+      throw new SessionError("Session ID not set. Please create a session first using createSession().");
+    }
     const formData = new import_form_data.default();
     for (const file of files) {
       if (Buffer.isBuffer(file.content)) {
@@ -1044,9 +1117,7 @@ var InstaVM = class {
         formData.append("paths", file.path);
       }
     }
-    if (options.sessionId || this._sessionId) {
-      formData.append("session_id", options.sessionId || this._sessionId);
-    }
+    formData.append("session_id", sessionId);
     if (options.remotePath) {
       formData.append("remote_path", options.remotePath);
     }
@@ -1096,20 +1167,39 @@ var InstaVM = class {
   }
   /**
    * Close a session
+   * Note: Sessions auto-expire on the server side. This just clears local state.
    */
   async closeSession(sessionId) {
     const targetSessionId = sessionId || this._sessionId;
     if (!targetSessionId) {
       return;
     }
+    if (targetSessionId === this._sessionId) {
+      this._sessionId = null;
+    }
+  }
+  /**
+   * Check if current session is still active by checking VM status
+   *
+   * @returns true if session is active, false otherwise
+   */
+  async isSessionActive(sessionId) {
+    const targetSessionId = sessionId || this._sessionId;
+    if (!targetSessionId) {
+      return false;
+    }
     try {
-      await this.httpClient.delete(`/v1/sessions/${targetSessionId}`);
-      if (targetSessionId === this._sessionId) {
-        this._sessionId = null;
-      }
+      const response = await this.httpClient.get(
+        `/v1/sessions/status/${targetSessionId}`,
+        void 0,
+        { "X-API-Key": this.httpClient.apiKey }
+      );
+      return response.vm_status === "active";
     } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.warn(`Failed to close session ${targetSessionId}:`, errorMessage);
+      if (error instanceof SessionError || error instanceof AuthenticationError || error instanceof NetworkError) {
+        return false;
+      }
+      return false;
     }
   }
   /**
@@ -1149,11 +1239,12 @@ var InstaVM = class {
       throw new SessionError("No active session to download from");
     }
     try {
-      const response = await this.httpClient.postRaw("/download", {
+      const response = await this.httpClient.postFormUrlEncoded("/download", {
         filename,
         session_id: targetSessionId
       });
-      const content = Buffer.from(response);
+      const encodedContent = response.content || "";
+      const content = encodedContent ? Buffer.from(encodedContent, "base64") : Buffer.from(response);
       return {
         success: true,
         filename,