oblien 2.2.36 → 2.2.37

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,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.36",
+  "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",