instavm 0.11.0 → 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 InstaVM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 ![Build Status](https://github.com/instavm/js/actions/workflows/ci.yml/badge.svg)
 
-Official JavaScript/TypeScript client for InstaVM code execution, VM lifecycle, snapshots, networking controls, browser automation, and platform APIs.
+Official JavaScript/TypeScript client for [InstaVM](https://instavm.io) — secure code execution in ephemeral microVMs with browser automation, networking controls, and platform APIs.
 
 ## Installation
 
@@ -10,9 +10,9 @@ Official JavaScript/TypeScript client for InstaVM code execution, VM lifecycle,
 npm install instavm
 ```
 
-## Quick Start
+**Requirements:** Node.js 18+, TypeScript 4.7+ (optional)
 
-### Cloud Quick Start
+## Quick Start
 
 ```typescript
 import { InstaVM } from 'instavm';
@@ -22,52 +22,43 @@ const client = new InstaVM(process.env.INSTAVM_API_KEY || 'your_api_key');
 try {
   const result = await client.execute("print('hello from instavm')");
   console.log(result.stdout);
-
-  const usage = await client.getUsage();
-  console.log(usage);
 } finally {
   await client.dispose();
 }
 ```
 
-### Local Mode Quick Start
-
-```typescript
-import { InstaVM } from 'instavm';
-
-const client = new InstaVM('', {
-  local: true,
-  localURL: 'http://coderunner.local:8222',
-});
-
-const result = await client.execute("print('hello from local mode')");
-console.log(result.stdout);
-
-const content = await client.browser.extractContent({
-  url: 'https://example.com',
-  includeInteractive: true,
-  includeAnchors: true,
-});
-
-console.log(content.readableContent.title);
-```
-
 ## Table of Contents
 
-- [Core Workflows](#core-workflows)
-- [Infrastructure & Platform APIs](#infrastructure-platform-apis)
-- [Browser & Computer Use](#browser-computer-use)
+- [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)
-- [Docs Map (Further Reading)](#docs-map-further-reading)
-- [Version / Changelog](#version-changelog)
+- [Development & Testing](#development--testing)
+- [Further Reading](#further-reading)
+- [Changelog](#changelog)
+
+---
 
-<a id="core-workflows"></a>
-## Core Workflows
+## Code Execution
 
-### Cloud Quick Start
+### Cloud Mode
 
-Cloud mode supports sessions, VM/network controls, platform APIs, and browser sessions.
+Cloud mode gives you sessions, VM/network controls, platform APIs, and browser sessions.
 
 ```typescript
 import { InstaVM } from 'instavm';
@@ -83,34 +74,38 @@ const sessionId = await client.createSession();
 console.log('session:', sessionId);
 ```
 
-### Local Mode Quick Start
+### Local Mode
 
-Local mode is optimized for direct execution and lightweight browser helpers.
+Local mode connects to a self-hosted runner for direct execution and browser helpers.
 
 ```typescript
 import { InstaVM } from 'instavm';
 
-const client = new InstaVM('', { local: true });
+const client = new InstaVM('', {
+  local: true,
+  localURL: 'http://coderunner.local:8222',
+});
 
-await client.execute("print('local execution works')");
-await client.browser.navigate('https://example.com');
+const result = await client.execute("print('hello from local mode')");
+console.log(result.stdout);
 ```
 
 ### File Operations
 
 ```typescript
-import { InstaVM } from 'instavm';
-
 const client = new InstaVM('your_api_key');
 const sessionId = await client.createSession();
 
+// Upload
 await client.upload(
   [{ name: 'script.py', content: "print('uploaded')", path: '/app/script.py' }],
   { sessionId }
 );
 
+// Execute
 await client.execute('python /app/script.py', { language: 'bash', sessionId });
 
+// Download
 const download = await client.download('output.json', { sessionId });
 console.log(download.filename, download.size);
 ```
@@ -118,8 +113,6 @@ console.log(download.filename, download.size);
 ### Async Execution
 
 ```typescript
-import { InstaVM } from 'instavm';
-
 const client = new InstaVM('your_api_key');
 
 const task = await client.executeAsync("sleep 5 && echo 'done'", { language: 'bash' });
@@ -128,21 +121,53 @@ const result = await client.getTaskResult(task.taskId, 2, 60);
 console.log(result.stdout);
 ```
 
-### VMs + Snapshots
+---
+
+## Sessions & Sandboxes
 
 ```typescript
-import { InstaVM } from 'instavm';
+const client = new InstaVM('your_api_key');
+const sessionId = await client.createSession();
+
+// Get the publicly-reachable app URL (optionally for a specific port)
+const appUrl = await client.getSessionAppUrl(sessionId, 8080);
+console.log(appUrl.app_url);
+
+// List sandbox records with optional metadata filter and limit
+const sandboxes = await client.listSandboxes({
+  metadata: { env: 'production' },
+  limit: 50,
+});
+console.log(sandboxes.length);
+```
 
+---
+
+## VMs & Snapshots
+
+```typescript
 const client = new InstaVM('your_api_key');
 
+// Create a basic VM
 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/
+// 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',
@@ -157,17 +182,84 @@ await client.snapshots.create({
 });
 
 const userSnapshots = await client.snapshots.list({ type: 'user' });
-console.log(vmList.length, vmAllRecords.length, userSnapshots.length);
 ```
 
-### Networking (Egress, Shares, SSH)
+---
+
+## Volumes
+
+### Volume CRUD & Files
 
 ```typescript
-import { InstaVM } from 'instavm';
+const client = new InstaVM('your_api_key');
+
+// Create
+const volume = await client.volumes.create({
+  name: 'project-data',
+  quota_bytes: 10 * 1024 * 1024 * 1024,
+});
+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,
+});
+
+// File operations
+await client.volumes.uploadFile(volumeId, {
+  filePath: './README.md',
+  path: 'docs/README.md',
+  overwrite: true,
+});
 
