instavm 0.8.3 → 0.13.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](https://instavm.io) — secure code execution in ephemeral microVMs with browser automation, networking controls, and platform APIs.
 
 ## Installation
 
@@ -19,951 +10,435 @@ A comprehensive JavaScript/TypeScript client library for InstaVM's code executio
 npm install instavm
 ```
 
-## Quick Start
+**Requirements:** Node.js 18+, TypeScript 4.7+ (optional)
 
-### Code Execution (Cloud Mode)
+## 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);
-
-    // 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 result = await client.execute("print('hello from instavm')");
+  console.log(result.stdout);
 } 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:
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Code Execution](#code-execution)
+  - [Cloud Mode](#cloud-mode)
+  - [Local Mode](#local-mode)
+  - [File Operations](#file-operations)
+  - [Async Execution](#async-execution)
+- [Sessions & Sandboxes](#sessions--sandboxes)
+- [VMs & Snapshots](#vms--snapshots)
+- [Volumes](#volumes)
+  - [Volume CRUD & Files](#volume-crud--files)
+  - [VM Volume Attachments](#vm-volume-attachments)
+- [Networking](#networking)
+  - [Egress, Shares, SSH](#egress-shares-ssh)
+- [Browser Automation](#browser-automation)
+  - [Basic Browser Flow](#basic-browser-flow)
+  - [Content Extraction](#content-extraction)
+- [Computer Use](#computer-use)
+- [Platform APIs](#platform-apis)
+- [Error Handling](#error-handling)
+- [Development & Testing](#development--testing)
+- [Further Reading](#further-reading)
+- [Changelog](#changelog)
 
-```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.stdout);
-
-// 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()`)
+## Code Execution
 
-Local mode does NOT support (cloud-only features):
-- ❌ Session management (`createSession()`, `closeSession()`, `getUsage()`)
-- ❌ File upload/download
-- ❌ Async execution
-- ❌ Browser session creation and complex interactions
+### Cloud Mode
 
-### File Upload
+Cloud mode gives you sessions, VM/network controls, platform APIs, and browser sessions.
 
 ```typescript
 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 = [
-    {
-        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'
+const client = new InstaVM('your_api_key', {
+  cpu_count: 2,
+  memory_mb: 1024,
+  env: { APP_ENV: 'dev' },
+  metadata: { team: 'platform' },
 });
-console.log(execution.stdout);
-```
-
-### 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
-import { 
-    InstaVM, 
-    AuthenticationError, 
-    RateLimitError, 
-    SessionError,
-    QuotaExceededError 
-} from 'instavm';
-
-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}`);
-    }
-}
-```
-
-### Async Execution
-
-```typescript
-import { InstaVM } from 'instavm';
-
-const client = new InstaVM('your_api_key');
 
-// Execute command asynchronously (returns task ID)
-const result = await client.executeAsync("sleep 5 && echo 'Long task complete!'", {
-    language: 'bash'
-});
-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}`);
+const sessionId = await client.createSession();
+console.log('session:', sessionId);
 ```
 
-## Browser Automation
+### Local Mode
 
-### Basic Browser Usage
+Local mode connects to a self-hosted runner for direct execution and 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);
-
-// Clean up
-await session.close();
-```
-
-### Advanced Browser Interactions
-
-```typescript
-// Navigate with options
-await session.navigate('https://github.com/login', {
-    waitTimeout: 30000,
-    waitUntil: 'networkidle'
+const client = new InstaVM('', {
+  local: true,
+  localURL: 'http://coderunner.local:8222',
 });
 
-// Fill login form
-await session.fill('input[name="login"]', 'username');
-await session.fill('input[name="password"]', 'password');
-
-// Click submit button
-await session.click('input[type="submit"]');
-
-// Wait for navigation
-await session.wait({ type: 'navigation' });
-
-// Scroll to load more content
-await session.scroll({ y: 1000 });
-
-// Extract dynamic content
-const repos = await session.extractElements('.repo-list-item', ['text']);
-console.log('Repositories found:', repos.length);
+const result = await client.execute("print('hello from local mode')");
+console.log(result.stdout);
 ```
 
-### Browser Session Management
+### File Operations
 
 ```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}`);
-});
+const client = new InstaVM('your_api_key');
+const sessionId = await client.createSession();
 
