JavaScript SDK

A comprehensive JavaScript/TypeScript client library for InstaVM's code execution and browser automation APIs. The official InstaVM JavaScript SDK provides a modern, promise-based interface with full TypeScript support.

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

Installation

npm install instavm

Quick Start

Code Execution

import { InstaVM, ExecutionError, NetworkError } from 'instavm';

// Create client with automatic session management
const client = new InstaVM('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}`);
    }
} finally {
    await client.dispose();
}

File Upload

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);

Client Configuration

Basic Configuration

import { InstaVM } from 'instavm';

// Default configuration
const client = new InstaVM('your_api_key');

// Custom configuration with options
const client = new InstaVM('your_api_key', {
    baseURL: 'https://api.instavm.io',  // Default: 'https://api.instavm.io'
    timeout: 300000,                    // Default: 300000 (5 minutes)
    maxRetries: 3,                      // Default: 3
    retryDelay: 1000                    // Default: 1000ms
});

Using Environment Variables

import { InstaVM } from 'instavm';

// Set API key via environment variable
process.env.INSTAVM_API_KEY = 'your_api_key';
const client = new InstaVM(process.env.INSTAVM_API_KEY);

Error Handling

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

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'
});

console.log(`Task ${result.taskId} status: ${result.status}`);
console.log(`Output so far: ${result.output}`);

Browser Automation

Basic Browser Usage

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

// 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');

// 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);

Browser Session Management

// 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

// 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 result = await automateWebsite();
console.log('Form submission result:', result);

CommonJS Usage

For projects using CommonJS:

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();
    }
}

main().catch(console.error);

API Reference

InstaVM Client

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>
    
    // 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>
}

Configuration Options

interface InstaVMOptions {
    baseURL?: string;        // Default: 'https://api.instavm.io'
    timeout?: number;        // Default: 300000 (5 minutes)
    maxRetries?: number;     // Default: 3
    retryDelay?: number;     // Default: 1000ms
}

interface ExecuteOptions {
    language?: 'python' | 'bash';  // Default: 'python'
    timeout?: number;               // Default: 15 seconds
    sessionId?: string;             // Use specific session
}

Error Types

The SDK provides comprehensive error handling:

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)
} from 'instavm';

Requirements

• Node.js 16+ (specified in package.json engines)
• TypeScript 5+ (for TypeScript projects)

Best Practices

Resource Management

// 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();
    }
}

await withInstaVM('your_api_key', async (client) => {
    const result = await client.execute('print("Hello, World!")');
    console.log(result.output);
});

Version Information

• Current Version: 0.2.2
• Repository: https://github.com/instavm/js
• npm Package: https://www.npmjs.com/package/instavm

Next Steps

• Python SDK
• Go SDK
• Authentication Guide