+const files = await client.volumes.listFiles(volumeId, {
+  prefix: 'docs/',
+  recursive: true,
+  limit: 1000,
+});
+
+const file = await client.volumes.downloadFile(volumeId, 'docs/README.md');
+await client.volumes.deleteFile(volumeId, 'docs/README.md');
+
+// Checkpoints
+const checkpoint = await client.volumes.createCheckpoint(volumeId, { name: 'pre-release' });
+await client.volumes.listCheckpoints(volumeId);
+await client.volumes.deleteCheckpoint(volumeId, String(checkpoint.id));
+
+// Cleanup
+await client.volumes.delete(volumeId);
+```
+
+### VM Volume Attachments
+
+```typescript
+const vm = await client.vms.create({}, true);
+const vmId = String(vm.vm_id);
+
+await client.vms.mountVolume(vmId, {
+  volume_id: volumeId,
+  mount_path: '/data',
+  mode: 'rw',
+}, true);
+
+await client.vms.listVolumes(vmId);
+await client.vms.unmountVolume(vmId, volumeId, '/data', true);
+```
+
+---
+
+## Networking
+
+### Egress, Shares, SSH
+
+```typescript
 const client = new InstaVM('your_api_key');
 const sessionId = await client.createSession();
 
+// Egress policy
 await client.setSessionEgress(
   {
     allowPackageManagers: true,
@@ -178,81 +270,36 @@ await client.setSessionEgress(
   sessionId
 );
 
+// 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 });
 
+// SSH key registration
 const key = await client.addSshKey('ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... user@host');
-console.log(key);
 ```
 
-<a id="infrastructure-platform-apis"></a>
-## Infrastructure & Platform APIs
+---
 
-### Platform APIs (API Keys, Audit, Webhooks)
+## Browser Automation
 
-```typescript
-import { InstaVM } from 'instavm';
-
-const client = new InstaVM('your_api_key');
-
-const apiKey = await client.apiKeys.create({ description: 'ci key' });
-const events = await client.audit.events({ status: 'success', limit: 25 });
-
-const endpoint = await client.webhooks.createEndpoint({
-  url: 'https://example.com/instavm/webhook',
-  event_patterns: ['vm.*', 'snapshot.*'],
-});
-
-const deliveries = await client.webhooks.listDeliveries({ limit: 10 });
-console.log(apiKey, events, endpoint, deliveries);
-```
-
-<a id="browser-computer-use"></a>
-## Browser & Computer Use
-
-### Browser Automation
-
-Basic browser session flow:
+### Basic Browser Flow
 
 ```typescript
-import { InstaVM } from 'instavm';
-
 const client = new InstaVM('your_api_key');
 
 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 });