-session.on('error', (error) => {
-    console.error('Session error:', error.message);
-});
+// Upload
+await client.upload(
+  [{ name: 'script.py', content: "print('uploaded')", path: '/app/script.py' }],
+  { sessionId }
+);
 
-session.on('close', () => {
-    console.log('Session closed');
-});
+// Execute
+await client.execute('python /app/script.py', { language: 'bash', sessionId });
 
-// Check if session is still active
-if (session.isActive) {
-    await session.navigate('https://example.com');
-}
+// Download
+const download = await client.download('output.json', { sessionId });
+console.log(download.filename, download.size);
 ```
 
-### Context Manager Pattern
+### Async Execution
 
 ```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:
+## Sessions & Sandboxes
 
 ```typescript
-import { InstaVM } from 'instavm';
-
 const client = new InstaVM('your_api_key');
+const sessionId = await client.createSession();
 
-// 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.stdout.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
-    });
-}
+// Get the publicly-reachable app URL (optionally for a specific port)
+const appUrl = await client.getSessionAppUrl(sessionId, 8080);
+console.log(appUrl.app_url);
 
-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.stdout);
-await client.dispose();
+// List sandbox records with optional metadata filter and limit
+const sandboxes = await client.listSandboxes({
+  metadata: { env: 'production' },
+  limit: 50,
+});
+console.log(sandboxes.length);
 ```
 
-## Language Support
+---
 
-### Python Code Execution
+## VMs & Snapshots
 
 ```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.stdout);
-```
+const client = new InstaVM('your_api_key');
 
-### Bash Commands
+// Create a basic VM
+const vm = await client.vms.create({ metadata: { purpose: 'dev' } }, true);
+const vmId = String(vm.vm_id);
+
+// Create a VM with pre-attached volumes
+const vmWithVols = await client.vms.create({
+  metadata: { purpose: 'data-processing' },
+  volumes: [
+    { volume_id: 'vol_abc', mount_path: '/data', mode: 'rw' },
+  ],
+}, true);
+
+// List VMs
+const vmList = await client.vms.list();              // GET /v1/vms  (running)
+const vmAllRecords = await client.vms.listAllRecords(); // GET /v1/vms/ (all records)
+
+// Snapshot a running VM
+await client.vms.snapshot(vmId, { name: 'dev-base' }, true);
+
+// Build a snapshot from an OCI image
+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
-// 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.stdout);
+const userSnapshots = await client.snapshots.list({ type: 'user' });
 ```
 
-### Session Persistence
-
-```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 result = await client.execute('print(f"Total: {total}, Average: {total/len(data)}")');
-console.log(result.stdout); // Output: Total: 15, Average: 3.0
-```
+## Volumes
 
-### Session Status Check
+### Volume CRUD & Files
 
 ```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
-
-### Wait Conditions
+const client = new InstaVM('your_api_key');
 
-```typescript
-// Wait for element to appear
-await session.wait({ 
-    type: 'visible', 
-    selector: '.loading-complete',
-    timeout: 30000 
+// Create
+const volume = await client.volumes.create({
+  name: 'project-data',
+  quota_bytes: 10 * 1024 * 1024 * 1024,
 });
-
-// Wait for element to disappear
-await session.wait({ 
-    type: 'hidden', 
-    selector: '.spinner' 
+const volumeId = String(volume.id);
+
+// Read / Update
+await client.volumes.list(true);   // refresh_usage=true
+await client.volumes.get(volumeId, true);
+await client.volumes.update(volumeId, {
+  name: 'project-data-v2',
+  quota_bytes: 20 * 1024 * 1024 * 1024,
 });
 
-// Wait for page load
-await session.wait({ 
-    type: 'networkidle' 
+// File operations
+await client.volumes.uploadFile(volumeId, {
+  filePath: './README.md',
+  path: 'docs/README.md',
+  overwrite: true,
 });
 
-// Simple timeout
-await session.wait({ 
-    type: 'timeout', 
-    ms: 5000 
+const files = await client.volumes.listFiles(volumeId, {
+  prefix: 'docs/',
+  recursive: true,
+  limit: 1000,
 });
-```
-
-### Screenshot Options
 
