oblien 2.2.36 → 2.2.38
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +53 -274
- package/dist/cdn.d.ts +105 -0
- package/dist/cdn.d.ts.map +1 -0
- package/dist/cdn.js +201 -0
- package/dist/cdn.js.map +1 -0
- package/dist/cli/commands/cdn.d.ts +3 -0
- package/dist/cli/commands/cdn.d.ts.map +1 -0
- package/dist/cli/commands/cdn.js +216 -0
- package/dist/cli/commands/cdn.js.map +1 -0
- package/dist/cli/commands/namespaces.js +19 -6
- package/dist/cli/commands/namespaces.js.map +1 -1
- package/dist/cli/commands/serve.d.ts +17 -0
- package/dist/cli/commands/serve.d.ts.map +1 -0
- package/dist/cli/commands/serve.js +113 -0
- package/dist/cli/commands/serve.js.map +1 -0
- package/dist/cli/commands/tunnel.d.ts +1 -0
- package/dist/cli/commands/tunnel.d.ts.map +1 -1
- package/dist/cli/commands/tunnel.js +100 -3
- package/dist/cli/commands/tunnel.js.map +1 -1
- package/dist/cli/index.js +14 -0
- package/dist/cli/index.js.map +1 -1
- package/dist/client.d.ts +12 -1
- package/dist/client.d.ts.map +1 -1
- package/dist/client.js +16 -1
- package/dist/client.js.map +1 -1
- package/dist/domain.d.ts +20 -1
- package/dist/domain.d.ts.map +1 -1
- package/dist/domain.js +37 -0
- package/dist/domain.js.map +1 -1
- package/dist/edge-proxy.d.ts +50 -11
- package/dist/edge-proxy.d.ts.map +1 -1
- package/dist/edge-proxy.js +55 -10
- package/dist/edge-proxy.js.map +1 -1
- package/dist/index.d.ts +8 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +5 -0
- package/dist/index.js.map +1 -1
- package/dist/mcp/tools.d.ts.map +1 -1
- package/dist/mcp/tools.js +145 -7
- package/dist/mcp/tools.js.map +1 -1
- package/dist/namespace.d.ts +27 -5
- package/dist/namespace.d.ts.map +1 -1
- package/dist/namespace.js +30 -4
- package/dist/namespace.js.map +1 -1
- package/dist/notifications.d.ts +72 -0
- package/dist/notifications.d.ts.map +1 -0
- package/dist/notifications.js +93 -0
- package/dist/notifications.js.map +1 -0
- package/dist/runtime/proxy.d.ts +55 -0
- package/dist/runtime/proxy.d.ts.map +1 -0
- package/dist/runtime/proxy.js +79 -0
- package/dist/runtime/proxy.js.map +1 -0
- package/dist/runtime.d.ts +16 -0
- package/dist/runtime.d.ts.map +1 -1
- package/dist/runtime.js +18 -0
- package/dist/runtime.js.map +1 -1
- package/dist/server/static.d.ts +81 -0
- package/dist/server/static.d.ts.map +1 -0
- package/dist/server/static.js +465 -0
- package/dist/server/static.js.map +1 -0
- package/dist/types/cdn.d.ts +301 -0
- package/dist/types/cdn.d.ts.map +1 -0
- package/dist/types/cdn.js +10 -0
- package/dist/types/cdn.js.map +1 -0
- package/dist/types/client.d.ts +10 -0
- package/dist/types/client.d.ts.map +1 -1
- package/dist/types/edge-proxy.d.ts +50 -1
- package/dist/types/edge-proxy.d.ts.map +1 -1
- package/dist/types/index.d.ts +6 -3
- package/dist/types/index.d.ts.map +1 -1
- package/dist/types/namespace.d.ts +55 -9
- package/dist/types/namespace.d.ts.map +1 -1
- package/dist/types/notifications.d.ts +77 -0
- package/dist/types/notifications.d.ts.map +1 -0
- package/dist/types/notifications.js +3 -0
- package/dist/types/notifications.js.map +1 -0
- package/dist/types/webhooks.d.ts +52 -0
- package/dist/types/webhooks.d.ts.map +1 -0
- package/dist/types/webhooks.js +3 -0
- package/dist/types/webhooks.js.map +1 -0
- package/dist/types/workspace-resources.d.ts +48 -0
- package/dist/types/workspace-resources.d.ts.map +1 -1
- package/dist/webhooks.d.ts +53 -0
- package/dist/webhooks.d.ts.map +1 -0
- package/dist/webhooks.js +60 -0
- package/dist/webhooks.js.map +1 -0
- package/docs/analytics.md +36 -0
- package/docs/cdn.md +119 -0
- package/docs/domains.md +47 -0
- package/docs/edge-proxy.md +44 -0
- package/docs/edge-tunnel.md +42 -0
- package/docs/errors.md +34 -0
- package/docs/namespaces.md +69 -0
- package/docs/notifications.md +40 -0
- package/docs/pages.md +26 -0
- package/docs/runtime.md +83 -0
- package/docs/serve.md +84 -0
- package/docs/tokens.md +24 -0
- package/docs/webhooks.md +42 -0
- package/docs/workspaces.md +82 -0
- package/package.json +5 -2
package/README.md
CHANGED
|
@@ -1,34 +1,15 @@
|
|
|
1
1
|
# Oblien SDK
|
|
2
2
|
|
|
3
|
-
Cloud workspaces that boot in milliseconds and run anything.
|
|
3
|
+
Cloud workspaces (sandboxes) that boot in milliseconds and run anything.
|
|
4
4
|
|
|
5
5
|
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.
|
|
6
6
|
|
|
7
|
-
This is the official TypeScript SDK
|
|
7
|
+
This is the official TypeScript SDK — it covers the full Oblien API surface across both planes:
|
|
8
8
|
|
|
9
|
-
**
|
|
9
|
+
- **Control plane** (`api.oblien.com`) — create, configure, power, snapshot, destroy workspaces; manage networking, domains, pages, namespaces, billing.
|
|
10
|
+
- **Data plane** (`workspace.oblien.com`) — a running workspace's filesystem, exec, terminal, watchers, and WebSocket events.
|
|
10
11
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
## Platform
|
|
14
|
-
|
|
15
|
-
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 with automatic TLS — or stay completely invisible.
|
|
16
|
-
|
|
17
|
-
The architecture is split into two planes:
|
|
18
|
-
|
|
19
|
-
- **Control plane** (`api.oblien.com`) — Create, configure, start, stop, snapshot, and destroy workspaces. Manage networking, domains, pages, namespaces, and billing.
|
|
20
|
-
- **Data plane** (`workspace.oblien.com`) — Interact with a running workspace's filesystem, execute commands, open terminal sessions, watch files, and stream events over WebSocket.
|
|
21
|
-
|
|
22
|
-
The SDK wraps both planes in a single client.
|
|
23
|
-
|
|
24
|
-
### What people build with it
|
|
25
|
-
|
|
26
|
-
- **AI agent environments** — A permanent workspace is the agent's home. It creates short-lived sandboxes on demand for tasks, user code, or deployments.
|
|
27
|
-
- **Service hosting** — Run an API server, a queue worker, or a database. Map it to a custom domain.
|
|
28
|
-
- **Static pages** — Deploy build output from a workspace to the edge CDN. No running VM required.
|
|
29
|
-
- **Remote development** — SSH into a workspace, install your stack, expose a port for live preview.
|
|
30
|
-
- **Per-user environments** — One workspace per customer with scoped networking, credit quotas, and full isolation.
|
|
31
|
-
- **Enterprise routing** — Route subdomains to external upstreams through the edge proxy.
|
|
12
|
+
**Hosted docs:** [oblien.com/docs](https://oblien.com/docs)
|
|
32
13
|
|
|
33
14
|
---
|
|
34
15
|
|
|
@@ -38,7 +19,7 @@ The SDK wraps both planes in a single client.
|
|
|
38
19
|
npm install oblien
|
|
39
20
|
```
|
|
40
21
|
|
|
41
|
-
|
|
22
|
+
Node.js 18+, ESM. Zero runtime dependencies.
|
|
42
23
|
|
|
43
24
|
---
|
|
44
25
|
|
|
@@ -53,247 +34,59 @@ const client = new Oblien({
|
|
|
53
34
|
});
|
|
54
35
|
|
|
55
36
|
// Create a workspace
|
|
56
|
-
const workspace = await client.workspaces.create({
|
|
57
|
-
image: 'node-20',
|
|
58
|
-
mode: 'permanent',
|
|
59
|
-
cpus: 2,
|
|
60
|
-
memory_mb: 4096,
|
|
61
|
-
});
|
|
37
|
+
const workspace = await client.workspaces.create({ image: 'node-20', cpus: 2, memory_mb: 4096 });
|
|
62
38
|
|
|
63
39
|
// Connect to the runtime — filesystem, exec, terminal
|
|
64
40
|
const rt = await client.workspaces.runtime(workspace.id);
|
|
65
|
-
|
|
66
|
-
// Run a command
|
|
67
41
|
const result = await rt.exec.run(['node', '--version']);
|
|
68
42
|
console.log(result.stdout);
|
|
69
|
-
|
|
70
|
-
// Read a file
|
|
71
|
-
const file = await rt.files.read({ filePath: '/etc/os-release' });
|
|
72
|
-
console.log(file.content);
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
---
|
|
76
|
-
|
|
77
|
-
## SDK structure
|
|
78
|
-
|
|
79
|
-
```
|
|
80
|
-
client
|
|
81
|
-
├── workspaces Control-plane workspace CRUD + power + sub-resources
|
|
82
|
-
│ ├── lifecycle Permanent/temporary mode, TTL, ping
|
|
83
|
-
│ ├── network Firewall, private links, outbound IP
|
|
84
|
-
│ ├── ssh SSH enable/disable, password/key
|
|
85
|
-
│ ├── publicAccess Expose ports with public URLs
|
|
86
|
-
│ ├── domains Custom domains with automatic SSL
|
|
87
|
-
│ ├── resources CPU, memory, disk allocation
|
|
88
|
-
│ ├── snapshots Snapshots and versioned archives
|
|
89
|
-
│ ├── workloads Managed background processes
|
|
90
|
-
│ ├── metrics Live stats, VM info/config
|
|
91
|
-
│ ├── usage Credit usage and activity tracking
|
|
92
|
-
│ ├── metadata Key-value metadata store
|
|
93
|
-
│ ├── apiAccess Runtime API tokens (gateway JWT / raw)
|
|
94
|
-
│ ├── logs Boot and command logs
|
|
95
|
-
│ └── images Available base images
|
|
96
|
-
│
|
|
97
|
-
├── pages Static pages — deploy to the edge CDN from any workspace
|
|
98
|
-
├── namespaces Group workspaces, enforce resource limits and quotas
|
|
99
|
-
├── edgeProxy Enterprise reverse proxy — route subdomains to upstreams
|
|
100
|
-
├── domain Pre-flight checks — slug availability + DNS verification
|
|
101
|
-
│
|
|
102
|
-
└── workspace(id) Scoped handle — all methods pre-filled with a workspace ID
|
|
103
|
-
```
|
|
104
|
-
|
|
105
|
-
---
|
|
106
|
-
|
|
107
|
-
## Workspaces
|
|
108
|
-
|
|
109
|
-
```typescript
|
|
110
|
-
const ws = client.workspaces;
|
|
111
|
-
|
|
112
|
-
// CRUD
|
|
113
|
-
const workspace = await ws.create({ image: 'node-20' });
|
|
114
|
-
const { workspaces } = await ws.list();
|
|
115
|
-
const data = await ws.get(workspace.id);
|
|
116
|
-
await ws.update(workspace.id, { name: 'my-api' });
|
|
117
|
-
await ws.delete(workspace.id);
|
|
118
|
-
|
|
119
|
-
// Power
|
|
120
|
-
await ws.start(id);
|
|
121
|
-
await ws.stop(id);
|
|
122
|
-
await ws.restart(id);
|
|
123
|
-
await ws.pause(id);
|
|
124
|
-
await ws.resume(id);
|
|
125
|
-
```
|
|
126
|
-
|
|
127
|
-
Sub-resources are accessed through namespaces on the workspaces object — `ws.lifecycle`, `ws.network`, `ws.domains`, etc. See the [API reference](https://oblien.com/docs/api) for full details on each.
|
|
128
|
-
|
|
129
|
-
### Scoped handle
|
|
130
|
-
|
|
131
|
-
Bind to a single workspace so you don't have to pass the ID every time:
|
|
132
|
-
|
|
133
|
-
```typescript
|
|
134
|
-
const handle = client.workspace('ws_abc');
|
|
135
|
-
|
|
136
|
-
await handle.start();
|
|
137
|
-
const rt = await handle.runtime();
|
|
138
|
-
await rt.exec.run(['npm', 'test']);
|
|
139
|
-
await handle.stop();
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
---
|
|
143
|
-
|
|
144
|
-
## Runtime (data plane)
|
|
145
|
-
|
|
146
|
-
The runtime connects to a running workspace and gives you direct access to its filesystem, command execution, terminal sessions, code search, and file watchers.
|
|
147
|
-
|
|
148
|
-
```typescript
|
|
149
|
-
const rt = await client.workspaces.runtime('ws_abc');
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
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.
|
|
153
|
-
|
|
154
|
-
| Namespace | What it does |
|
|
155
|
-
|-----------|-------------|
|
|
156
|
-
| `rt.files` | List, read, write, stat, mkdir, delete, stream directory trees |
|
|
157
|
-
| `rt.transfer` | Download and upload `tar.gz` archives, with optional client-side progress callbacks |
|
|
158
|
-
| `rt.exec` | Run commands, stream output, list/kill tasks, send stdin |
|
|
159
|
-
| `rt.terminal` | Create PTY sessions, get scrollback, close sessions |
|
|
160
|
-
| `rt.search` | Content search (ripgrep) and filename search |
|
|
161
|
-
| `rt.watcher` | Watch directories for real-time file change events |
|
|
162
|
-
| `rt.ws()` | WebSocket — persistent connection for terminal I/O and watcher events |
|
|
163
|
-
|
|
164
|
-
See the [Runtime API docs](https://oblien.com/docs/runtime-api) for full endpoint reference.
|
|
165
|
-
|
|
166
|
-
---
|
|
167
|
-
|
|
168
|
-
## Pages
|
|
169
|
-
|
|
170
|
-
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.
|
|
171
|
-
|
|
172
|
-
```typescript
|
|
173
|
-
// Deploy a page
|
|
174
|
-
const { page } = await client.pages.create({
|
|
175
|
-
workspace_id: 'ws_abc',
|
|
176
|
-
path: '/app/dist',
|
|
177
|
-
name: 'my-app',
|
|
178
|
-
});
|
|
179
|
-
|
|
180
|
-
// Re-deploy with fresh files
|
|
181
|
-
await client.pages.deploy(page.slug, {
|
|
182
|
-
workspace_id: 'ws_abc',
|
|
183
|
-
path: '/app/dist',
|
|
184
|
-
});
|
|
185
|
-
|
|
186
|
-
// Custom domain
|
|
187
|
-
await client.pages.connectDomain(page.slug, { domain: 'app.example.com' });
|
|
188
|
-
|
|
189
|
-
// Toggle
|
|
190
|
-
await client.pages.disable(page.slug);
|
|
191
|
-
await client.pages.enable(page.slug);
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
See the [Pages docs](https://oblien.com/docs/concepts/pages) for concepts and the [Pages API](https://oblien.com/docs/api/pages) for the full reference.
|
|
195
|
-
|
|
196
|
-
---
|
|
197
|
-
|
|
198
|
-
## Domains
|
|
199
|
-
|
|
200
|
-
Pre-flight checks before connecting custom domains or claiming slugs. These are standalone — not scoped to a specific workspace or page.
|
|
201
|
-
|
|
202
|
-
```typescript
|
|
203
|
-
// Check if a slug is available
|
|
204
|
-
const { available, url } = await client.domain.checkSlug({ slug: 'my-app' });
|
|
205
|
-
|
|
206
|
-
// Verify DNS for a custom domain
|
|
207
|
-
const { verified, cname, ownership, errors, required_records } = await client.domain.verify({
|
|
208
|
-
domain: 'app.example.com',
|
|
209
|
-
resource_id: 'ws_abc',
|
|
210
|
-
});
|
|
211
|
-
|
|
212
|
-
if (!verified) {
|
|
213
|
-
console.log(errors);
|
|
214
|
-
console.log(required_records);
|
|
215
|
-
}
|
|
216
43
|
```
|
|
217
44
|
|
|
218
|
-
Standard plans require both edge DNS and TXT ownership. Enterprise custom-domain grants can verify with edge DNS only.
|
|
219
|
-
|
|
220
45
|
---
|
|
221
46
|
|
|
222
|
-
##
|
|
47
|
+
## Features
|
|
223
48
|
|
|
224
|
-
|
|
49
|
+
The client wraps every part of the platform. Each feature has a deep-dive page in [`docs/`](./docs).
|
|
225
50
|
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
51
|
+
| Feature | Accessor | What it does | Guide |
|
|
52
|
+
|---------|----------|--------------|-------|
|
|
53
|
+
| **Workspaces** | `client.workspaces`, `client.workspace(id)` | microVM CRUD, power, and 14 sub-resources (network, ssh, snapshots, …) | [docs/workspaces](./docs/workspaces.md) |
|
|
54
|
+
| **Runtime** | `client.workspaces.runtime(id)` | Data plane: files, exec, terminal, search, watchers, WebSocket | [docs/runtime](./docs/runtime.md) |
|
|
55
|
+
| **Pages** | `client.pages` | Deploy static files to the edge CDN with automatic TLS | [docs/pages](./docs/pages.md) |
|
|
56
|
+
| **Namespaces** | `client.namespaces` | Group workspaces; resource limits, quotas, per-namespace usage | [docs/namespaces](./docs/namespaces.md) |
|
|
57
|
+
| **Domains** | `client.domain` | Slug/DNS pre-flight, route listing, SSL certs + auto-renew | [docs/domains](./docs/domains.md) |
|
|
58
|
+
| **Edge Proxy** | `client.edgeProxy` | Reverse-proxy subdomains to *verified* external upstreams | [docs/edge-proxy](./docs/edge-proxy.md) |
|
|
59
|
+
| **Edge Tunnel** | `client.edgeTunnel` | Expose a local port to the internet (ngrok-style) | [docs/edge-tunnel](./docs/edge-tunnel.md) |
|
|
60
|
+
| **Notifications** | `client.notifications` | Mobile push via per-workspace virtual send tokens | [docs/notifications](./docs/notifications.md) |
|
|
61
|
+
| **Webhooks** | `client.webhooks` | Subscribe to events; HMAC-signed, namespace-scopable | [docs/webhooks](./docs/webhooks.md) |
|
|
62
|
+
| **Analytics** | `client.analytics` | Edge traffic — requests, bandwidth, geo, live stream | [docs/analytics](./docs/analytics.md) |
|
|
63
|
+
| **Scoped Tokens** | `client.tokens` | Short-lived, per-tenant scoped JWTs | [docs/tokens](./docs/tokens.md) |
|
|
64
|
+
| **CDN** | `client.cdn` | Upload files, mint upload tokens, manage stored files (namespace-aware) | [docs/cdn](./docs/cdn.md) |
|
|
65
|
+
| **Errors** | `import { OblienError, … }` | Typed error classes for every HTTP status | [docs/errors](./docs/errors.md) |
|
|
231
66
|
|
|
232
|
-
|
|
233
|
-
period: 'monthly',
|
|
234
|
-
max_credits: 500,
|
|
235
|
-
overdraft_action: 'stop',
|
|
236
|
-
});
|
|
67
|
+
### Map at a glance
|
|
237
68
|
|
|
238
|
-
const { namespaces } = await client.namespaces.list();
|
|
239
69
|
```
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
domain: 'edge.example.com',
|
|
254
|
-
target: 'https://internal-staging.example.com:8080',
|
|
255
|
-
});
|
|
256
|
-
|
|
257
|
-
await client.edgeProxy.disable(proxy.id);
|
|
258
|
-
await client.edgeProxy.enable(proxy.id);
|
|
70
|
+
client
|
|
71
|
+
├── workspaces microVM CRUD + power + sub-resources → docs/workspaces.md
|
|
72
|
+
│ └── runtime(id) files · exec · terminal · search · ws → docs/runtime.md
|
|
73
|
+
├── workspace(id) scoped handle (ID pre-filled)
|
|
74
|
+
├── pages static deploys to the edge CDN → docs/pages.md
|
|
75
|
+
├── namespaces grouping · limits · quotas · usage → docs/namespaces.md
|
|
76
|
+
├── domain slug/DNS checks · routes · SSL → docs/domains.md
|
|
77
|
+
├── edgeProxy subdomain → verified upstream → docs/edge-proxy.md
|
|
78
|
+
├── edgeTunnel local port → public URL → docs/edge-tunnel.md
|
|
79
|
+
├── notifications mobile push (virtual tokens) → docs/notifications.md
|
|
80
|
+
├── webhooks event subscriptions → docs/webhooks.md
|
|
81
|
+
├── analytics edge traffic metrics → docs/analytics.md
|
|
82
|
+
└── tokens short-lived scoped tokens → docs/tokens.md
|
|
259
83
|
```
|
|
260
84
|
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
---
|
|
264
|
-
|
|
265
|
-
## Error handling
|
|
85
|
+
### Also included
|
|
266
86
|
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
import {
|
|
271
|
-
OblienError,
|
|
272
|
-
NotFoundError,
|
|
273
|
-
RateLimitError,
|
|
274
|
-
PaymentRequiredError,
|
|
275
|
-
} from 'oblien';
|
|
276
|
-
|
|
277
|
-
try {
|
|
278
|
-
await client.workspaces.get('ws_nonexistent');
|
|
279
|
-
} catch (err) {
|
|
280
|
-
if (err instanceof NotFoundError) { /* 404 */ }
|
|
281
|
-
if (err instanceof RateLimitError) { /* 429 — back off */ }
|
|
282
|
-
if (err instanceof PaymentRequiredError) { /* 402 — quota exceeded */ }
|
|
283
|
-
if (err instanceof OblienError) {
|
|
284
|
-
console.error(err.code, err.message, err.details, err.requestId);
|
|
285
|
-
}
|
|
286
|
-
}
|
|
287
|
-
```
|
|
288
|
-
|
|
289
|
-
| Error class | HTTP | When |
|
|
290
|
-
|-------------|------|------|
|
|
291
|
-
| `AuthenticationError` | 401 | Invalid or missing credentials |
|
|
292
|
-
| `PaymentRequiredError` | 402 | Credit quota exceeded |
|
|
293
|
-
| `NotFoundError` | 404 | Resource does not exist |
|
|
294
|
-
| `ConflictError` | 409 | Resource in wrong state |
|
|
295
|
-
| `ValidationError` | 422 | Invalid parameters |
|
|
296
|
-
| `RateLimitError` | 429 | Too many requests |
|
|
87
|
+
- **CLI** — `npx oblien …` (auth, workspaces, exec, scp, terminal, tunnels, …). See [CLI docs](https://oblien.com/docs/cli).
|
|
88
|
+
- **Static server** — `oblien serve ./public` serves a folder and puts it on a public URL through the edge tunnel; also exported as `startStaticServer()`. Zero dependencies. See [docs/serve](./docs/serve.md).
|
|
89
|
+
- **MCP server** — `oblien-mcp` exposes the SDK as Model Context Protocol tools for agents. See [MCP docs](https://oblien.com/docs/mcp).
|
|
297
90
|
|
|
298
91
|
---
|
|
299
92
|
|
|
@@ -301,50 +94,36 @@ try {
|
|
|
301
94
|
|
|
302
95
|
```typescript
|
|
303
96
|
const client = new Oblien({
|
|
304
|
-
clientId: 'your_client_id',
|
|
305
|
-
clientSecret: 'your_client_secret',
|
|
306
|
-
baseUrl: 'https://api.oblien.com',
|
|
97
|
+
clientId: 'your_client_id', // required
|
|
98
|
+
clientSecret: 'your_client_secret', // required
|
|
99
|
+
baseUrl: 'https://api.oblien.com', // optional (default)
|
|
307
100
|
});
|
|
101
|
+
|
|
102
|
+
// Or a short-lived scoped token (see docs/tokens.md):
|
|
103
|
+
const scoped = new Oblien({ token });
|
|
308
104
|
```
|
|
309
105
|
|
|
310
|
-
Get
|
|
106
|
+
Get API keys from the [dashboard](https://oblien.com/dashboard/settings).
|
|
311
107
|
|
|
312
108
|
---
|
|
313
109
|
|
|
314
110
|
## TypeScript
|
|
315
111
|
|
|
316
|
-
Written in TypeScript with full
|
|
112
|
+
Written in TypeScript with full declarations shipped. Every request param, response shape, and event type is exported:
|
|
317
113
|
|
|
318
114
|
```typescript
|
|
319
115
|
import type {
|
|
320
116
|
WorkspaceCreateParams, WorkspaceData,
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
EdgeProxyCreateParams,
|
|
324
|
-
ExecStreamEvent, WSTerminalEvent,
|
|
117
|
+
NamespaceUsageUnits, EdgeProxyCreateParams,
|
|
118
|
+
WebhookEvent, ExecStreamEvent,
|
|
325
119
|
} from 'oblien';
|
|
326
120
|
```
|
|
327
121
|
|
|
328
122
|
---
|
|
329
123
|
|
|
330
|
-
## Requirements
|
|
331
|
-
|
|
332
|
-
- Node.js 18+
|
|
333
|
-
- TypeScript 5.0+ (if using TypeScript)
|
|
334
|
-
- ESM (`"type": "module"` in your package.json, or use dynamic `import()`)
|
|
335
|
-
|
|
336
|
-
---
|
|
337
|
-
|
|
338
124
|
## Links
|
|
339
125
|
|
|
340
|
-
- [Documentation](https://oblien.com/docs)
|
|
341
|
-
- [Quickstart](https://oblien.com/docs/workspace/quickstart)
|
|
342
|
-
- [SDK setup guide](https://oblien.com/docs/workspace/sdk-setup)
|
|
343
|
-
- [API reference](https://oblien.com/docs/api)
|
|
344
|
-
- [Runtime API](https://oblien.com/docs/runtime-api)
|
|
345
|
-
- [Dashboard](https://oblien.com/dashboard)
|
|
346
|
-
|
|
347
|
-
---
|
|
126
|
+
- [Documentation](https://oblien.com/docs) · [Quickstart](https://oblien.com/docs/workspace/quickstart) · [API reference](https://oblien.com/docs/api) · [Runtime API](https://oblien.com/docs/runtime-api) · [Dashboard](https://oblien.com/dashboard)
|
|
348
127
|
|
|
349
128
|
## License
|
|
350
129
|
|
package/dist/cdn.d.ts
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
import type { HttpClient } from './http.js';
|
|
2
|
+
import type { CdnTokenParams, CdnTokenResponse, CdnUploadInput, CdnUploadParams, CdnUploadResponse, CdnUploadManyResponse, CdnProcessUrlsParams, CdnProcessUrlsResponse, CdnLimitsResponse, CdnVariantOptionsResponse, CdnListParams, CdnListResponse, CdnStatsParams, CdnStatsResponse, CdnFileResponse, CdnUsageParams, CdnUsageResponse, CdnUsageSeriesParams, CdnUsageSeriesResponse } from './types/cdn.js';
|
|
3
|
+
import type { ApiResponse } from './types/common.js';
|
|
4
|
+
/**
|
|
5
|
+
* CDN — issue upload tokens, upload files, and manage stored files.
|
|
6
|
+
*
|
|
7
|
+
* The CDN spans two planes. Token issuance and file management go through the
|
|
8
|
+
* API host (`client._http`); uploads go directly to the CDN edge host with a
|
|
9
|
+
* short-lived token. Every operation is namespace-aware: pass `namespace` to
|
|
10
|
+
* scope a token/upload/listing, or omit it (admin/dashboard callers see all of
|
|
11
|
+
* their files). Namespace-scoped API keys are automatically pinned to their
|
|
12
|
+
* own namespace by the server.
|
|
13
|
+
*
|
|
14
|
+
* ```ts
|
|
15
|
+
* import Oblien from 'oblien';
|
|
16
|
+
* import { readFileSync } from 'node:fs';
|
|
17
|
+
* const client = new Oblien({ clientId, clientSecret });
|
|
18
|
+
*
|
|
19
|
+
* // One-shot: mints a token and uploads, scoped to a namespace
|
|
20
|
+
* const { url } = await client.cdn.upload(
|
|
21
|
+
* { data: readFileSync('./logo.png'), filename: 'logo.png', contentType: 'image/png' },
|
|
22
|
+
* { namespace: 'tenant-a' },
|
|
23
|
+
* );
|
|
24
|
+
*
|
|
25
|
+
* // List / stats for that namespace
|
|
26
|
+
* const { data } = await client.cdn.list({ namespace: 'tenant-a' });
|
|
27
|
+
* await client.cdn.stats({ namespace: 'tenant-a' });
|
|
28
|
+
* ```
|
|
29
|
+
*/
|
|
30
|
+
export declare class Cdn {
|
|
31
|
+
/** @internal */
|
|
32
|
+
readonly _http: HttpClient;
|
|
33
|
+
/** @internal — CDN edge base, incl. the `/api` mount (e.g. https://cdn.oblien.com/api). */
|
|
34
|
+
private readonly _cdnBaseUrl;
|
|
35
|
+
private readonly _base;
|
|
36
|
+
constructor(client: {
|
|
37
|
+
_http: HttpClient;
|
|
38
|
+
_cdnBaseUrl: string;
|
|
39
|
+
});
|
|
40
|
+
/**
|
|
41
|
+
* Mint a short-lived (1 min) USER-scope CDN token (upload + process).
|
|
42
|
+
* Requires an admin- or namespace-scoped API key.
|
|
43
|
+
*/
|
|
44
|
+
token(params?: CdnTokenParams): Promise<CdnTokenResponse>;
|
|
45
|
+
/**
|
|
46
|
+
* Mint a short-lived ADMIN-scope CDN token (full edge access incl. delete).
|
|
47
|
+
* Requires an admin API key.
|
|
48
|
+
*/
|
|
49
|
+
adminToken(params?: CdnTokenParams): Promise<CdnTokenResponse>;
|
|
50
|
+
/**
|
|
51
|
+
* Upload a single file to the CDN edge. Mints a user token automatically
|
|
52
|
+
* (bound to `params.namespace`, carrying `params.metadata` — variant/TTL
|
|
53
|
+
* options), or reuses `params.token` if given.
|
|
54
|
+
*/
|
|
55
|
+
upload(file: CdnUploadInput, params?: CdnUploadParams): Promise<CdnUploadResponse>;
|
|
56
|
+
/**
|
|
57
|
+
* Upload multiple files in one request (field `files`). Mints a single token
|
|
58
|
+
* for the batch, bound to `params.namespace` and carrying `params.metadata`.
|
|
59
|
+
*/
|
|
60
|
+
uploadMany(files: CdnUploadInput[], params?: CdnUploadParams): Promise<CdnUploadManyResponse>;
|
|
61
|
+
/**
|
|
62
|
+
* Ingest files from remote URLs (edge downloads + processes them). Variant
|
|
63
|
+
* options travel in the token metadata (the edge reads them from the permit),
|
|
64
|
+
* so `metadata` is baked into the auto-minted token; the request body only
|
|
65
|
+
* carries `urls` + batch controls.
|
|
66
|
+
*/
|
|
67
|
+
processUrls(params: CdnProcessUrlsParams): Promise<CdnProcessUrlsResponse>;
|
|
68
|
+
/** Get the edge upload size/count limits. Mints a user token if none given. */
|
|
69
|
+
getLimits(params?: {
|
|
70
|
+
token?: string;
|
|
71
|
+
namespace?: string;
|
|
72
|
+
}): Promise<CdnLimitsResponse>;
|
|
73
|
+
/** Get the available image variant configurations. Mints a user token if none given. */
|
|
74
|
+
getVariantOptions(params?: {
|
|
75
|
+
token?: string;
|
|
76
|
+
namespace?: string;
|
|
77
|
+
}): Promise<CdnVariantOptionsResponse>;
|
|
78
|
+
/** List logged files for the caller, optionally filtered by namespace. */
|
|
79
|
+
list(params?: CdnListParams): Promise<CdnListResponse>;
|
|
80
|
+
/** Storage statistics for the caller, optionally scoped to a namespace. */
|
|
81
|
+
stats(params?: CdnStatsParams): Promise<CdnStatsResponse>;
|
|
82
|
+
/**
|
|
83
|
+
* Per-namespace usage for a month: ingest (uploaded in the month, incl.
|
|
84
|
+
* variants) + current active footprint, and the configured caps.
|
|
85
|
+
*/
|
|
86
|
+
usage(params?: CdnUsageParams): Promise<CdnUsageResponse>;
|
|
87
|
+
/**
|
|
88
|
+
* Windowed ingest series (bytes/files uploaded per day or month), zero-filled
|
|
89
|
+
* over the window — for usage charts.
|
|
90
|
+
*/
|
|
91
|
+
usageSeries(params?: CdnUsageSeriesParams): Promise<CdnUsageSeriesResponse>;
|
|
92
|
+
/** Get a single logged file by its id. */
|
|
93
|
+
get(fileId: number | string): Promise<CdnFileResponse>;
|
|
94
|
+
/** Soft-delete a logged file. */
|
|
95
|
+
delete(fileId: number | string): Promise<ApiResponse>;
|
|
96
|
+
/** Restore a soft-deleted file. */
|
|
97
|
+
restore(fileId: number | string): Promise<ApiResponse>;
|
|
98
|
+
/**
|
|
99
|
+
* Call the CDN edge host with a Bearer token. Uploads pass a `FormData`
|
|
100
|
+
* body; JSON endpoints pass a plain object. Mirrors HttpClient's
|
|
101
|
+
* body-first error handling and reuses the shared error builder.
|
|
102
|
+
*/
|
|
103
|
+
private _edgeRequest;
|
|
104
|
+
}
|
|
105
|
+
//# sourceMappingURL=cdn.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"cdn.d.ts","sourceRoot":"","sources":["../src/cdn.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,yBAAyB,EACzB,aAAa,EACb,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AASrD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,GAAG;IACd,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;gBAEpB,MAAM,EAAE;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;IAO9D;;;OAGG;IACG,KAAK,CAAC,MAAM,GAAE,cAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQnE;;;OAGG;IACG,UAAU,CAAC,MAAM,GAAE,cAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAUxE;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,cAAc,EAAE,MAAM,GAAE,eAAoB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAO5F;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,MAAM,GAAE,eAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC;IASvG;;;;;OAKG;IACG,WAAW,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAMhF,+EAA+E;IACzE,SAAS,CAAC,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAKhG,wFAAwF;IAClF,iBAAiB,CAAC,MAAM,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAAG,OAAO,CAAC,yBAAyB,CAAC;IAOhH,0EAA0E;IACpE,IAAI,CAAC,MAAM,GAAE,aAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IAQhE,2EAA2E;IACrE,KAAK,CAAC,MAAM,GAAE,cAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQnE;;;OAGG;IACG,KAAK,CAAC,MAAM,GAAE,cAAmB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAQnE;;;OAGG;IACG,WAAW,CAAC,MAAM,GAAE,oBAAyB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAQrF,0CAA0C;IACpC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAO5D,iCAAiC;IAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAO3D,mCAAmC;IAC7B,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAS5D;;;;OAIG;YACW,YAAY;CA4B3B"}
|