-
-console.log(screenshot.length);
 await browser.close();
 ```
 
-Advanced flow with waits and extraction:
-
-```typescript
-import { InstaVM } from 'instavm';
-
-const client = new InstaVM('your_api_key');
-const browser = await client.browser.createSession();
+### Content Extraction
 
-await browser.navigate('https://news.ycombinator.com');
-await browser.wait({ type: 'visible', selector: 'a.storylink' }, 10000);
-
-const links = await browser.extractElements('a.storylink', ['text', 'href']);
-console.log(links.slice(0, 5));
-
-await browser.close();
-```
-
-### LLM-Friendly Content Extraction (concise pattern only)
+LLM-friendly extraction with optional interactive-element and anchor discovery:
 
 ```typescript
-import { InstaVM } from 'instavm';
-
-const client = new InstaVM('your_api_key');
 const browser = await client.browser.createSession();
-
 await browser.navigate('https://example.com/docs');
 
 const content = await browser.extractContent({
@@ -269,23 +316,57 @@ for (const anchor of (content.contentAnchors || []).slice(0, 5)) {
 await browser.close();
 ```
 
-### Computer Use
+---
 
-```typescript
-import { InstaVM } from 'instavm';
+## Computer Use
 
+Control a full desktop environment inside a VM session:
+
+```typescript
 const client = new InstaVM('your_api_key');
 const sessionId = await client.createSession();
 
+// Viewer URL and state
 const viewer = await client.computerUse.viewerUrl(sessionId);
 const state = await client.computerUse.get(sessionId, '/state');
 
-console.log(viewer, state);
+// Proxy methods (GET, POST, HEAD)
+const headResp = await client.computerUse.head(sessionId, '/state');
+
+// VNC websockify URL for remote desktop streaming
+const vnc = await client.computerUse.vncWebsockify(sessionId);
 ```
 
-<a id="error-handling"></a>
+---
+
+## Platform APIs
+
+API keys, audit logs, and webhooks:
+
+```typescript
+const client = new InstaVM('your_api_key');
+
+// API Keys
+const apiKey = await client.apiKeys.create({ description: 'ci key' });
+
+// Audit log
+const events = await client.audit.events({ status: 'success', limit: 25 });
+
+// Webhooks
+const endpoint = await client.webhooks.createEndpoint({
+  url: 'https://example.com/instavm/webhook',
+  event_patterns: ['vm.*', 'snapshot.*'],
+});
+
+const deliveries = await client.webhooks.listDeliveries({ limit: 10 });
+```
+
+---
+
 ## Error Handling
 
+All SDK errors extend a typed hierarchy for precise `catch` handling:
+
 ```typescript
 import {
   InstaVM,
@@ -317,40 +398,46 @@ try {
 }
 ```
 
-<a id="development-testing"></a>
+---
+
 ## Development & Testing
 
 ```bash
-# Install dependencies
-npm install
-
-# Run unit tests
-npm run test:unit
-
-# Optional: full test run
-npm test
-
-# Build package
-npm run build
+npm install          # Install dependencies
+npm run test:unit    # Unit tests
+npm test             # Full test suite
+npm run build        # Build package
 ```
 
-<a id="docs-map-further-reading"></a>
-## Docs Map (Further Reading)
+---
+
+## Further Reading
 
 - [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)
+- [Computer Use API](https://instavm.io/docs/api#endpoint-categories)
+- [Webhooks API](https://instavm.io/docs/api#endpoint-categories)
+
+---
+
+## Changelog
+
+Current package version: **0.13.0**
+
+### 0.13.0
 
-<a id="version-changelog"></a>
-## Version / Changelog
+- [`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
 
-Current package version: `0.11.0`.
+### 0.12.0
 
-Highlights in this line:
-- Manager-based infrastructure APIs (VMs, snapshots, shares, custom domains, computer use, API keys, audit, webhooks)
+- 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/`