-```typescript
-// Full page screenshot
-const fullPage = await session.screenshot({ 
-    fullPage: true,
-    format: 'png'
-});
+const file = await client.volumes.downloadFile(volumeId, 'docs/README.md');
+await client.volumes.deleteFile(volumeId, 'docs/README.md');
 
-// Clip specific area
-const clipped = await session.screenshot({
-    clip: {
-        x: 0,
-        y: 0, 
-        width: 800,
-        height: 600
-    },
-    format: 'jpeg',
-    quality: 90
-});
+// Checkpoints
+const checkpoint = await client.volumes.createCheckpoint(volumeId, { name: 'pre-release' });
+await client.volumes.listCheckpoints(volumeId);
+await client.volumes.deleteCheckpoint(volumeId, String(checkpoint.id));
 
-// Screenshots return base64 encoded strings
-const buffer = Buffer.from(fullPage, 'base64');
-// Save to file if needed
+// Cleanup
+await client.volumes.delete(volumeId);
 ```
 
-### Element Extraction
+### VM Volume Attachments
 
 ```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']);
+const vm = await client.vms.create({}, true);
+const vmId = String(vm.vm_id);
 
-// Extract form data
-const formData = await session.extractElements('input, select, textarea', [
-    'name', 'value', 'type', 'placeholder'
-]);
+await client.vms.mountVolume(vmId, {
+  volume_id: volumeId,
+  mount_path: '/data',
+  mode: 'rw',
+}, true);
 
-console.log('Links found:', links);
-console.log('Articles:', articles);
-console.log('Form fields:', formData);
+await client.vms.listVolumes(vmId);
+await client.vms.unmountVolume(vmId, volumeId, '/data', true);
 ```
 
-### 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);
+## Networking
 
-// Find interactive elements (buttons, links, inputs)
-const loginButton = content.interactiveElements?.find(
-    el => el.text?.toLowerCase().includes('login')
-);
-if (loginButton) {
-    await session.click(loginButton.selector);
-}
+### Egress, Shares, SSH
 
-// 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')
+```typescript
+const client = new InstaVM('your_api_key');
+const sessionId = await client.createSession();
+
+// Egress policy
+await client.setSessionEgress(
+  {
+    allowPackageManagers: true,
+    allowHttp: false,
+    allowHttps: true,
+    allowedDomains: ['npmjs.com', 'registry.npmjs.org'],
+  },
+  sessionId
 );
-if (signupLink) {
-    await session.click(signupLink.selector);
-}
-```
 
-## Error Handling Reference
+// Public/private share links
+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 });
 
-### 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)
-    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');
-    }
-}
+// SSH key registration
+const key = await client.addSshKey('ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@host');
 ```
 
-### Retry Logic
-
-The SDK includes automatic retry logic for:
-- Network errors (connection issues)
-- Rate limiting (with exponential backoff)
-- Server errors (5xx status codes)
-
-```typescript
-// Customize retry behavior
-const client = new InstaVM('your_api_key', {
-    maxRetries: 5,
-    retryDelay: 2000,  // Base delay in milliseconds
-    timeout: 300000    // 5 minute timeout
-});
-```
+---
 
-## API Reference
+## Browser Automation
 
-### InstaVM Client
+### Basic Browser Flow
 
 ```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>
-
-    // 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
+const client = new InstaVM('your_api_key');
 
-    // Cleanup
-    dispose(): Promise<void>
-}
+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 });
+await browser.close();
 ```
 
-### Configuration Options
+### Content Extraction
 
-```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
-}
+LLM-friendly extraction with optional interactive-element and anchor discovery:
 
-interface ExecuteOptions {
-    language?: 'python' | 'bash';  // Default: 'python'
-    timeout?: number;               // Default: 15 seconds
-    sessionId?: string;             // Use specific session
-}
-```
+```typescript
+const browser = await client.browser.createSession();
+await browser.navigate('https://example.com/docs');
 
-### Browser Manager
+const content = await browser.extractContent({
+  includeInteractive: true,
+  includeAnchors: true,
+  maxAnchors: 30,
+});
 
-```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>
+console.log(content.readableContent.title);
+for (const anchor of (content.contentAnchors || []).slice(0, 5)) {
+  console.log(anchor.text, anchor.selector);
 }
 
-interface BrowserSessionOptions {
-    viewportWidth?: number;   // Default: 1920
-    viewportHeight?: number;  // Default: 1080
-    userAgent?: string;       // Custom user agent
-}
+await browser.close();
 ```
 
