instavm 0.8.1 → 0.11.0

package/README.md

@@ -1,17 +1,8 @@
 # InstaVM JavaScript SDK
 
-A comprehensive JavaScript/TypeScript client library for InstaVM's code execution and browser automation APIs.
+![Build Status](https://github.com/instavm/js/actions/workflows/ci.yml/badge.svg)
 
-## Features
-
-- **Code Execution**: Run Python, Bash, and other languages in secure cloud environments
-- **Browser Automation**: Control web browsers for testing, scraping, and automation  
-- **Session Management**: Automatic session creation and persistent execution contexts
-- **File Operations**: Upload files to execution environments
-- **Async Support**: Execute commands asynchronously for long-running tasks
-- **Error Handling**: Comprehensive exception hierarchy for different failure modes
-- **TypeScript Support**: Full type safety with comprehensive TypeScript definitions
-- **Modern JavaScript**: ES modules, CommonJS, and UMD support
+Official JavaScript/TypeScript client for InstaVM code execution, VM lifecycle, snapshots, networking controls, browser automation, and platform APIs.
 
 ## Installation
 
@@ -21,905 +12,346 @@ npm install instavm
 
 ## Quick Start
 
-### Code Execution (Cloud Mode)
+### Cloud Quick Start
 
 ```typescript
-import { InstaVM, ExecutionError, NetworkError } from 'instavm';
+import { InstaVM } from 'instavm';
 
-// Create client with automatic session management
-const client = new InstaVM('your_api_key');
+const client = new InstaVM(process.env.INSTAVM_API_KEY || 'your_api_key');
 
 try {
-    // Execute a command
-    const result = await client.execute("print(100**100)");
-    console.log(result);
+  const result = await client.execute("print('hello from instavm')");
+  console.log(result.stdout);
 
-    // Get usage info for the session
-    const usage = await client.getUsage();
-    console.log(usage);
-
-} catch (error) {
-    if (error instanceof ExecutionError) {
-        console.log(`Code execution failed: ${error.message}`);
-    } else if (error instanceof NetworkError) {
-        console.log(`Network issue: ${error.message}`);
-    }
+  const usage = await client.getUsage();
+  console.log(usage);
 } finally {
-    await client.dispose();
+  await client.dispose();
 }
 ```
 
-### Local Execution Mode
-
-Run code execution against a local container (e.g., [coderunner](https://github.com/instavm/coderunner)) instead of the cloud API:
+### Local Mode Quick Start
 
 ```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
+  local: true,
+  localURL: 'http://coderunner.local:8222',
 });
 
-// Execute code locally without session management
-const result = await client.execute("print('Hello from local container!')");
-console.log(result.output);
+const result = await client.execute("print('hello from local mode')");
+console.log(result.stdout);
 
-// Browser automation in local mode (no session required)
 const content = await client.browser.extractContent({
-    url: 'https://example.com',
-    includeInteractive: true,
-    includeAnchors: true
+  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
-import { InstaVM } from 'instavm';
-
-const client = new InstaVM('your_api_key');
-
-// Upload files to the execution environment
-const files = [
-    {
-        name: 'script.py',
-        content: 'print("Hello from uploaded file!")',
-        path: '/remote/path/script.py'
-    }
-];
-
-const result = await client.upload(files);
-console.log(result);
-
-// Execute the uploaded file
-const execution = await client.execute('python /remote/path/script.py', {
-    language: 'bash'
-});
-console.log(execution.output);
+console.log(content.readableContent.title);
 ```
 
-### 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`);
+## Table of Contents
 
-// Save to local file
-fs.writeFileSync('local-data.csv', result.content);
-```
-
-### Error Handling
+- [Core Workflows](#core-workflows)
+- [Infrastructure & Platform APIs](#infrastructure-platform-apis)
+- [Browser & Computer Use](#browser-computer-use)
+- [Error Handling](#error-handling)
+- [Development & Testing](#development-testing)
+- [Docs Map (Further Reading)](#docs-map-further-reading)
+- [Version / Changelog](#version-changelog)
 
-```typescript
-import { 
-    InstaVM, 
-    AuthenticationError, 
-    RateLimitError, 
-    SessionError,
-    QuotaExceededError 
-} from 'instavm';
+<a id="core-workflows"></a>
+## Core Workflows
 
-try {
-    const client = new InstaVM('invalid_key');
-    await client.execute('print("test")');
-} catch (error) {
-    if (error instanceof AuthenticationError) {
-        console.log("Invalid API key");
-    } else if (error instanceof RateLimitError) {
-        console.log(`Rate limit exceeded - retry after ${error.retryAfter} seconds`);
-    } else if (error instanceof QuotaExceededError) {
-        console.log("Usage quota exceeded");
-    } else if (error instanceof SessionError) {
-        console.log(`Session error: ${error.message}`);
-    }
-}
-```
+### Cloud Quick Start
 
-### Async Execution
+Cloud mode supports sessions, VM/network controls, platform APIs, and browser sessions.
 
 ```typescript
 import { InstaVM } from 'instavm';
 
-const client = new InstaVM('your_api_key');
-
-// Execute command asynchronously (returns task info)
-const result = await client.executeAsync("sleep 5 && echo 'Long task complete!'", {
-    language: 'bash'
+const client = new InstaVM('your_api_key', {
+  cpu_count: 2,
+  memory_mb: 1024,
+  env: { APP_ENV: 'dev' },
+  metadata: { team: 'platform' },
 });
 
-console.log(`Task ${result.taskId} status: ${result.status}`);
-console.log(`Output so far: ${result.output}`);
+const sessionId = await client.createSession();
+console.log('session:', sessionId);
 ```
 
-## Browser Automation
+### Local Mode Quick Start
 
-### Basic Browser Usage
+Local mode is optimized for direct execution and lightweight browser helpers.
 
 ```typescript
 import { InstaVM } from 'instavm';
 
-const client = new InstaVM('your_api_key');
-
-// Create browser session
-const session = await client.browser.createSession({
-    viewportWidth: 1920,
-    viewportHeight: 1080
-});
-
-// Navigate to website
-await session.navigate('https://example.com');
-
-// Take screenshot
-const screenshot = await session.screenshot();
-console.log(`Screenshot captured: ${screenshot.length} chars`);
-
-// Extract page data
-const elements = await session.extractElements('h1, p', ['text', 'href']);
-console.log('Page content:', elements);
+const client = new InstaVM('', { local: true });
 
-// Clean up
-await session.close();
+await client.execute("print('local execution works')");
+await client.browser.navigate('https://example.com');
 ```
 
-### Advanced Browser Interactions
+### File Operations
 
 ```typescript
-// Navigate with options
-await session.navigate('https://github.com/login', {
-    waitTimeout: 30000,
-    waitUntil: 'networkidle'
-});
-
-// Fill login form
-await session.fill('input[name="login"]', 'username');
-await session.fill('input[name="password"]', 'password');
+import { InstaVM } from 'instavm';
 
-// Click submit button
-await session.click('input[type="submit"]');
+const client = new InstaVM('your_api_key');
+const sessionId = await client.createSession();
 
-// Wait for navigation
-await session.wait({ type: 'navigation' });
+await client.upload(
+  [{ name: 'script.py', content: "print('uploaded')", path: '/app/script.py' }],
+  { sessionId }
+);
 
-// Scroll to load more content
-await session.scroll({ y: 1000 });
+await client.execute('python /app/script.py', { language: 'bash', sessionId });
 
-// Extract dynamic content
-const repos = await session.extractElements('.repo-list-item', ['text']);
-console.log('Repositories found:', repos.length);
+const download = await client.download('output.json', { sessionId });
+console.log(download.filename, download.size);
 ```
 
-### Browser Session Management
+### Async Execution
 
 ```typescript
-// Create session with custom options
-const session = await client.browser.createSession({
-    viewportWidth: 1280,
-    viewportHeight: 720,
-    userAgent: 'CustomBot/1.0'
-});
-
-// Session supports event listeners
-session.on('navigation', (result) => {
-    console.log(`Navigated to: ${result.url}`);
-    console.log(`Page title: ${result.title}`);
-});
-
-session.on('error', (error) => {
-    console.error('Session error:', error.message);
-});
-
-session.on('close', () => {
-    console.log('Session closed');
-});
-
-// Check if session is still active
-if (session.isActive) {
-    await session.navigate('https://example.com');
-}
-```
-
-### Context Manager Pattern
+import { InstaVM } from 'instavm';
 
-```typescript
-// Use browser session with automatic cleanup
 const client = new InstaVM('your_api_key');
 
-async function automateWebsite() {
-    const session = await client.browser.createSession();
-    
-    try {
-        await session.navigate('https://httpbin.org/forms/post');
-        
-        // Fill and submit form
-        await session.fill('input[name="custname"]', 'John Doe');
-        await session.fill('input[name="custtel"]', '555-1234');
-        await session.click('input[type="submit"]');
-        
-        // Wait for result
-        await session.wait({ type: 'visible', selector: 'pre' });
-        
-        // Extract result
-        const result = await session.extractElements('pre', ['text']);
-        return result[0]?.text;
-        
-    } finally {
-        await session.close();
-    }
-}
+const task = await client.executeAsync("sleep 5 && echo 'done'", { language: 'bash' });
+const result = await client.getTaskResult(task.taskId, 2, 60);
 
-const result = await automateWebsite();
-console.log('Form submission result:', result);
+console.log(result.stdout);
 ```
 
-## Mixed Code + Browser Automation
-
-Combine code execution with browser automation for powerful workflows:
+### VMs + Snapshots
 
 ```typescript
 import { InstaVM } from 'instavm';
 
 const client = new InstaVM('your_api_key');
 
-// Execute Python code to prepare data
-const dataPrep = await client.execute(`
-import json
-import pandas as pd
-
-# Prepare search terms
-search_terms = ["AI", "Machine Learning", "JavaScript"]
-data = {"terms": search_terms, "timestamp": "2024-01-01"}
-print(json.dumps(data))
-`);
-
-const searchData = JSON.parse(dataPrep.output.trim());
-
-// Use browser to search and collect results
-const session = await client.browser.createSession();
-const results = [];
-
-for (const term of searchData.terms) {
-    await session.navigate(`https://news.ycombinator.com/search?q=${encodeURIComponent(term)}`);
-    
-    const headlines = await session.extractElements('.titleline > a', ['text', 'href']);
-    results.push({
-        term,
-        headlines: headlines.slice(0, 5) // Top 5 results
-    });
-}
-
-await session.close();
-
-// Process results with Python
-const analysis = await client.execute(`
-import json
-data = ${JSON.stringify(results)}
-
-# Analyze results
-total_headlines = sum(len(item['headlines']) for item in data)
-print(f"Collected {total_headlines} headlines across {len(data)} search terms")
-
-# Find most common words
-all_text = ' '.join([headline['text'] for item in data for headline in item['headlines']])
-words = all_text.lower().split()
-word_counts = {}
-for word in words:
-    if len(word) > 3:  # Filter short words
-        word_counts[word] = word_counts.get(word, 0) + 1
-
-# Top 10 words
-top_words = sorted(word_counts.items(), key=lambda x: x[1], reverse=True)[:10]
-print("Top words:", top_words)
-`);
-
-console.log(analysis.output);
-await client.dispose();
-```
-
-## Language Support
-
-### Python Code Execution
+const vm = await client.vms.create({ metadata: { purpose: 'dev' } }, true);
+const vmId = String(vm.vm_id);
+
+const vmList = await client.vms.list(); // GET /v1/vms
+const vmAllRecords = await client.vms.listAllRecords(); // GET /v1/vms/
+
+await client.vms.snapshot(vmId, { name: 'dev-base' }, true);
+
+await client.snapshots.create({
+  oci_image: 'docker.io/library/python:3.11-slim',
+  name: 'python-3-11-dev',
+  vcpu_count: 2,
+  memory_mb: 1024,
+  type: 'user',
+  build_args: {
+    git_clone_url: 'https://github.com/example/repo.git',
+    git_clone_branch: 'main',
+    envs: { NODE_ENV: 'production' },
+  },
+});
 
-```typescript
-// Python with libraries
-const result = await client.execute(`
-import pandas as pd
-import numpy as np
-
-# Create sample data
-data = pd.DataFrame({
-    'numbers': np.random.randn(100),
-    'categories': np.random.choice(['A', 'B', 'C'], 100)
-})
-
-# Basic statistics
-print(f"Mean: {data['numbers'].mean():.2f}")
-print(f"Std: {data['numbers'].std():.2f}")
-print(f"Categories: {data['categories'].value_counts().to_dict()}")
-`);
-
-console.log(result.output);
+const userSnapshots = await client.snapshots.list({ type: 'user' });
+console.log(vmList.length, vmAllRecords.length, userSnapshots.length);
 ```
 
-### Bash Commands
+### Networking (Egress, Shares, SSH)
 
 ```typescript
-// System operations
-const sysInfo = await client.execute(`
-echo "System Information:"
-echo "==================="
-uname -a
-echo
-echo "Disk Usage:"
-df -h
-echo
-echo "Memory Info:"
-free -h
-`, { language: 'bash' });
-
-console.log(sysInfo.output);
-```
+import { InstaVM } from 'instavm';
 
-### Session Persistence
+const client = new InstaVM('your_api_key');
+const sessionId = await client.createSession();
+
+await client.setSessionEgress(
+  {
+    allowPackageManagers: true,
+    allowHttp: false,
+    allowHttps: true,
+    allowedDomains: ['npmjs.com', 'registry.npmjs.org'],
+  },
+  sessionId
+);
 
-```typescript
-// Variables persist across executions within the same session
-await client.execute('data = [1, 2, 3, 4, 5]');
-await client.execute('total = sum(data)');
+const share = await client.shares.create({ session_id: sessionId, port: 3000, is_public: false });
+await client.shares.update(String(share.share_id), { is_public: true });
 
-const result = await client.execute('print(f"Total: {total}, Average: {total/len(data)}")');
-console.log(result.output); // Output: Total: 15, Average: 3.0
+const key = await client.addSshKey('ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@host');
+console.log(key);
 ```
 
-## Advanced Features
+<a id="infrastructure-platform-apis"></a>
+## Infrastructure & Platform APIs
 
-### Wait Conditions
+### Platform APIs (API Keys, Audit, Webhooks)
 
 ```typescript
-// Wait for element to appear
-await session.wait({ 
-    type: 'visible', 
-    selector: '.loading-complete',
-    timeout: 30000 
-});
-
-// Wait for element to disappear
-await session.wait({ 
-    type: 'hidden', 
-    selector: '.spinner' 
-});
-
-// Wait for page load
-await session.wait({ 
-    type: 'networkidle' 
-});
-
-// Simple timeout
-await session.wait({ 
-    type: 'timeout', 
-    ms: 5000 
-});
-```
+import { InstaVM } from 'instavm';
 
-### Screenshot Options
+const client = new InstaVM('your_api_key');
 
-```typescript
-// Full page screenshot
-const fullPage = await session.screenshot({ 
-    fullPage: true,
-    format: 'png'
-});
+const apiKey = await client.apiKeys.create({ description: 'ci key' });
+const events = await client.audit.events({ status: 'success', limit: 25 });
 
-// Clip specific area
-const clipped = await session.screenshot({
-    clip: {
-        x: 0,
-        y: 0, 
-        width: 800,
-        height: 600
-    },
-    format: 'jpeg',
-    quality: 90
+const endpoint = await client.webhooks.createEndpoint({
+  url: 'https://example.com/instavm/webhook',
+  event_patterns: ['vm.*', 'snapshot.*'],
 });
 
-// Screenshots return base64 encoded strings
-const buffer = Buffer.from(fullPage, 'base64');
-// Save to file if needed
+const deliveries = await client.webhooks.listDeliveries({ limit: 10 });
+console.log(apiKey, events, endpoint, deliveries);
 ```
 
-### Element Extraction
-
-```typescript
-// Extract multiple attributes
-const links = await session.extractElements('a', ['href', 'text', 'title']);
-
-// Extract with CSS selectors
-const articles = await session.extractElements('article h2, .post-title', ['text']);
-
-// Extract form data
-const formData = await session.extractElements('input, select, textarea', [
-    'name', 'value', 'type', 'placeholder'
-]);
+<a id="browser-computer-use"></a>
+## Browser & Computer Use
 
-console.log('Links found:', links);
-console.log('Articles:', articles);
-console.log('Form fields:', formData);
-```
+### Browser Automation
 
-### LLM-Friendly Content Extraction
+Basic browser session flow:
 
 ```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
-});
+import { InstaVM } from 'instavm';
 
-// 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);
+const client = new InstaVM('your_api_key');
 
-// Find interactive elements (buttons, links, inputs)
-const loginButton = content.interactiveElements?.find(
-    el => el.text?.toLowerCase().includes('login')
-);
-if (loginButton) {
-    await session.click(loginButton.selector);
-}
+const browser = await client.browser.createSession({ viewportWidth: 1366, viewportHeight: 768 });
+await browser.navigate('https://example.com');
+await browser.click('a');
+const screenshot = await browser.screenshot({ fullPage: true });
 
-// 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);
-}
+console.log(screenshot.length);
+await browser.close();
 ```
 
-## Error Handling Reference
-
-### Error Types
+Advanced flow with waits and extraction:
 
 ```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)
-    UnsupportedOperationError // Operation not supported in local mode
-} from 'instavm';
-
-// Specific error handling
-try {
-    await session.click('.non-existent-button');
-} catch (error) {
-    if (error instanceof ElementNotFoundError) {
-        console.log(`Element not found: ${error.selector}`);
-    } else if (error instanceof BrowserTimeoutError) {
-        console.log('Operation timed out');
-    }
-}
-```
-
-### Retry Logic
-
-The SDK includes automatic retry logic for:
-- Network errors (connection issues)
-- Rate limiting (with exponential backoff)
-- Server errors (5xx status codes)
+import { InstaVM } from 'instavm';
 
-```typescript
-// Customize retry behavior
-const client = new InstaVM('your_api_key', {
-    maxRetries: 5,
-    retryDelay: 2000,  // Base delay in milliseconds
-    timeout: 300000    // 5 minute timeout
-});
-```
+const client = new InstaVM('your_api_key');
+const browser = await client.browser.createSession();
 
-## API Reference
+await browser.navigate('https://news.ycombinator.com');
+await browser.wait({ type: 'visible', selector: 'a.storylink' }, 10000);
 
-### InstaVM Client
+const links = await browser.extractElements('a.storylink', ['text', 'href']);
+console.log(links.slice(0, 5));
 
-```typescript
-class InstaVM {
-    constructor(apiKey: string, options?: InstaVMOptions)
-    
-    // Code execution
-    execute(command: string, options?: ExecuteOptions): Promise<ExecutionResult>
-    executeAsync(command: string, options?: ExecuteOptions): Promise<AsyncExecutionResult>
-    
-    // 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>
-    getUsage(sessionId?: string): Promise<UsageStats>
-    
-    // Browser automation
-    browser: BrowserManager
-    
-    // Properties
-    readonly sessionId: string | null
-    
-    // Cleanup
-    dispose(): Promise<void>
-}
+await browser.close();
 ```
 
-### Configuration Options
+### LLM-Friendly Content Extraction (concise pattern only)
 
 ```typescript
-interface InstaVMOptions {
-    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
-}
+import { InstaVM } from 'instavm';
 
-interface ExecuteOptions {
-    language?: 'python' | 'bash';  // Default: 'python'
-    timeout?: number;               // Default: 15 seconds
-    sessionId?: string;             // Use specific session
-}
-```
+const client = new InstaVM('your_api_key');
+const browser = await client.browser.createSession();
 
-### Browser Manager
+await browser.navigate('https://example.com/docs');
 
-```typescript
-class BrowserManager {
-    createSession(options?: BrowserSessionOptions): Promise<BrowserSession>
-    listSessions(): Promise<BrowserSessionInfo[]>
-    getSession(sessionId: string): Promise<BrowserSessionInfo>
-    getLocalSession(sessionId: string): BrowserSession | undefined
-    getLocalSessions(): BrowserSession[]
-    closeAllSessions(): Promise<void>
-    dispose(): Promise<void>
-}
+const content = await browser.extractContent({
+  includeInteractive: true,
+  includeAnchors: true,
+  maxAnchors: 30,
+});
 
-interface BrowserSessionOptions {
-    viewportWidth?: number;   // Default: 1920
-    viewportHeight?: number;  // Default: 1080
-    userAgent?: string;       // Custom user agent
+console.log(content.readableContent.title);
+for (const anchor of (content.contentAnchors || []).slice(0, 5)) {
+  console.log(anchor.text, anchor.selector);
 }
-```
 
-### Browser Session
-
-```typescript
-class BrowserSession extends EventEmitter {
-    // Navigation
-    navigate(url: string, options?: NavigateOptions): Promise<NavigationResult>
-    
-    // Interaction
-    click(selector: string, options?: ClickOptions): Promise<void>
-    type(selector: string, text: string, options?: TypeOptions): Promise<void>
-    fill(selector: string, value: string, options?: FillOptions): Promise<void>
-    scroll(options?: ScrollOptions): Promise<void>
-    
-    // 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>
-    
-    // Properties
-    readonly sessionId: string
-    readonly isActive: boolean
-    
-    // Events: 'navigation', 'error', 'close'
-}
+await browser.close();
 ```
 
-### Type Definitions
+### Computer Use
 
 ```typescript
-interface ExecutionResult {
-    output: string;
-    success: boolean;
-    executionTime: number;
-    sessionId?: string;
-    error?: string;
-}
-
-interface NavigationResult {
-    success: boolean;
-    url: string;
-    title?: string;
-    status?: number;
-}
-
-interface ExtractedElement {
-    text?: string;
-    href?: string;
-    [attribute: string]: string | undefined;
-}
-
-type WaitCondition = 
-    | { type: 'timeout'; ms: number }
-    | { type: 'visible'; selector: string }
-    | { type: 'hidden'; selector: string }
-    | { type: 'navigation' }
-    | { type: 'networkidle' };
-```
-
-## Best Practices
-
-### Resource Management
+import { InstaVM } from 'instavm';
 
-```typescript
-// Always dispose of the client when done
 const client = new InstaVM('your_api_key');
-try {
-    // Your automation code
-} finally {
-    await client.dispose(); // Closes all sessions and cleans up
-}
+const sessionId = await client.createSession();
 
-// Or use a wrapper function
-async function withInstaVM(apiKey: string, callback: (client: InstaVM) => Promise<void>) {
-    const client = new InstaVM(apiKey);
-    try {
-        await callback(client);
-    } finally {
-        await client.dispose();
-    }
-}
+const viewer = await client.computerUse.viewerUrl(sessionId);
+const state = await client.computerUse.get(sessionId, '/state');
 
-await withInstaVM('your_api_key', async (client) => {
-    const result = await client.execute('print("Hello, World!")');
-    console.log(result.output);
-});
+console.log(viewer, state);
 ```
 
-### Error Handling Strategy
+<a id="error-handling"></a>
+## Error Handling
 
 ```typescript
-// Implement comprehensive error handling
-async function robustAutomation(client: InstaVM) {
-    let session: BrowserSession | null = null;
-    
-    try {
-        session = await client.browser.createSession();
-        
-        // Retry navigation with timeout
-        let retries = 3;
-        while (retries > 0) {
-            try {
-                await session.navigate('https://example.com');
-                break;
-            } catch (error) {
-                if (error instanceof BrowserTimeoutError && retries > 1) {
-                    console.log(`Navigation timeout, retrying... (${retries - 1} attempts left)`);
-                    retries--;
-                    await new Promise(resolve => setTimeout(resolve, 2000));
-                } else {
-                    throw error;
-                }
-            }
-        }
-        
-        // Safe element interaction
-        try {
-            await session.click('button.submit');
-        } catch (error) {
-            if (error instanceof ElementNotFoundError) {
-                console.log('Submit button not found, trying alternative selector');
-                await session.click('input[type="submit"]');
-            } else {
-                throw error;
-            }
-        }
-        
-    } catch (error) {
-        console.error('Automation failed:', error.message);
-        throw error;
-    } finally {
-        if (session) {
-            await session.close();
-        }
-    }
-}
-```
-
-### Performance Optimization
-
-```typescript
-// Batch operations when possible
-const session = await client.browser.createSession();
-
-// Instead of multiple separate calls
-await session.navigate('https://example.com');
-const title = await session.extractElements('title', ['text']);
-const links = await session.extractElements('a', ['href']);
-const images = await session.extractElements('img', ['src', 'alt']);
-
-// Consider using a single extraction call for related elements
-const pageData = await session.extractElements('title, a, img', ['text', 'href', 'src', 'alt']);
-
-// Use appropriate timeouts
-await session.navigate('https://slow-site.com', { 
-    waitTimeout: 60000  // Increase timeout for slow sites
-});
+import {
+  InstaVM,
+  AuthenticationError,
+  ExecutionError,
+  NetworkError,
+  RateLimitError,
+  SessionError,
+} from 'instavm';
 
-// Optimize screenshot size for performance
-const thumbnail = await session.screenshot({
-    clip: { x: 0, y: 0, width: 400, height: 300 },
-    format: 'jpeg',
-    quality: 70
-});
-```
+const client = new InstaVM('your_api_key');
 
-## CommonJS Usage
-
-For projects using CommonJS:
-
-```javascript
-const { InstaVM, AuthenticationError } = require('instavm');
-
-async function main() {
-    const client = new InstaVM('your_api_key');
-    
-    try {
-        const result = await client.execute('print("Hello from CommonJS!")');
-        console.log(result.output);
-    } catch (error) {
-        if (error instanceof AuthenticationError) {
-            console.error('Authentication failed');
-        }
-    } finally {
-        await client.dispose();
-    }
+try {
+  await client.execute("raise Exception('boom')");
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Invalid API key');
+  } else if (error instanceof RateLimitError) {
+    console.error('Rate limited');
+  } else if (error instanceof SessionError) {
+    console.error('Session issue:', error.message);
+  } else if (error instanceof ExecutionError) {
+    console.error('Execution failed:', error.message);
+  } else if (error instanceof NetworkError) {
+    console.error('Network issue:', error.message);
+  } else {
+    throw error;
+  }
 }
-
-main().catch(console.error);
 ```
 
-## Development and Testing
-
-### Running Tests
+<a id="development-testing"></a>
+## Development & Testing
 
 ```bash
 # Install dependencies
 npm install
 
-# Run unit tests (no API key required)
+# Run unit tests
 npm run test:unit
 
-# Run integration tests (requires API key)
-INSTAVM_API_KEY=your_api_key npm run test:integration
-
-# Run all tests
+# Optional: full test run
 npm test
 
-# Build the package
+# Build package
 npm run build
-
-# Type checking
-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.
-
-## Requirements
-
-- Node.js 16+
-- TypeScript 5+ (for TypeScript projects)
-
-## License
-
-Proprietary. This SDK is provided for use with InstaVM services only. 
-
-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
+<a id="docs-map-further-reading"></a>
+## Docs Map (Further Reading)
 
-### Version 0.2.0
+- [JavaScript SDK Docs](https://instavm.io/docs/sdks/javascript)
+- [VMs API](https://instavm.io/docs/api/vms/)
+- [Snapshots API](https://instavm.io/docs/api/snapshots/)
+- [Shares API](https://instavm.io/docs/api/shares/)
+- [Computer Use API (REST API Reference)](https://instavm.io/docs/api#endpoint-categories)
+- [Webhooks API (REST API Reference)](https://instavm.io/docs/api#endpoint-categories)
 
-- ✅ Enhanced session management
-- ✅ Improved error handling
+<a id="version-changelog"></a>
+## Version / Changelog
 
-### Version 0.1.0
+Current package version: `0.11.0`.
 
-- ✅ Code execution fully functional (Python, Bash)
-- ✅ Browser automation complete (navigation, interaction, extraction)
-- ✅ Comprehensive TypeScript support
-- ✅ Error handling with specific error types
-- ✅ Session management and automatic cleanup
-- ✅ File upload capabilities
-- ✅ Async execution support
-- ✅ Event-driven browser sessions
-- ✅ Modern build system with multiple output formats
+Highlights in this line:
+- Manager-based infrastructure APIs (VMs, snapshots, shares, custom domains, computer use, API keys, audit, webhooks)
+- Snapshot build args support for env vars and Git clone inputs
+- Distinct VM list helpers for `/v1/vms` and `/v1/vms/`
 
-The JavaScript SDK provides complete feature parity with the Python SDK and is ready for production use.
+For detailed release history, see [GitHub Releases](https://github.com/instavm/js/releases).