oblien 2.2.35 → 2.2.37

package/docs/runtime.md

@@ -0,0 +1,53 @@
+# 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 |
+
+## 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' });
+```
+
+**Full reference:** [Runtime API docs](https://oblien.com/docs/runtime-api)

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.35",
+  "version": "2.2.37",
   "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",