oblien 2.2.36 → 2.2.38

package/docs/edge-tunnel.md

@@ -0,0 +1,42 @@
+# Edge Tunnel
+
+Expose a **local** port to the internet through the Oblien edge — like a built-in ngrok. The tunnel client forwards incoming edge traffic to `localhost:<port>`.
+
+```typescript
+const et = client.edgeTunnel;
+```
+
+## One-liner: create + connect
+
+```typescript
+const tunnel = await et.connect({ name: 'dev-server', port: 3000 });
+console.log(tunnel.url);                 // https://dev-xyz.preview.oblien.com
+
+tunnel.on('request', (id, port) => console.log(`→ localhost:${port}`));
+tunnel.on('close', () => console.log('disconnected'));
+
+// Later…
+tunnel.close();
+```
+
+## Low-level
+
+```typescript
+const { tunnel } = await et.create({ name: 'api', port: 8080 });
+const { token, connect_url } = await et.issueToken(tunnel.id);
+// → drive a TunnelClient yourself with { connectUrl: connect_url, token }
+```
+
+## Manage
+
+```typescript
+const { tunnels } = await et.list();
+await et.checkDomain({ host: 'tunnel.example.com' });  // pre-flight custom domain (TXT/CNAME)
+await et.update(tunnel.id, { name: 'api-v2' });
+await et.enable(tunnel.id);
+await et.disable(tunnel.id);
+await et.renewSSL(tunnel.id);
+await et.delete(tunnel.id);
+```
+
+**Full reference:** [Edge Tunnel API](https://oblien.com/docs/api/edge-tunnel)

package/docs/errors.md

@@ -0,0 +1,34 @@
+# Error handling
+
+Every API error is an instance of `OblienError` with typed subclasses. The SDK preserves the machine-readable `code`, human-readable `message`, optional `details`, and optional `requestId` from the API response.
+
+```typescript
+import {
+  OblienError,
+  NotFoundError,
+  RateLimitError,
+  PaymentRequiredError,
+} from 'oblien';
+
+try {
+  await client.workspaces.get('ws_nonexistent');
+} catch (err) {
+  if (err instanceof NotFoundError)        { /* 404 */ }
+  if (err instanceof RateLimitError)       { /* 429 — back off */ }
+  if (err instanceof PaymentRequiredError) { /* 402 — quota exceeded */ }
+  if (err instanceof OblienError) {
+    console.error(err.code, err.message, err.details, err.requestId);
+  }
+}
+```
+
+| Error class | HTTP | When |
+|---|---|---|
+| `AuthenticationError` | 401 | Invalid or missing credentials |
+| `PaymentRequiredError` | 402 | Credit quota exceeded |
+| `NotFoundError` | 404 | Resource does not exist |
+| `ConflictError` | 409 | Resource in wrong state |
+| `ValidationError` | 422 | Invalid parameters |
+| `RateLimitError` | 429 | Too many requests |
+
+All subclasses extend `OblienError`, so a single `instanceof OblienError` catch handles everything while still exposing `.code`/`.message`/`.details`/`.requestId`.

package/docs/namespaces.md

@@ -0,0 +1,69 @@
+# Namespaces
+
+Group workspaces into isolated namespaces with **resource limits**, **spending quotas**, lifecycle controls, and **per-namespace usage** — the building block for multi-tenant setups (one namespace per customer/team).
+
+```typescript
+const ns = client.namespaces;
+```
+
+## Create + resource limits
+
+```typescript
+const { data } = await ns.create({
+  name: 'production',
+  resource_limits: {
+    max_workspaces: 50,
+    max_vcpus: 16,      // per-workspace cap
+    max_ram_mb: 32768,
+    max_disk_gb: 100,
+  },
+});
+```
+
+Resource limits are enforced **atomically at workspace create and resource upgrade** — over-limit returns `409 NAMESPACE_LIMIT_REACHED`. `max_workspaces` is race-proof (the namespace row is locked + the count re-checked inside the insert transaction). Update them with `ns.update(id, { resource_limits })`.
+
+## Lifecycle
+
+```typescript
+await ns.suspend(id);   // freeze — blocks new creates/starts in the namespace
+await ns.activate(id);
+await ns.stopWorkspaces(id);
+const { namespaces } = await ns.list();
+```
+
+## Quotas (optional)
+
+Spending limits per service, with overdraft + threshold webhooks. Skip these if you bill externally (use **usage units** below instead).
+
+```typescript
+await ns.setQuota({
+  namespace: 'production', service: 'sandbox',
+  quotaLimit: 500, overdraft: 50,
+  onOverdraftAction: 'stop_workspaces',
+  notificationThresholds: [80, 95],   // fires namespace.quota.threshold webhooks
+});
+await ns.resetQuota({ namespace: 'production', service: 'sandbox' });
+await ns.listWithQuotas();
+```
+
+## Usage
+
+```typescript
+// Credits view (Oblien's converted units, grouped by service)
+const usage = await ns.usage(id, { days: 30 });
+const details = await ns.getDetails('production'); // quota + usage + transactions
+
+// RAW metered units — for external billing with your own rates
+const { data } = await ns.usageUnits('production', {
+  from: '2026-06-01T00:00:00Z', to: '2026-06-21T00:00:00Z', groupBy: 'day',
+});
+data.totals.vcpu_hours;   // cpu_time_minutes/60, gb_hours, network_gb, disk_io_gb …
+```
+
+`usageUnits` is deterministic for a range — poll it and idempotency-key on `(namespace, bucket.timestamp)`. The same raw units are also pushed per cycle on the `credits.usage` [webhook](./webhooks.md). Edge metrics (requests/bandwidth) per namespace come from [Analytics](./analytics.md) `home({ namespace })`.
+
+## Namespace-scoped API keys
+
+A namespace-scoped key is pinned to its namespace: list/get/usage/webhooks all auto-filter to it, and it can't widen scope. `user_id` is always the tenant gate.
+
+**Full reference:** [Namespaces API](https://oblien.com/docs/api/namespaces)

package/docs/notifications.md

@@ -0,0 +1,40 @@
+# Notifications
+
+Push notifications to the Oblien mobile app. Flow: **inside a workspace ▶ Oblien ▶ FCM ▶ device**. The app registers a device; you mint **virtual** send tokens scoped to a workspace; code inside that workspace sends with a token. The real device FCM token never leaves Oblien, and a virtual token can be revoked independently.
+
+```typescript
+const nt = client.notifications;
+```
+
+## Devices
+
+The mobile app registers itself. Keyed by a stable `device_id` (the FCM token rotates under it); the token is **validated with FCM before storage**.
+
+```typescript
+await nt.registerDevice({ device_id: 'dev_abc', fcm_token: '<fcm>', platform: 'ios' });
+await nt.listDevices();
+await nt.removeDevice(deviceId);
+```
+
+## Send tokens (per workspace)
+
+```typescript
+// Plaintext token returned ONCE — store it.
+const { token } = await nt.createToken({ workspace_id: 'ws_123', name: 'agent' });
+
+await nt.listTokens('ws_123');
+await nt.revokeToken(token.id);   // soft — stops routing
+await nt.deleteToken(token.id);   // permanent
+```
+
+## Send
+
+Authenticated by the virtual token itself (not client credentials) — callable from inside a workspace. Fans out to the token owner's active devices.
+
+```typescript
+await nt.send(token.token, { title: 'Build done', body: 'Agent finished', data: { run_id: 'abc' } });
+```
+
+Dead device tokens (app uninstalled) are auto-pruned on send.
+
+**Full reference:** [Notifications concept](https://oblien.com/docs/concepts/notifications) · [API](https://oblien.com/docs/api/notifications)

package/docs/pages.md

@@ -0,0 +1,26 @@
+# Pages
+
+Deploy static files from a workspace to the edge CDN. The workspace can stop or be deleted after export — the page stays live with automatic TLS. No running VM required.
+
+```typescript
+// Deploy build output from a workspace
+const { page } = await client.pages.create({
+  workspace_id: 'ws_abc',
+  path: '/app/dist',
+  name: 'my-app',
+});
+
+// Re-deploy with fresh files
+await client.pages.deploy(page.slug, { workspace_id: 'ws_abc', path: '/app/dist' });
+
+// Custom domain (automatic SSL)
+await client.pages.connectDomain(page.slug, { domain: 'app.example.com' });
+
+// Toggle
+await client.pages.disable(page.slug);
+await client.pages.enable(page.slug);
+```
+
+Pages are namespace-aware — pass `namespace` on create to group them and apply namespace scoping.
+
+**Full reference:** [Pages concept](https://oblien.com/docs/concepts/pages) · [Pages API](https://oblien.com/docs/api/pages)

package/docs/runtime.md

@@ -0,0 +1,83 @@
+# Runtime (data plane)
+
+The runtime connects to a **running** workspace and gives direct access to its filesystem, command execution, terminal sessions, code search, and file watchers — over the data plane (`workspace.oblien.com`).
+
+```typescript
+const rt = await client.workspaces.runtime('ws_abc');
+// or from a scoped handle:
+const rt = await client.workspace('ws_abc').runtime();
+```
+
+This enables the Runtime API server (if needed), fetches a gateway JWT, and returns a `Runtime` instance. The token is cached — subsequent calls for the same workspace return instantly.
+
+## Namespaces
+
+| Namespace | What it does |
+|---|---|
+| `rt.files` | List, read, write, stat, mkdir, delete, stream directory trees |
+| `rt.transfer` | Download/upload `tar.gz` archives, with optional progress callbacks |
+| `rt.exec` | Run commands, stream output, list/kill tasks, send stdin |
+| `rt.terminal` | Create PTY sessions, get scrollback, close sessions |
+| `rt.search` | Content search (ripgrep) + filename search |
+| `rt.watcher` | Watch directories for real-time file-change events |
+| `rt.ws()` | WebSocket — persistent connection for terminal I/O and watcher events |
+| `rt.proxy(port)` | Reverse-proxy HTTP/WebSocket to a **loopback** service inside the workspace |
+
+## Files
+
+```typescript
+const { entries } = await rt.files.list({ dirPath: '/app/src' });
+const file = await rt.files.read({ filePath: '/app/index.js' });
+await rt.files.write({ fullPath: '/app/hello.txt', content: 'hi', createDirs: true });
+await rt.files.delete({ path: '/app/tmp' });
+```
+
+## Exec
+
+```typescript
+const result = await rt.exec.run(['node', '--version']);
+console.log(result.stdout);
+
+// Stream long-running output
+for await (const event of rt.exec.stream(['npm', 'install'])) {
+  process.stdout.write(event.chunk ?? '');
+}
+```
+
+## Search
+
+```typescript
+const matches = await rt.search.content({ query: 'handleRequest', path: '/app' });
+const files = await rt.search.files({ query: 'controller' });
+```
+
+## Proxy
+
+Reach an HTTP or WebSocket server running on a **loopback port inside the workspace** (e.g. a dev server on `127.0.0.1:3000`) as if you were talking to it directly. Headers, streaming/SSE, and WebSocket upgrades pass through near-natively. For safety the proxy is **loopback-only** — it cannot reach the VM's private network or the internet.
+
+```typescript
+// HTTP — returns a raw fetch Response (status, headers, body/stream)
+const res = await rt.proxy(3000).fetch('/api/users?limit=10');
+const users = await res.json();
+
+// POST with a body
+await rt.proxy(3000).fetch('/api/users', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ name: 'ada' }),
+});
+
+// Streaming (SSE) passes through untouched
+const stream = await rt.proxy(8080).fetch('/events');
+for await (const chunk of stream.body!) { /* handle chunk */ }
+
+// WebSocket
+const ws = rt.proxy(3000).ws('/socket');
+ws.onmessage = (e) => console.log(e.data);
+```
+
+The runtime connection token is attached automatically (via the `Authorization` header for HTTP, and the `token` query param for WebSocket) and is **stripped before the request reaches the in-VM app**, so it never leaks to your code running inside the workspace.
+
+**HTTP transport (advanced).** The SDK calls the runtime endpoint `GET|POST|… /proxy<path>` and selects the target with the `X-Oblien-Proxy-Target: <port>` header. Equivalent forms the runtime also accepts: the `x_oblien_target=<port>` query param (used for WebSocket, since browsers can't set headers), or the path form `/proxy/<port>/<path>`. `token` and `x_oblien_target` are reserved query params and are removed before forwarding.
+
+**Full reference:** [Runtime API docs](https://oblien.com/docs/runtime-api)

package/docs/serve.md

@@ -0,0 +1,84 @@
+# Static server
+
+Serve a folder over HTTP and put it on the public internet in one step. The
+server is built entirely on Node's `http`/`fs` — **no extra dependencies** — and
+the CLI wires it straight into the [edge tunnel](./edge-tunnel.md), so a
+directory becomes a public HTTPS URL with a single command.
+
+## CLI
+
+```bash
+oblien serve                       # serve ./public
+oblien serve ./dist                # serve ./dist
+oblien serve ./dist --slug my-app  # pick the public subdomain
+oblien serve ./build --spa         # single-page-app fallback
+oblien serve ./site --domain preview.example.com
+```
+
+`oblien serve` starts a static server on a loopback port and then forwards it
+through the edge exactly like `oblien tunnel <port>` — so every tunnel flag
+works here too:
+
+| Flag | Description |
+| --- | --- |
+| `--port <n>` | Local port to serve on (default: an OS-assigned free port) |
+| `--slug <slug>` | Custom subdomain slug for the public URL |
+| `--name <name>` | Tunnel display name (default: the folder name) |
+| `--domain <domain>` | Base domain or exact custom hostname (see [edge-tunnel](./edge-tunnel.md)) |
+| `--expires-in <ttl>` | Tunnel token TTL, e.g. `30s`, `5m`, `1h`, `7d` |
+| `--spa` | Serve `index.html` for any unmatched path (client-side routing) |
+| `--no-listing` | Disable auto-generated directory listings |
+| `--index <file>` | Directory index filename (default: `index.html`) |
+
+Press `Ctrl+C` to stop — the tunnel disconnects and the local server shuts down.
+
+## What the server handles
+
+- **Correct MIME types** for common web, font, image, media, and document extensions.
+- **Streamed responses** (`createReadStream`) — large files never buffer in memory.
+- **`Range` requests** — media seeking / resumable downloads return `206 Partial Content`.
+- **Revalidation** — `ETag` + `Last-Modified` yield `304 Not Modified` on conditional requests.
+- **Directory handling** — serves `index.html`, redirects `/dir` → `/dir/`, and renders a clean listing when there's no index (unless `--no-listing`).
+- **SPA fallback** (`--spa`) — unmatched paths return the root `index.html`.
+- **Path-traversal protection** — requests are resolved against the root; anything escaping it lexically is rejected (`403`), and a file whose canonical path (following symlinks) leaves the root is rejected (`404`).
+- **Dotfiles denied by default** — `.git/`, `.env`, and other dot-paths return `404` (the server is often public), except `.well-known/`. Opt in with `allowDotfiles`.
+
+## Programmatic use
+
+The same server is exported from the SDK, so you can start it yourself and pair
+it with the [`TunnelClient`](./edge-tunnel.md) or use it standalone:
+
+```typescript
+import { startStaticServer } from 'oblien';
+
+const site = await startStaticServer({
+  root: './public',
+  spa: true,           // optional: index.html fallback
+  // port: 8080,       // optional: default is an OS-assigned free port
+  // host: '127.0.0.1' // optional: default loopback only
+});
+
+console.log(`serving on ${site.url}`); // http://127.0.0.1:<port>
+
+// ...later
+await site.close();
+```
+
+`startStaticServer(options)` resolves once the server is listening and returns a
+handle: `{ port, host, url, server, close() }`. The `port` is always resolved —
+even when you omit it and let the OS choose. For finer control, `createStaticServer(options)`
+returns a non-listening `http.Server`, and `createStaticHandler(options)` returns a
+raw `(req, res)` handler you can mount on your own server.
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `root` | `string` | — | Directory to serve (resolved against cwd) |
+| `host` | `string` | `127.0.0.1` | Interface to bind |
+| `port` | `number` | `0` (auto) | Port to listen on |
+| `index` | `string` | `index.html` | Directory index filename |
+| `listing` | `boolean` | `true` | Render a listing when a directory has no index |
+| `spa` | `boolean` | `false` | Serve the root index for unmatched paths |
+| `allowDotfiles` | `boolean` | `false` | Serve dotfiles/dot-directories (`.well-known/` is always allowed) |
+| `onRequest` | `(info) => void` | — | Per-request hook: `{ method, path, status }` |

package/docs/tokens.md

@@ -0,0 +1,24 @@
+# Scoped Tokens
+
+Issue short-lived, scoped JWTs for your end-users instead of sharing long-lived `clientId`/`clientSecret`. Ideal for SaaS: hand each tenant a token bound to their namespace (or a single workspace) that expires on its own.
+
+```typescript
+const { token, expiresAt, scope } = await client.tokens.create({
+  scope: 'namespace',      // 'namespace' | 'workspace'
+  namespace: 'team-a',     // required for namespace scope
+  ttl: 900,                // seconds (max 3600, default 900)
+  label: 'tenant-team-a',
+});
+```
+
+Use the returned token as the `token` option on a new client:
+
+```typescript
+const scoped = new Oblien({ token });
+// scoped is pinned to team-a — list/get/usage/webhooks auto-filter to it,
+// and it can't widen scope.
+```
+
+The token is self-contained (signature + expiry) — no DB lookup. Revoke early by blacklisting its `jti` server-side if needed.
+
+**Full reference:** [Scoped tokens API](https://oblien.com/docs/api/scoped-tokens)

package/docs/webhooks.md

@@ -0,0 +1,42 @@
+# Webhooks
+
+Subscribe an HTTPS endpoint to platform events (vm/workload lifecycle, credit usage, namespace quota thresholds), signed with HMAC-SHA256 (`X-Webhook-Signature`). A webhook can be **scoped to a namespace** so it only receives that namespace's events — or left account-wide.
+
+```typescript
+const wh = client.webhooks;
+```
+
+## Event types
+
+```typescript
+const { events } = await wh.events();
+```
+
+Includes: `vm.stopped`, `vm.archived`, `workload.started|exited|failed|stopped|restart_loop`, `credits.usage`, `credits.low`, `credits.depleted`, `namespace.quota.threshold`.
+
+## Create (namespace-scoped or account-wide)
+
+```typescript
+const { webhook } = await wh.create({
+  url: 'https://example.com/hooks/oblien',
+  events: ['credits.usage', 'namespace.quota.threshold', 'credits.depleted'],
+  namespace: 'team-a',           // ← only team-a's events; omit for account-wide
+  secret: process.env.WH_SECRET, // signs deliveries
+});
+```
+
+A namespace-bound webhook receives only events that carry that namespace; account-wide webhooks receive everything. Namespace-scoped API keys are auto-pinned to their namespace.
+
+## Manage
+
+```typescript
+const { webhooks } = await wh.list({ namespace: 'team-a' });
+await wh.update(webhook.id, { active: false });
+await wh.delete(webhook.id);
+```
+
+## Usage metering via webhook
+
+`credits.usage` is emitted per billing cycle with `{ namespace, workspace_id, usage: { cpu_time_minutes, memory_gb_minutes, disk_io_gb, network_gb } }` — a push alternative to polling [`namespaces.usageUnits`](./namespaces.md). Idempotent per event.
+
+**Full reference:** [Webhooks concept](https://oblien.com/docs/concepts/webhooks)

package/docs/workspaces.md

@@ -0,0 +1,82 @@
+# Workspaces
+
+A workspace is a hardware-isolated microVM that boots in under a second from any Docker image. It's the only primitive in Oblien — everything else (pages, proxies, domains) hangs off a workspace or the account.
+
+`client.workspaces` is the control-plane resource: create, configure, power, and destroy workspaces, plus a tree of sub-resources. To interact with a *running* workspace's filesystem/exec/terminal, see **[Runtime](./runtime.md)**.
+
+```typescript
+const ws = client.workspaces;
+```
+
+## CRUD
+
+```typescript
+const workspace = await ws.create({
+  image: 'node-20',     // any Docker image
+  mode: 'permanent',    // 'permanent' | 'temporary'
+  cpus: 2,
+  memory_mb: 4096,
+  namespace: 'team-a',  // optional — groups + applies namespace limits/quotas
+});
+
+const { workspaces } = await ws.list();
+const data = await ws.get(workspace.id);
+await ws.update(workspace.id, { name: 'my-api' });
+await ws.delete(workspace.id);
+```
+
+Creating in a namespace enforces that namespace's **resource limits** (max workspaces, per-workspace vCPU/RAM/disk) atomically, and **status** (a suspended/over-quota namespace rejects new workspaces). See **[Namespaces](./namespaces.md)**.
+
+## Power
+
+```typescript
+await ws.start(id);
+await ws.stop(id);
+await ws.restart(id);
+await ws.pause(id);    // freeze to disk
+await ws.resume(id);   // thaw
+```
+
+## Scoped handle
+
+Bind to one workspace so you never pass the ID again:
+
+```typescript
+const handle = client.workspace('ws_abc');
+
+await handle.start();
+const rt = await handle.runtime();
+await rt.exec.run(['npm', 'test']);
+await handle.stop();
+```
+
+## Runtime
+
+```typescript
+const rt = await client.workspaces.runtime('ws_abc');
+```
+
+Enables the Runtime API server, fetches + caches a gateway JWT, and returns a `Runtime` instance for the data plane (files, exec, terminal, search, watcher, transfer, WebSocket). → **[Runtime](./runtime.md)**.
+
+## Sub-resources
+
+Accessed as namespaces on `client.workspaces`:
+
+| Sub-resource | What it does |
+|---|---|
+| `lifecycle` | Permanent/temporary mode, TTL, ping |
+| `network` | Firewall, private links, outbound IP |
+| `ssh` | SSH enable/disable, password/key |
+| `publicAccess` | Expose ports with public URLs + automatic TLS |
+| `domains` | Custom domains with automatic SSL ([Domains](./domains.md)) |
+| `resources` | CPU / memory / disk allocation (upgrade — namespace caps enforced) |
+| `snapshots` | Snapshots and versioned archives |
+| `workloads` | Managed background processes |
+| `metrics` | Live stats, VM info/config |
+| `usage` | Credit usage + activity tracking |
+| `metadata` | Key-value metadata store |
+| `apiAccess` | Runtime API tokens (gateway JWT / raw) |
+| `logs` | Boot and command logs |
+| `images` | Available base images |
+
+**Full reference:** [API docs](https://oblien.com/docs/api/workspaces)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oblien",
-  "version": "2.2.36",
+  "version": "2.2.38",
   "description": "Official TypeScript SDK for the Oblien Workspace API",
   "type": "module",
   "main": "./dist/index.js",
@@ -24,7 +24,10 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc",