instavm 0.2.2 → 0.4.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
@@ -75,6 +113,29 @@ const execution = await client.execute('python /remote/path/script.py', {
 console.log(execution.output);
 ```
 
+### File Download
+
+```typescript
+import { InstaVM } from 'instavm';
+import fs from 'fs';
+
+const client = new InstaVM('your_api_key');
+
+// Create a file in the remote environment
+await client.execute(`
+import pandas as pd
+df = pd.DataFrame({'name': ['Alice', 'Bob'], 'age': [25, 30]})
+df.to_csv('data.csv', index=False)
+`);
+
+// Download the file
+const result = await client.download('data.csv');
+console.log(`Downloaded ${result.size} bytes`);
+
+// Save to local file
+fs.writeFileSync('local-data.csv', result.content);
+```
+
 ### Error Handling
 
 ```typescript
@@ -432,25 +493,59 @@ console.log('Articles:', articles);
 console.log('Form fields:', formData);
 ```
 
+### LLM-Friendly Content Extraction
+
+```typescript
+// Extract clean, LLM-optimized content from a webpage
+const content = await session.extractContent({
+    includeInteractive: true,  // Include clickable/typeable elements
+    includeAnchors: true,       // Include content-to-selector mappings
+    maxAnchors: 50              // Limit number of anchors
+});
+
+// Get clean article text (no ads, no navigation, no scripts)
+console.log('Title:', content.readableContent.title);
+console.log('Article:', content.readableContent.content);
+console.log('Author:', content.readableContent.byline);
+
+// Find interactive elements (buttons, links, inputs)
+const loginButton = content.interactiveElements?.find(
+    el => el.text?.toLowerCase().includes('login')
+);
+if (loginButton) {
+    await session.click(loginButton.selector);
+}
+
+// Use content anchors to map text to selectors
+// Perfect for LLM agents that need to "read then click"
+const signupLink = content.contentAnchors?.find(
+    anchor => anchor.text.toLowerCase().includes('sign up')
+);
+if (signupLink) {
+    await session.click(signupLink.selector);
+}
+```
+
 ## Error Handling Reference
 
 ### Error Types
 
 ```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
@@ -495,7 +590,8 @@ class InstaVM {
     
     // File operations
     upload(files: FileUpload[], options?: UploadOptions): Promise<UploadResult>
-    
+    download(filename: string, options?: DownloadOptions): Promise<DownloadResult>
+
     // Session management
     createSession(): Promise<string>
     closeSession(sessionId?: string): Promise<void>
@@ -516,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 {
@@ -565,7 +663,8 @@ class BrowserSession extends EventEmitter {
     // Data extraction
     screenshot(options?: ScreenshotOptions): Promise<string>
     extractElements(selector: string, attributes?: string[]): Promise<ExtractedElement[]>
-    
+    extractContent(options?: ExtractContentOptions): Promise<ExtractedContent>
+
     // Utilities
     wait(condition: WaitCondition, timeout?: number): Promise<void>
     close(): Promise<void>
@@ -750,11 +849,14 @@ main().catch(console.error);
 # Install dependencies
 npm install
 
-# Run unit tests
-npm test
+# Run unit tests (no API key required)
+npm run test:unit
 
 # Run integration tests (requires API key)
-INSTAVM_API_KEY=your_key npm run test:integration
+INSTAVM_API_KEY=your_api_key npm run test:integration
+
+# Run all tests
+npm test
 
 # Build the package
 npm run build
@@ -763,6 +865,8 @@ npm run build
 npm run type-check
 ```
 
+**Note:** Integration tests require a valid InstaVM API key. Set the `INSTAVM_API_KEY` environment variable before running integration tests. Unit tests do not require an API key.
+
 ### Contributing
 
 This is an official SDK. For issues and feature requests, please use the GitHub repository.
@@ -782,6 +886,30 @@ 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
+- ✅ **NEW**: LLM-friendly content extraction - Extract clean, readable content with interactive element mapping
+- ✅ Enhanced browser automation with content anchors for intelligent LLM agents
+- ✅ Full API parity with Python SDK
+
+### Version 0.2.1
+
+- ✅ Bug fixes and improvements
+
+### Version 0.2.0
+
+- ✅ Enhanced session management
+- ✅ Improved error handling
+
 ### Version 0.1.0
 
 - ✅ Code execution fully functional (Python, Bash)

package/dist/index.d.mts

@@ -46,7 +46,7 @@ declare class HTTPClient {
      */
     post<T = any>(url: string, data?: any, headers?: Record<string, string>): Promise<T>;
     /**
-     * POST request for code execution (X-API-Key header is automatically added)
+     * 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>;
     /**
@@ -61,6 +61,10 @@ declare class HTTPClient {
      * DELETE request
      */
     delete<T = any>(url: string, headers?: Record<string, string>): Promise<T>;
+    /**
+     * POST request that returns raw binary data (for file downloads)
+     */
+    postRaw(url: string, data?: any, headers?: Record<string, string>): Promise<ArrayBuffer>;
 }
 
 interface BrowserSessionOptions {
@@ -146,6 +150,35 @@ interface ExtractOptions {
     attributes?: string[];
     maxResults?: number;
 }
+interface ExtractContentOptions {
+    url?: string;
+    includeInteractive?: boolean;
+    includeAnchors?: boolean;
+    maxAnchors?: number;
+}
+interface InteractiveElement {
+    type: 'button' | 'link' | 'input' | 'select' | 'textarea';
+    selector: string;
+    text?: string;
+    label?: string;
+    placeholder?: string;
+    value?: string;
+}
+interface ContentAnchor {
+    text: string;
+    selector: string;
+}
+interface ExtractedContent {
+    readableContent: {
+        content: string;
+        title?: string;
+        byline?: string;
+        excerpt?: string;
+        siteName?: string;
+    };
+    interactiveElements?: InteractiveElement[];
+    contentAnchors?: ContentAnchor[];
+}
 
 /**
  * Browser session for automation
@@ -183,6 +216,32 @@ declare class BrowserSession extends EventEmitter {
      * Extract elements from the page
      */
     extractElements(selector: string, attributes?: string[], options?: ExtractOptions): Promise<ExtractedElement[]>;
+    /**
+     * Extract LLM-friendly content from the current page
+     *
+     * Returns clean article content, interactive elements, and content anchors
+     * for intelligent browser automation with LLMs.
+     *
+     * @param options - Content extraction options
+     * @returns Extracted content with readable text, interactive elements, and content anchors
+     *
+     * @example
+     * ```typescript
+     * const content = await session.extractContent();
+     *
+     * // LLM reads clean content
+     * const article = content.readableContent.content;
+     *
+     * // LLM finds "Sign Up" in content and uses anchors to get selector
+     * const signUpAnchor = content.contentAnchors?.find(
+     *   anchor => anchor.text.toLowerCase().includes('sign up')
+     * );
+     * if (signUpAnchor) {
+     *   await session.click(signUpAnchor.selector);
+     * }
+     * ```
+     */
+    extractContent(options?: ExtractContentOptions): Promise<ExtractedContent>;
     /**
      * Wait for a condition
      */
@@ -207,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
      */
@@ -232,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
      */
@@ -280,12 +348,23 @@ interface UsageStats {
     quotaRemaining: number;
     quotaLimit: number;
 }
+interface DownloadOptions {
+    sessionId?: string;
+}
+interface DownloadResult {
+    success: boolean;
+    filename: string;
+    content: Buffer;
+    size: number;
+}
 
 interface InstaVMOptions {
     baseURL?: string;
     timeout?: number;
     maxRetries?: number;
     retryDelay?: number;
+    local?: boolean;
+    localURL?: string;
 }
 /**
  * Main InstaVM client class
@@ -294,7 +373,12 @@ declare class InstaVM {
     private httpClient;
     private _sessionId;
     readonly browser: BrowserManager;
+    readonly local: boolean;
     constructor(apiKey: string, options?: InstaVMOptions);
+    /**
+     * Ensure operation is not called in local mode
+     */
+    private ensureNotLocal;
     /**
      * Execute code synchronously
      */
@@ -319,6 +403,10 @@ declare class InstaVM {
      * Get usage statistics for a session
      */
     getUsage(sessionId?: string): Promise<UsageStats>;
+    /**
+     * Download a file from the remote VM
+     */
+    download(filename: string, options?: DownloadOptions): Promise<DownloadResult>;
     /**
      * Get the current session ID
      */
@@ -420,5 +508,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, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractOptions, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, 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

@@ -46,7 +46,7 @@ declare class HTTPClient {
      */
     post<T = any>(url: string, data?: any, headers?: Record<string, string>): Promise<T>;
     /**
-     * POST request for code execution (X-API-Key header is automatically added)
+     * 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>;
     /**
@@ -61,6 +61,10 @@ declare class HTTPClient {
      * DELETE request
      */
     delete<T = any>(url: string, headers?: Record<string, string>): Promise<T>;
+    /**
+     * POST request that returns raw binary data (for file downloads)
+     */
+    postRaw(url: string, data?: any, headers?: Record<string, string>): Promise<ArrayBuffer>;
 }
 
 interface BrowserSessionOptions {
@@ -146,6 +150,35 @@ interface ExtractOptions {
     attributes?: string[];
     maxResults?: number;
 }
+interface ExtractContentOptions {
+    url?: string;
+    includeInteractive?: boolean;
+    includeAnchors?: boolean;
+    maxAnchors?: number;
+}
+interface InteractiveElement {
+    type: 'button' | 'link' | 'input' | 'select' | 'textarea';
+    selector: string;
+    text?: string;
+    label?: string;
+    placeholder?: string;
+    value?: string;
+}
+interface ContentAnchor {
+    text: string;
+    selector: string;
+}
+interface ExtractedContent {
+    readableContent: {
+        content: string;
+        title?: string;
+        byline?: string;
+        excerpt?: string;
+        siteName?: string;
+    };
+    interactiveElements?: InteractiveElement[];
+    contentAnchors?: ContentAnchor[];
+}
 
 /**
  * Browser session for automation
@@ -183,6 +216,32 @@ declare class BrowserSession extends EventEmitter {
      * Extract elements from the page
      */
     extractElements(selector: string, attributes?: string[], options?: ExtractOptions): Promise<ExtractedElement[]>;
+    /**
+     * Extract LLM-friendly content from the current page
+     *
+     * Returns clean article content, interactive elements, and content anchors
+     * for intelligent browser automation with LLMs.
+     *
+     * @param options - Content extraction options
+     * @returns Extracted content with readable text, interactive elements, and content anchors
+     *
+     * @example
+     * ```typescript
+     * const content = await session.extractContent();
+     *
+     * // LLM reads clean content
+     * const article = content.readableContent.content;
+     *
+     * // LLM finds "Sign Up" in content and uses anchors to get selector
+     * const signUpAnchor = content.contentAnchors?.find(
+     *   anchor => anchor.text.toLowerCase().includes('sign up')
+     * );
+     * if (signUpAnchor) {
+     *   await session.click(signUpAnchor.selector);
+     * }
+     * ```
+     */
+    extractContent(options?: ExtractContentOptions): Promise<ExtractedContent>;
     /**
      * Wait for a condition
      */
@@ -207,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
      */
@@ -232,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
      */
@@ -280,12 +348,23 @@ interface UsageStats {
     quotaRemaining: number;
     quotaLimit: number;
 }
+interface DownloadOptions {
+    sessionId?: string;
+}
+interface DownloadResult {
+    success: boolean;
+    filename: string;
+    content: Buffer;
+    size: number;
+}
 
 interface InstaVMOptions {
     baseURL?: string;
     timeout?: number;
     maxRetries?: number;
     retryDelay?: number;
+    local?: boolean;
+    localURL?: string;
 }
 /**
  * Main InstaVM client class
@@ -294,7 +373,12 @@ declare class InstaVM {
     private httpClient;
     private _sessionId;
     readonly browser: BrowserManager;
+    readonly local: boolean;
     constructor(apiKey: string, options?: InstaVMOptions);
+    /**
+     * Ensure operation is not called in local mode
+     */
+    private ensureNotLocal;
     /**
      * Execute code synchronously
      */
@@ -319,6 +403,10 @@ declare class InstaVM {
      * Get usage statistics for a session
      */
     getUsage(sessionId?: string): Promise<UsageStats>;
+    /**
+     * Download a file from the remote VM
+     */
+    download(filename: string, options?: DownloadOptions): Promise<DownloadResult>;
     /**
      * Get the current session ID
      */
@@ -420,5 +508,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, ElementNotFoundError, type ExecuteOptions, ExecutionError, type ExecutionResult, type ExtractOptions, type ExtractedElement, type FileUpload, type FillOptions, type HttpClientConfig, InstaVM, InstaVMError, type InstaVMOptions, 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 };