-### 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'
-}
-```
+## Computer Use
 
-### Type Definitions
+Control a full desktop environment inside a VM session:
 
 ```typescript
-interface ExecutionResult {
-    stdout: string;
-    stderr: string;
-    success: boolean;
-    executionTime?: number;
-    cpuTime?: number;
-    createdAt?: string;
-    sessionId?: string;
-    error?: string;
-}
+const client = new InstaVM('your_api_key');
+const sessionId = await client.createSession();
 
-interface TaskResult {
-    stdout: string;
-    stderr: string;
-    executionTime?: number;
-    cpuTime?: number;
-    createdAt?: string;
-}
+// Viewer URL and state
+const viewer = await client.computerUse.viewerUrl(sessionId);
+const state = await client.computerUse.get(sessionId, '/state');
 
-interface NavigationResult {
-    success: boolean;
-    url: string;
-    title?: string;
-    status?: number;
-}
+// Proxy methods (GET, POST, HEAD)
+const headResp = await client.computerUse.head(sessionId, '/state');
 
-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' };
+// VNC websockify URL for remote desktop streaming
+const vnc = await client.computerUse.vncWebsockify(sessionId);
 ```
 
-## Best Practices
+---
+
+## Platform APIs
 
-### Resource Management
+API keys, audit logs, and webhooks:
 
 ```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
-}
 
-// 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();
-    }
-}
+// API Keys
+const apiKey = await client.apiKeys.create({ description: 'ci key' });
 
-await withInstaVM('your_api_key', async (client) => {
-    const result = await client.execute('print("Hello, World!")');
-    console.log(result.stdout);
-});
-```
+// Audit log
+const events = await client.audit.events({ status: 'success', limit: 25 });
 
-### Error Handling Strategy
+// Webhooks
+const endpoint = await client.webhooks.createEndpoint({
+  url: 'https://example.com/instavm/webhook',
+  event_patterns: ['vm.*', 'snapshot.*'],
+});
 
-```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();
-        }
-    }
-}
+const deliveries = await client.webhooks.listDeliveries({ limit: 10 });
 ```
 
-### 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']);
+## Error Handling
 
-// Consider using a single extraction call for related elements
-const pageData = await session.extractElements('title, a, img', ['text', 'href', 'src', 'alt']);
+All SDK errors extend a typed hierarchy for precise `catch` handling:
 
-// Use appropriate timeouts
-await session.navigate('https://slow-site.com', { 
-    waitTimeout: 60000  // Increase timeout for slow sites
-});
+```typescript
+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.stdout);
-    } 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
+## Development & Testing
 
 ```bash
-# Install dependencies
-npm install
-
-# Run unit tests (no API key required)
-npm run test:unit
-
-# Run integration tests (requires API key)
-INSTAVM_API_KEY=your_api_key npm run test:integration
-
-# Run all tests
-npm test
-
-# Build the package
-npm run build
-
-# Type checking
-npm run type-check
+npm install          # Install dependencies
+npm run test:unit    # Unit tests
+npm test             # Full test suite
+npm run build        # Build package
 ```
 
-**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. 
+## Further Reading
 
-All rights reserved. No redistribution or modification permitted.
+- [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](https://instavm.io/docs/api#endpoint-categories)
+- [Webhooks API](https://instavm.io/docs/api#endpoint-categories)
 
 ---
 
 ## 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
-- ✅ **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
+Current package version: **0.13.0**
 
-### Version 0.2.0
+### 0.13.0
 
-- ✅ Enhanced session management
-- ✅ Improved error handling
+- [`getSessionAppUrl(sessionId?, port?)`](#sessions--sandboxes) — session app URL with optional port
+- [`listSandboxes({ metadata?, limit? })`](#sessions--sandboxes) — list sandbox records with metadata filtering
+- [`computerUse.head(sessionId, path)`](#computer-use) — HEAD proxy method for computer-use sessions
+- [`computerUse.vncWebsockify(sessionId)`](#computer-use) — VNC websockify URL for remote desktop streaming
+- VM creation now accepts [`volumes`](#vms--snapshots) for pre-attached volume mounts
+- `APIKey` type includes `key_prefix` and `full_key` fields
 
-### Version 0.1.0
+### 0.12.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
+- Manager-based infrastructure APIs (VMs, volumes, 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).