oblien 2.0.0 → 2.0.1

package/README.md

@@ -0,0 +1,634 @@
+# Oblien SDK
+
+Cloud workspaces that boot in milliseconds and run anything.
+
+Oblien gives you hardware-isolated microVMs -- each with its own kernel, its own memory, and full root access. Use them to give an AI agent a live environment, deploy a service with a public URL, run untrusted code in a throwaway sandbox, or spin up a dev machine you can SSH into. The workspace is the only primitive. What it becomes is up to you.
+
+This is the official TypeScript SDK. It covers the full Oblien API surface: workspace lifecycle, networking, snapshots, workloads, metrics, SSH, public access, and the in-workspace runtime (files, exec, terminal, search, watchers, WebSocket).
+
+**Documentation:** [https://oblien.com/docs](https://oblien.com/docs)
+
+---
+
+## Platform
+
+Oblien is a workspace platform. Every workspace is a microVM that boots in under a second from any Docker image. Workspaces can be temporary (auto-delete after a TTL) or permanent (run indefinitely). They can be air-gapped or wired to other workspaces over a private internal network. They can expose ports to the internet through Oblien's edge proxy with automatic TLS -- or stay completely invisible.
+
+The architecture is split into two planes:
+
+- **Control plane** (`api.oblien.com`) -- Create, configure, start, stop, snapshot, and destroy workspaces. Manage networking, firewall rules, SSH keys, workloads, images, billing, and metadata.
+- **Data plane** (`workspace.oblien.com`) -- Interact with a running workspace's filesystem, execute commands, open terminal sessions, watch files, and stream events over WebSocket.
+
+The SDK wraps both planes in a single client.
+
+### What people build with it
+
+- **AI agent environments** -- A permanent workspace is the agent's home. It creates short-lived sandboxes on demand for tasks, user code, or deployments.
+- **Service hosting** -- Run an API server, a queue worker, or a database as a permanent workspace. Map it to a custom domain.
+- **Remote development** -- SSH into a workspace, install your stack, expose a port for live preview.
+- **CI/CD** -- Spin up ephemeral workspaces per build, run tests in full isolation, auto-destroy when done.
+- **Code sandboxes** -- Air-gapped throwaway VMs that auto-delete after a TTL. No internet, no persistence.
+- **Per-user environments** -- One workspace per customer with scoped networking, credit quotas, and full isolation.
+
+---
+
+## Install
+
+```bash
+npm install oblien
+```
+
+Requires Node.js 18 or later. Zero runtime dependencies.
+
+---
+
+## Quick start
+
+```typescript
+import Oblien from 'oblien';
+
+const client = new Oblien({
+  clientId: process.env.OBLIEN_CLIENT_ID,
+  clientSecret: process.env.OBLIEN_CLIENT_SECRET,
+});
+
+const ws = client.workspaces;
+
+// Create a workspace
+const workspace = await ws.create({
+  image: 'node-20',
+  mode: 'permanent',
+  config: { cpus: 2, memory_mb: 4096 },
+});
+
+// Start it
+await ws.start(workspace.id);
+
+// Connect to the runtime -- filesystem, exec, terminal
+const rt = await ws.runtime(workspace.id);
+
+// Run a command
+const result = await rt.exec.run(['node', '--version']);
+console.log(result.stdout);
+
+// Read a file
+const file = await rt.files.read({ filePath: '/etc/os-release' });
+console.log(file.content);
+
+// Expose port 3000 to the internet
+await ws.publicAccess.expose(workspace.id, { port: 3000 });
+```
+
+---
+
+## Architecture
+
+### Client and workspaces
+
+```typescript
+import Oblien from 'oblien';
+
+const client = new Oblien({ clientId, clientSecret });
+const ws = client.workspaces;
+```
+
+`client.workspaces` is the entry point for all control-plane operations. It provides CRUD methods, power controls, and 13 sub-resource namespaces:
+
+| Namespace | Description |
+|-----------|-------------|
+| `ws.lifecycle` | Permanent/temporary mode, TTL, ping, destroy |
+| `ws.network` | Firewall rules, private links, outbound IP |
+| `ws.ssh` | Enable SSH, set password or public key |
+| `ws.publicAccess` | Expose and revoke public ports |
+| `ws.resources` | CPU, memory, disk allocation |
+| `ws.snapshots` | Create, restore, archive, and manage snapshots |
+| `ws.workloads` | Managed background processes with log streaming |
+| `ws.metrics` | Live CPU/memory/disk/network stats, VM info and config |
+| `ws.usage` | Credit usage, activity tracking |
+| `ws.metadata` | Key-value metadata store |
+| `ws.apiAccess` | Internal API server -- enable, disable, rotate tokens |
+| `ws.logs` | Boot and command logs |
+| `ws.images` | Available workspace images |
+
+### CRUD
+
+```typescript
+// Create
+const workspace = await ws.create({ image: 'node-20', mode: 'permanent' });
+
+// List
+const { workspaces } = await ws.list({ page: 1, limit: 20 });
+
+// Get
+const data = await ws.get('ws_a1b2c3d4');
+
+// Update
+await ws.update('ws_a1b2c3d4', { name: 'production-api' });
+
+// Delete
+await ws.delete('ws_a1b2c3d4');
+```
+
+### Power controls
+
+```typescript
+await ws.start(id);
+await ws.stop(id);
+await ws.restart(id);
+await ws.pause(id);    // preserves memory state
+await ws.resume(id);
+await ws.ping(id);     // renews TTL for temporary workspaces
+```
+
+### Account-level queries
+
+```typescript
+const quota = await ws.getQuota();
+const estimate = await ws.getEstimate({ cpu: 4, ram_mb: 8192 });
+```
+
+---
+
+## Runtime (data plane)
+
+The runtime connects to a running workspace and provides direct access to its filesystem, command execution, terminal sessions, search, and file watchers.
+
+```typescript
+const rt = await ws.runtime('ws_a1b2c3d4');
+```
+
+This call enables the workspace's internal API server (if not already enabled), fetches a gateway JWT, and returns a `Runtime` instance. The token is cached -- subsequent calls for the same workspace return instantly.
+
+### Files
+
+```typescript
+// List directory
+const entries = await rt.files.list({ dirPath: '/app' });
+
+// Read file
+const { content } = await rt.files.read({ filePath: '/app/index.js' });
+
+// Write file
+await rt.files.write({ fullPath: '/app/config.json', content: '{}' });
+
+// Create directory
+await rt.files.mkdir({ path: '/app/logs' });
+
+// Stat
+const stat = await rt.files.stat({ path: '/app/index.js' });
+
+// Delete
+await rt.files.delete({ path: '/app/tmp' });
+
+// Stream directory tree (async generator)
+for await (const entry of rt.files.stream({ dirPath: '/app' })) {
+  console.log(entry.path);
+}
+```
+
+### Exec
+
+```typescript
+// Run a command and wait for result
+const result = await rt.exec.run(['npm', 'test']);
+console.log(result.exitCode, result.stdout, result.stderr);
+
+// Stream output as it happens (async generator)
+for await (const event of rt.exec.stream(['npm', 'run', 'build'])) {
+  process.stdout.write(event.data);
+}
+
+// List running tasks
+const tasks = await rt.exec.list();
+
+// Kill a task
+await rt.exec.kill(taskId);
+
+// Send stdin to a running task
+await rt.exec.input(taskId, 'yes\n');
+
+// Subscribe to a running task's output
+for await (const event of rt.exec.subscribe(taskId)) {
+  console.log(event);
+}
+```
+
+### Terminal
+
+```typescript
+// Create a terminal session
+const session = await rt.terminal.create({ shell: '/bin/bash' });
+
+// List sessions
+const sessions = await rt.terminal.list();
+
+// Get scrollback buffer
+const { data } = await rt.terminal.scrollback(session.id, { bytes: 4096 });
+
+// Close session
+await rt.terminal.close(session.id);
+```
+
+### Search
+
+```typescript
+// Search file contents (ripgrep)
+const hits = await rt.search.content({ query: 'TODO', path: '/app' });
+
+// Search file names
+const files = await rt.search.files({ query: 'config', path: '/app' });
+
+// Index status and initialization
+const status = await rt.search.status();
+await rt.search.init();
+```
+
+### Watcher
+
+```typescript
+// Watch a directory for changes
+const watcher = await rt.watcher.create({ path: '/app/src' });
+
+// List active watchers
+const watchers = await rt.watcher.list();
+
+// Get watcher info
+const info = await rt.watcher.get(watcher.id);
+
+// Stop watching
+await rt.watcher.delete(watcher.id);
+```
+
+---
+
+## WebSocket
+
+For real-time terminal I/O and file watcher events, open a persistent WebSocket connection:
+
+```typescript
+const socket = rt.ws();
+
+socket.onOpen(() => {
+  console.log('connected');
+});
+
+socket.onTerminalOutput((data) => {
+  process.stdout.write(data.output);
+});
+
+socket.onWatcherEvent((event) => {
+  console.log(event.type, event.path);
+});
+
+socket.onClose(() => {
+  console.log('disconnected');
+});
+
+socket.onError((err) => {
+  console.error(err);
+});
+
+await socket.connect();
+
+// Send input to a terminal
+socket.writeTerminalInput(sessionId, 'ls -la\n');
+
+// Resize terminal
+socket.resizeTerminal(sessionId, { cols: 120, rows: 40 });
+```
+
+---
+
+## SSE streaming
+
+Several endpoints return server-sent events as async generators. Consume them with `for await`:
+
+```typescript
+// Stream workspace logs
+for await (const line of ws.logs.streamBoot(id)) {
+  console.log(line);
+}
+
+// Stream workload output
+for await (const event of ws.workloads.logsStream(id, workloadId)) {
+  process.stdout.write(event.data);
+}
+
+// Stream live metrics
+for await (const snapshot of ws.metrics.statsStream(id)) {
+  console.log(snapshot.cpu_percent, snapshot.memory_used_mb);
+}
+
+// Stream workload stats
+for await (const stats of ws.workloads.statsStream(id, workloadId)) {
+  console.log(stats);
+}
+```
+
+---
+
+## Sub-resources
+
+### Lifecycle
+
+```typescript
+const status = await ws.lifecycle.get(id);
+
+// Convert to permanent
+await ws.lifecycle.makePermanent(id);
+
+// Convert to temporary with TTL
+await ws.lifecycle.makeTemporary(id, { ttl_seconds: 3600 });
+
+// Update TTL
+await ws.lifecycle.updateTtl(id, { ttl_seconds: 7200 });
+
+// Destroy (irreversible)
+await ws.lifecycle.destroy(id);
+```
+
+### Network
+
+```typescript
+const network = await ws.network.get(id);
+
+await ws.network.update(id, {
+  ingress: ['10.0.1.5'],
+  egress: ['10.0.1.10'],
+  allow_internet: false,
+});
+
+// Assign a dedicated outbound IP
+await ws.network.applyOutboundIp(id, { ip: '203.0.113.50' });
+```
+
+### SSH
+
+```typescript
+await ws.ssh.enable(id, { password: 'secure-password' });
+await ws.ssh.enable(id, { publicKey: 'ssh-ed25519 AAAA...' });
+await ws.ssh.disable(id);
+const sshStatus = await ws.ssh.status(id);
+```
+
+### Public access
+
+```typescript
+// Expose a port
+const endpoint = await ws.publicAccess.expose(id, {
+  port: 3000,
+  domain: 'app.yourdomain.com',
+});
+
+// List exposed ports
+const ports = await ws.publicAccess.list(id);
+
+// Revoke
+await ws.publicAccess.revoke(id, { port: 3000 });
+```
+
+### Snapshots
+
+```typescript
+// Create a snapshot
+await ws.snapshots.create(id, { label: 'before-deploy' });
+
+// Restore
+await ws.snapshots.restore(id);
+
+// Archives
+await ws.snapshots.createArchive(id, { label: 'v1.0' });
+const archives = await ws.snapshots.listArchives(id);
+const archive = await ws.snapshots.getArchive(id, 'v1');
+await ws.snapshots.deleteArchive(id, 'v1');
+await ws.snapshots.deleteAllArchives(id);
+```
+
+### Workloads
+
+```typescript
+// Create a managed workload
+await ws.workloads.create(id, {
+  name: 'server',
+  cmd: ['node', 'server.js'],
+  env: { PORT: '3000' },
+});
+
+const workloads = await ws.workloads.list(id);
+const workload = await ws.workloads.get(id, workloadId);
+await ws.workloads.start(id, workloadId);
+await ws.workloads.stop(id, workloadId);
+await ws.workloads.delete(id, workloadId);
+
+// Logs and stats (async generators)
+for await (const line of ws.workloads.logsStream(id, workloadId)) {
+  console.log(line);
+}
+for await (const snapshot of ws.workloads.statsStream(id, workloadId)) {
+  console.log(snapshot);
+}
+```
+
+### Metrics
+
+```typescript
+const stats = await ws.metrics.stats(id);
+const info = await ws.metrics.info(id);
+const config = await ws.metrics.config(id);
+
+for await (const snapshot of ws.metrics.statsStream(id)) {
+  console.log(snapshot);
+}
+```
+
+### Usage
+
+```typescript
+const usage = await ws.usage.get(id);
+const totals = await ws.usage.totals(id);
+const chart = await ws.usage.creditsChart(id);
+const global = await ws.usage.global();
+const activity = await ws.usage.activity();
+await ws.usage.wipe(id);
+```
+
+### Metadata
+
+```typescript
+const meta = await ws.metadata.get(id);
+await ws.metadata.update(id, { key: 'env', value: 'production' });
+await ws.metadata.patch(id, { key: 'version', value: '2.1.0' });
+```
+
+### API access
+
+```typescript
+const status = await ws.apiAccess.status(id);
+const access = await ws.apiAccess.enable(id);
+await ws.apiAccess.disable(id);
+await ws.apiAccess.rotateToken(id);
+const token = await ws.apiAccess.getToken(id);
+const raw = await ws.apiAccess.rawToken(id);
+```
+
+### Logs
+
+```typescript
+const log = await ws.logs.get(id);
+await ws.logs.clear(id);
+const files = await ws.logs.listFiles(id);
+const file = await ws.logs.getFile(id, 'boot.log');
+
+for await (const line of ws.logs.streamBoot(id)) {
+  console.log(line);
+}
+for await (const line of ws.logs.streamCmd(id)) {
+  console.log(line);
+}
+```
+
+### Images
+
+```typescript
+const images = await ws.images.list();
+const image = await ws.images.get('node-20');
+```
+
+---
+
+## Standalone imports
+
+The SDK exports `Workspace` and `Runtime` as standalone classes for cases where you need direct access without going through the main client:
+
+```typescript
+// Workspace (control plane) -- standalone
+import { Workspace } from 'oblien/workspace';
+
+const ws = new Workspace(client);
+await ws.create({ image: 'python-3.12' });
+
+// Runtime (data plane) -- standalone with a raw token
+import { Runtime } from 'oblien/runtime';
+
+const rt = new Runtime({
+  token: 'your_gateway_jwt',
+});
+await rt.files.list({ dirPath: '/' });
+
+// Runtime with a direct IP (bypass edge proxy)
+const directRt = new Runtime({
+  token: 'raw_token',
+  baseUrl: 'http://10.0.1.5:9990',
+});
+```
+
+---
+
+## Error handling
+
+Every API error is an instance of `OblienError` with typed subclasses:
+
+```typescript
+import Oblien, {
+  OblienError,
+  AuthenticationError,
+  NotFoundError,
+  RateLimitError,
+  ValidationError,
+  PaymentRequiredError,
+  ConflictError,
+} from 'oblien';
+
+try {
+  await ws.get('ws_nonexistent');
+} catch (err) {
+  if (err instanceof NotFoundError) {
+    console.log('Workspace does not exist');
+  } else if (err instanceof AuthenticationError) {
+    console.log('Bad credentials');
+  } else if (err instanceof RateLimitError) {
+    console.log('Slow down -- retry after backoff');
+  } else if (err instanceof PaymentRequiredError) {
+    console.log('Quota exceeded -- upgrade your plan');
+  } else if (err instanceof ValidationError) {
+    console.log('Invalid parameters:', err.message);
+  } else if (err instanceof ConflictError) {
+    console.log('Workspace is in the wrong state for this operation');
+  } else if (err instanceof OblienError) {
+    console.log(`API error ${err.status}: ${err.message}`);
+  }
+}
+```
+
+| Error class | HTTP status | When |
+|-------------|-------------|------|
+| `AuthenticationError` | 401 | Invalid or missing credentials |
+| `PaymentRequiredError` | 402 | Credit quota exceeded |
+| `NotFoundError` | 404 | Resource does not exist |
+| `ConflictError` | 409 | Resource in wrong state for the operation |
+| `ValidationError` | 422 | Invalid request parameters |
+| `RateLimitError` | 429 | Too many requests |
+
+---
+
+## Configuration
+
+```typescript
+const client = new Oblien({
+  clientId: 'your_client_id',       // required
+  clientSecret: 'your_client_secret', // required
+  baseUrl: 'https://api.oblien.com',  // optional, default
+});
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `clientId` | `string` | -- | Your API client ID |
+| `clientSecret` | `string` | -- | Your API client secret |
+| `baseUrl` | `string` | `https://api.oblien.com` | Control plane API base URL |
+
+Get your API keys from the [dashboard](https://oblien.com/dashboard).
+
+---
+
+## TypeScript
+
+The SDK is written in TypeScript and ships its own type declarations. All request parameters, response shapes, and event types are fully typed and exported from the top-level package:
+
+```typescript
+import type {
+  WorkspaceCreateParams,
+  WorkspaceData,
+  ExecTask,
+  ExecStreamEvent,
+  FileEntry,
+  WSTerminalEvent,
+  WSWatcherEvent,
+} from 'oblien';
+```
+
+---
+
+## Requirements
+
+- Node.js 18+
+- TypeScript 5.0+ (if using TypeScript)
+- ESM (`"type": "module"` in your package.json, or use dynamic `import()`)
+
+---
+
+## Links
+
+- [Documentation](https://oblien.com/docs)
+- [SDK setup guide](https://oblien.com/docs/workspace/sdk-setup)
+- [Quickstart](https://oblien.com/docs/workspace/quickstart)
+- [API reference](https://oblien.com/docs/api)
+- [Runtime / Internal API](https://oblien.com/docs/internal-api)
+- [Dashboard](https://oblien.com/dashboard)
+- [GitHub](https://github.com/oblien/sdk)
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oblien",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Official TypeScript SDK for the Oblien Workspace API",
   "type": "module",
   "main": "./dist/index.js",