instavm 0.3.0 → 0.8.0

package/README.md

@@ -21,7 +21,7 @@ npm install instavm
 
 ## Quick Start
 
-### Code Execution
+### Code Execution (Cloud Mode)
 
 ```typescript
 import { InstaVM, ExecutionError, NetworkError } from 'instavm';
@@ -30,7 +30,7 @@ import { InstaVM, ExecutionError, NetworkError } from 'instavm';
 const client = new InstaVM('your_api_key');
 
 try {
-    // Execute a command  
+    // Execute a command
     const result = await client.execute("print(100**100)");
     console.log(result);
 
@@ -49,6 +49,44 @@ try {
 }
 ```
 
+### Local Execution Mode
+
+Run code execution against a local container (e.g., [coderunner](https://github.com/instavm/coderunner)) instead of the cloud API:
+
+```typescript
+import { InstaVM } from 'instavm';
+
+// Create client in local mode (no API key required)
+const client = new InstaVM('', {
+    local: true,
+    localURL: 'http://coderunner.local:8222'  // Optional, defaults to this URL
+});
+
+// Execute code locally without session management
+const result = await client.execute("print('Hello from local container!')");
+console.log(result.output);
+
+// Browser automation in local mode (no session required)
+const content = await client.browser.extractContent({
+    url: 'https://example.com',
+    includeInteractive: true,
+    includeAnchors: true
+});
+console.log('Page title:', content.readableContent.title);
+console.log('Clean content:', content.readableContent.content);
+```
+
+**Note:** Local mode supports:
+- ✅ Code execution (`execute()`)
+- ✅ Browser navigation (`browser.navigate()`)
+- ✅ Content extraction (`browser.extractContent()`)
+
+Local mode does NOT support (cloud-only features):
+- ❌ Session management (`createSession()`, `closeSession()`, `getUsage()`)
+- ❌ File upload/download
+- ❌ Async execution
+- ❌ Browser session creation and complex interactions
+
 ### File Upload
 
 ```typescript
@@ -494,19 +532,20 @@ if (signupLink) {
 
 ```typescript
 import {
-    InstaVMError,           // Base error class
-    AuthenticationError,    // API key issues
-    RateLimitError,        // Rate limiting (has retryAfter property)
-    QuotaExceededError,    // Usage quota exceeded
-    NetworkError,          // Connection issues
-    ExecutionError,        // Code execution failures
-    SessionError,          // Session management issues
-    BrowserError,          // General browser errors
-    BrowserSessionError,   // Browser session issues
-    BrowserInteractionError, // Browser interaction failures
-    BrowserTimeoutError,   // Browser operation timeouts
-    BrowserNavigationError, // Navigation failures
-    ElementNotFoundError   // Element selection issues (has selector property)
+    InstaVMError,              // Base error class
+    AuthenticationError,       // API key issues
+    RateLimitError,           // Rate limiting (has retryAfter property)
+    QuotaExceededError,       // Usage quota exceeded
+    NetworkError,             // Connection issues
+    ExecutionError,           // Code execution failures
+    SessionError,             // Session management issues
+    BrowserError,             // General browser errors
+    BrowserSessionError,      // Browser session issues
+    BrowserInteractionError,  // Browser interaction failures
+    BrowserTimeoutError,      // Browser operation timeouts
+    BrowserNavigationError,   // Navigation failures
+    ElementNotFoundError,     // Element selection issues (has selector property)
+    UnsupportedOperationError // Operation not supported in local mode
 } from 'instavm';
 
 // Specific error handling
@@ -573,10 +612,12 @@ class InstaVM {
 
 ```typescript
 interface InstaVMOptions {
-    baseURL?: string;        // Default: 'https://api.instavm.io'
+    baseURL?: string;        // Default: 'https://api.instavm.io' (ignored if local=true)
     timeout?: number;        // Default: 300000 (5 minutes)
     maxRetries?: number;     // Default: 3
     retryDelay?: number;     // Default: 1000ms
+    local?: boolean;         // Default: false - Use local container instead of cloud
+    localURL?: string;       // Default: 'http://coderunner.local:8222' - Local container URL
 }
 
 interface ExecuteOptions {
@@ -845,6 +886,14 @@ All rights reserved. No redistribution or modification permitted.
 
 ## Changelog
 
+### Version 0.4.0
+
+- ✅ **NEW**: Local execution mode support - Run code execution against local containers
+- ✅ **NEW**: Local browser automation - Navigate and extract content without sessions
+- ✅ **NEW**: `UnsupportedOperationError` - Better error messages for cloud-only features
+- ✅ Parity with Python SDK v0.4.0 local mode features
+- ✅ Improved flexibility for on-premise deployments
+
 ### Version 0.3.0
 
 - ✅ **NEW**: File download functionality - Download files from remote VM

package/dist/index.d.mts

@@ -44,11 +44,11 @@ declare class HTTPClient {
     /**
      * POST request with JSON body
      */
-    post<T = any>(url: string, data?: any, headers?: Record<string, string>): Promise<T>;
+    post<T = any>(url: string, data?: any, headers?: Record<string, string>, timeout?: number): Promise<T>;
     /**
      * POST request for code execution (uses X-API-Key header like Python client)
      */
-    postExecution<T = any>(url: string, data: any, headers?: Record<string, string>): Promise<T>;
+    postExecution<T = any>(url: string, data: any, headers?: Record<string, string>, timeout?: number): Promise<T>;
     /**
      * POST request with form data (for file uploads)
      */
@@ -151,6 +151,7 @@ interface ExtractOptions {
     maxResults?: number;
 }
 interface ExtractContentOptions {
+    url?: string;
     includeInteractive?: boolean;
     includeAnchors?: boolean;
     maxAnchors?: number;
@@ -265,7 +266,8 @@ declare class BrowserSession extends EventEmitter {
 declare class BrowserManager {
     private httpClient;
     private activeSessions;
-    constructor(httpClient: HTTPClient);
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
     /**
      * Create a new browser session
      */
@@ -290,6 +292,14 @@ declare class BrowserManager {
      * Close all active sessions
      */
     closeAllSessions(): Promise<void>;
+    /**
+     * Navigate to a URL (local mode support - no session required)
+     */
+    navigate(url: string, options?: NavigateOptions): Promise<NavigationResult>;
+    /**
+     * Extract LLM-friendly content (local mode support - no session required)
+     */
+    extractContent(options?: ExtractContentOptions): Promise<ExtractedContent>;
     /**
      * Clean up resources
      */
@@ -350,9 +360,15 @@ interface DownloadResult {
 
 interface InstaVMOptions {
     baseURL?: string;
+    /**
+     * Timeout in milliseconds. Used for HTTP request timeout and sent to API as VM lifetime (in seconds).
+     * Default: 300000 (5 minutes)
+     */
     timeout?: number;
     maxRetries?: number;
     retryDelay?: number;
+    local?: boolean;
+    localURL?: string;
 }
 /**
  * Main InstaVM client class
@@ -361,9 +377,20 @@ declare class InstaVM {
     private httpClient;
     private _sessionId;
     readonly browser: BrowserManager;
+    readonly local: boolean;
+    private readonly timeout;
     constructor(apiKey: string, options?: InstaVMOptions);
+    /**
+     * Ensure operation is not called in local mode
+     */
+    private ensureNotLocal;
     /**
      * Execute code synchronously
+     *
+     * @param command - Command to execute
+     * @param options - Execution options
+     * @param options.timeout - Request timeout in milliseconds (used for HTTP request timeout and sent to API in seconds)
+     * @returns Execution result
      */
     execute(command: string, options?: ExecuteOptions): Promise<ExecutionResult>;
     /**
@@ -491,5 +518,11 @@ declare class ElementNotFoundError extends BrowserError {
     readonly selector?: string;
     constructor(message?: string, selector?: string, options?: any);
 }
+/**
+ * Unsupported operation error (e.g., operations not available in local mode)
+ */
+declare class UnsupportedOperationError extends InstaVMError {
+    constructor(message?: string, options?: any);
+}
 
-export { type ApiResponse, type AsyncExecutionResult, AuthenticationError, BrowserError, BrowserInteractionError, BrowserManager, BrowserNavigationError, BrowserSession, BrowserSessionError, type BrowserSessionInfo, type BrowserSessionOptions, BrowserTimeoutError, type ClickOptions, type ContentAnchor, type DownloadOptions, type DownloadResult, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractContentOptions, type ExtractOptions, type ExtractedContent, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, type InteractiveElement, type NavigateOptions, type NavigationResult, NetworkError, QuotaExceededError, RateLimitError, type RequestConfig, type RetryConfig, type ScreenshotOptions, type ScrollOptions, SessionError, type TypeOptions, type UploadOptions, type UploadResult, type UsageStats, type WaitCondition };
+export { type ApiResponse, type AsyncExecutionResult, AuthenticationError, BrowserError, BrowserInteractionError, BrowserManager, BrowserNavigationError, BrowserSession, BrowserSessionError, type BrowserSessionInfo, type BrowserSessionOptions, BrowserTimeoutError, type ClickOptions, type ContentAnchor, type DownloadOptions, type DownloadResult, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractContentOptions, type ExtractOptions, type ExtractedContent, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, type InteractiveElement, type NavigateOptions, type NavigationResult, NetworkError, QuotaExceededError, RateLimitError, type RequestConfig, type RetryConfig, type ScreenshotOptions, type ScrollOptions, SessionError, type TypeOptions, UnsupportedOperationError, type UploadOptions, type UploadResult, type UsageStats, type WaitCondition };

package/dist/index.d.ts

@@ -44,11 +44,11 @@ declare class HTTPClient {
     /**
      * POST request with JSON body
      */
-    post<T = any>(url: string, data?: any, headers?: Record<string, string>): Promise<T>;
+    post<T = any>(url: string, data?: any, headers?: Record<string, string>, timeout?: number): Promise<T>;
     /**
      * POST request for code execution (uses X-API-Key header like Python client)
      */
-    postExecution<T = any>(url: string, data: any, headers?: Record<string, string>): Promise<T>;
+    postExecution<T = any>(url: string, data: any, headers?: Record<string, string>, timeout?: number): Promise<T>;
     /**
      * POST request with form data (for file uploads)
      */
@@ -151,6 +151,7 @@ interface ExtractOptions {
     maxResults?: number;
 }
 interface ExtractContentOptions {
+    url?: string;
     includeInteractive?: boolean;
     includeAnchors?: boolean;
     maxAnchors?: number;
@@ -265,7 +266,8 @@ declare class BrowserSession extends EventEmitter {
 declare class BrowserManager {
     private httpClient;
     private activeSessions;
-    constructor(httpClient: HTTPClient);
+    private local;
+    constructor(httpClient: HTTPClient, local?: boolean);
     /**
      * Create a new browser session
      */
@@ -290,6 +292,14 @@ declare class BrowserManager {
      * Close all active sessions
      */
     closeAllSessions(): Promise<void>;
+    /**
+     * Navigate to a URL (local mode support - no session required)
+     */
+    navigate(url: string, options?: NavigateOptions): Promise<NavigationResult>;
+    /**
+     * Extract LLM-friendly content (local mode support - no session required)
+     */
+    extractContent(options?: ExtractContentOptions): Promise<ExtractedContent>;
     /**
      * Clean up resources
      */
@@ -350,9 +360,15 @@ interface DownloadResult {
 
 interface InstaVMOptions {
     baseURL?: string;
+    /**
+     * Timeout in milliseconds. Used for HTTP request timeout and sent to API as VM lifetime (in seconds).
+     * Default: 300000 (5 minutes)
+     */
     timeout?: number;
     maxRetries?: number;
     retryDelay?: number;
+    local?: boolean;
+    localURL?: string;
 }
 /**
  * Main InstaVM client class
@@ -361,9 +377,20 @@ declare class InstaVM {
     private httpClient;
     private _sessionId;
     readonly browser: BrowserManager;
+    readonly local: boolean;
+    private readonly timeout;
     constructor(apiKey: string, options?: InstaVMOptions);
+    /**
+     * Ensure operation is not called in local mode
+     */
+    private ensureNotLocal;
     /**
      * Execute code synchronously
+     *
+     * @param command - Command to execute
+     * @param options - Execution options
+     * @param options.timeout - Request timeout in milliseconds (used for HTTP request timeout and sent to API in seconds)
+     * @returns Execution result
      */
     execute(command: string, options?: ExecuteOptions): Promise<ExecutionResult>;
     /**
@@ -491,5 +518,11 @@ declare class ElementNotFoundError extends BrowserError {
     readonly selector?: string;
     constructor(message?: string, selector?: string, options?: any);
 }
+/**
+ * Unsupported operation error (e.g., operations not available in local mode)
+ */
+declare class UnsupportedOperationError extends InstaVMError {
+    constructor(message?: string, options?: any);
+}
 
-export { type ApiResponse, type AsyncExecutionResult, AuthenticationError, BrowserError, BrowserInteractionError, BrowserManager, BrowserNavigationError, BrowserSession, BrowserSessionError, type BrowserSessionInfo, type BrowserSessionOptions, BrowserTimeoutError, type ClickOptions, type ContentAnchor, type DownloadOptions, type DownloadResult, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractContentOptions, type ExtractOptions, type ExtractedContent, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, type InteractiveElement, type NavigateOptions, type NavigationResult, NetworkError, QuotaExceededError, RateLimitError, type RequestConfig, type RetryConfig, type ScreenshotOptions, type ScrollOptions, SessionError, type TypeOptions, type UploadOptions, type UploadResult, type UsageStats, type WaitCondition };
+export { type ApiResponse, type AsyncExecutionResult, AuthenticationError, BrowserError, BrowserInteractionError, BrowserManager, BrowserNavigationError, BrowserSession, BrowserSessionError, type BrowserSessionInfo, type BrowserSessionOptions, BrowserTimeoutError, type ClickOptions, type ContentAnchor, type DownloadOptions, type DownloadResult, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractContentOptions, type ExtractOptions, type ExtractedContent, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, type InteractiveElement, type NavigateOptions, type NavigationResult, NetworkError, QuotaExceededError, RateLimitError, type RequestConfig, type RetryConfig, type ScreenshotOptions, type ScrollOptions, SessionError, type TypeOptions, UnsupportedOperationError, type UploadOptions, type UploadResult, type UsageStats, type WaitCondition };

package/dist/index.js

@@ -46,7 +46,8 @@ __export(index_exports, {
   NetworkError: () => NetworkError,
   QuotaExceededError: () => QuotaExceededError,
   RateLimitError: () => RateLimitError,
-  SessionError: () => SessionError
+  SessionError: () => SessionError,
+  UnsupportedOperationError: () => UnsupportedOperationError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -131,6 +132,11 @@ var ElementNotFoundError = class extends BrowserError {
     this.selector = selector;
   }
 };
+var UnsupportedOperationError = class extends InstaVMError {
+  constructor(message = "Operation not supported", options) {
+    super(message, options);
+  }
+};
 
 // src/utils/retry.ts
 function defaultRetryCondition(error) {
@@ -272,18 +278,19 @@ var HTTPClient = class {
   /**
    * POST request with JSON body
    */
-  async post(url, data, headers) {
+  async post(url, data, headers, timeout) {
     return this.request({
       method: "POST",
       url,
       data,
-      headers
+      headers,
+      timeout
     });
   }
   /**
    * POST request for code execution (uses X-API-Key header like Python client)
    */
-  async postExecution(url, data, headers) {
+  async postExecution(url, data, headers, timeout) {
     const requestHeaders = {
       "X-API-Key": this.config.apiKey,
       ...headers
@@ -292,7 +299,8 @@ var HTTPClient = class {
       method: "POST",
       url,
       data,
-      headers: requestHeaders
+      headers: requestHeaders,
+      timeout
     });
   }
   /**
@@ -706,14 +714,20 @@ var BrowserSession = class extends import_eventemitter3.EventEmitter {
 
 // src/client/BrowserManager.ts
 var BrowserManager = class {
-  constructor(httpClient) {
+  constructor(httpClient, local = false) {
     this.activeSessions = /* @__PURE__ */ new Map();
     this.httpClient = httpClient;
+    this.local = local;
   }
   /**
    * Create a new browser session
    */
   async createSession(options = {}) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        "Browser session management is not supported in local mode. Use navigate() or extractContent() with URL directly."
+      );
+    }
     const requestData = {
       viewport_width: options.viewportWidth || 1920,
       viewport_height: options.viewportHeight || 1080,
@@ -812,6 +826,77 @@ var BrowserManager = class {
     );
     this.activeSessions.clear();
   }
+  /**
+   * Navigate to a URL (local mode support - no session required)
+   */
+  async navigate(url, options = {}) {
+    if (!this.local) {
+      throw new UnsupportedOperationError(
+        "navigate() without session is only supported in local mode. In cloud mode, create a session first."
+      );
+    }
+    const requestData = {
+      url,
+      wait_timeout: options.waitTimeout || 3e4
+    };
+    try {
+      const response = await this.httpClient.post(
+        "/v1/browser/interactions/navigate",
+        requestData
+      );
+      return {
+        success: response.success !== false,
+        url: response.url || url,
+        title: response.title,
+        status: response.status
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new BrowserNavigationError(
+        `Navigation failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
+  /**
+   * Extract LLM-friendly content (local mode support - no session required)
+   */
+  async extractContent(options = {}) {
+    if (!this.local) {
+      throw new UnsupportedOperationError(
+        "extractContent() without session is only supported in local mode. In cloud mode, create a session first."
+      );
+    }
+    if (!options.url) {
+      throw new BrowserInteractionError("url is required in local mode");
+    }
+    const requestData = {
+      url: options.url,
+      include_interactive: options.includeInteractive !== false,
+      include_anchors: options.includeAnchors !== false,
+      max_anchors: options.maxAnchors ?? 50
+    };
+    try {
+      const response = await this.httpClient.post(
+        "/v1/browser/interactions/content",
+        requestData
+      );
+      return {
+        readableContent: {
+          ...response.readable_content || {},
+          content: response.readable_content?.content || ""
+        },
+        interactiveElements: response.interactive_elements,
+        contentAnchors: response.content_anchors
+      };
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new BrowserInteractionError(
+        `Content extraction failed: ${errorMessage}`,
+        { cause: error }
+      );
+    }
+  }
   /**
    * Clean up resources
    */
@@ -825,38 +910,61 @@ var import_form_data = __toESM(require("form-data"));
 var InstaVM = class {
   constructor(apiKey, options = {}) {
     this._sessionId = null;
-    if (!apiKey) {
-      throw new Error("API key is required");
+    this.local = options.local || false;
+    this.timeout = options.timeout || 3e5;
+    if (!this.local && !apiKey) {
+      throw new AuthenticationError("API key is required for cloud mode");
     }
     const config = {
-      baseURL: options.baseURL || "https://api.instavm.io",
-      timeout: options.timeout || 3e5,
-      // 5 minutes
+      baseURL: this.local ? options.localURL || "http://coderunner.local:8222" : options.baseURL || "https://api.instavm.io",
+      timeout: this.timeout,
       maxRetries: options.maxRetries || 3,
       retryDelay: options.retryDelay || 1e3,
-      apiKey
+      apiKey: apiKey || ""
     };
     this.httpClient = new HTTPClient(config);
-    this.browser = new BrowserManager(this.httpClient);
+    this.browser = new BrowserManager(this.httpClient, this.local);
+  }
+  /**
+   * Ensure operation is not called in local mode
+   */
+  ensureNotLocal(operationName) {
+    if (this.local) {
+      throw new UnsupportedOperationError(
+        `${operationName} is not supported in local mode. This operation is only available when using the cloud API.`
+      );
+    }
   }
   /**
    * Execute code synchronously
+   *
+   * @param command - Command to execute
+   * @param options - Execution options
+   * @param options.timeout - Request timeout in milliseconds (used for HTTP request timeout and sent to API in seconds)
+   * @returns Execution result
    */
   async execute(command, options = {}) {
     let sessionId = options.sessionId || this._sessionId;
-    if (!sessionId) {
+    if (!this.local && !sessionId) {
       sessionId = await this.createSession();
     }
     const requestData = {
       command,
-      language: options.language || "python",
-      timeout: options.timeout || 15,
-      session_id: sessionId
+      language: options.language || "python"
     };
+    if (options.timeout !== void 0) {
+      requestData.timeout = Math.floor(options.timeout / 1e3);
+    }
+    if (!this.local && sessionId) {
+      requestData.session_id = sessionId;
+    }
+    const requestTimeout = options.timeout !== void 0 ? options.timeout : this.timeout;
     try {
       const response = await this.httpClient.postExecution(
         "/execute",
-        requestData
+        requestData,
+        void 0,
+        requestTimeout
       );
       if (response.session_id) {
         this._sessionId = response.session_id;
@@ -882,6 +990,7 @@ var InstaVM = class {
    * Execute code asynchronously
    */
   async executeAsync(command, options = {}) {
+    this.ensureNotLocal("Async execution");
     let sessionId = options.sessionId || this._sessionId;
     if (!sessionId) {
       sessionId = await this.createSession();
@@ -923,6 +1032,7 @@ var InstaVM = class {
    * Upload files to the execution environment
    */
   async upload(files, options = {}) {
+    this.ensureNotLocal("File upload");
     const formData = new import_form_data.default();
     for (const file of files) {
       if (Buffer.isBuffer(file.content)) {
@@ -965,9 +1075,11 @@ var InstaVM = class {
    * Create a new execution session
    */
   async createSession() {
+    this.ensureNotLocal("Session management");
     try {
       const response = await this.httpClient.post("/v1/sessions/session", {
-        api_key: this.httpClient.apiKey
+        api_key: this.httpClient.apiKey,
+        vm_lifetime_seconds: Math.floor(this.timeout / 1e3)
       });
       if (response.session_id) {
         this._sessionId = response.session_id;
@@ -1004,6 +1116,7 @@ var InstaVM = class {
    * Get usage statistics for a session
    */
   async getUsage(sessionId) {
+    this.ensureNotLocal("Usage tracking");
     const targetSessionId = sessionId || this._sessionId;
     if (!targetSessionId) {
       throw new SessionError("No active session to get usage for");
@@ -1030,6 +1143,7 @@ var InstaVM = class {
    * Download a file from the remote VM
    */
   async download(filename, options = {}) {
+    this.ensureNotLocal("File download");
     const targetSessionId = options.sessionId || this._sessionId;
     if (!targetSessionId) {
       throw new SessionError("No active session to download from");
@@ -1087,6 +1201,7 @@ var InstaVM = class {
   NetworkError,
   QuotaExceededError,
   RateLimitError,
-  SessionError
+  SessionError,
+  UnsupportedOperationError
 });
 //# sourceMappingURL=index.js.map