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.
Files changed (101) hide show
  1. package/README.md +53 -274
  2. package/dist/cdn.d.ts +105 -0
  3. package/dist/cdn.d.ts.map +1 -0
  4. package/dist/cdn.js +201 -0
  5. package/dist/cdn.js.map +1 -0
  6. package/dist/cli/commands/cdn.d.ts +3 -0
  7. package/dist/cli/commands/cdn.d.ts.map +1 -0
  8. package/dist/cli/commands/cdn.js +216 -0
  9. package/dist/cli/commands/cdn.js.map +1 -0
  10. package/dist/cli/commands/namespaces.js +19 -6
  11. package/dist/cli/commands/namespaces.js.map +1 -1
  12. package/dist/cli/commands/serve.d.ts +17 -0
  13. package/dist/cli/commands/serve.d.ts.map +1 -0
  14. package/dist/cli/commands/serve.js +113 -0
  15. package/dist/cli/commands/serve.js.map +1 -0
  16. package/dist/cli/commands/tunnel.d.ts +1 -0
  17. package/dist/cli/commands/tunnel.d.ts.map +1 -1
  18. package/dist/cli/commands/tunnel.js +100 -3
  19. package/dist/cli/commands/tunnel.js.map +1 -1
  20. package/dist/cli/index.js +14 -0
  21. package/dist/cli/index.js.map +1 -1
  22. package/dist/client.d.ts +12 -1
  23. package/dist/client.d.ts.map +1 -1
  24. package/dist/client.js +16 -1
  25. package/dist/client.js.map +1 -1
  26. package/dist/domain.d.ts +20 -1
  27. package/dist/domain.d.ts.map +1 -1
  28. package/dist/domain.js +37 -0
  29. package/dist/domain.js.map +1 -1
  30. package/dist/edge-proxy.d.ts +50 -11
  31. package/dist/edge-proxy.d.ts.map +1 -1
  32. package/dist/edge-proxy.js +55 -10
  33. package/dist/edge-proxy.js.map +1 -1
  34. package/dist/index.d.ts +8 -1
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +5 -0
  37. package/dist/index.js.map +1 -1
  38. package/dist/mcp/tools.d.ts.map +1 -1
  39. package/dist/mcp/tools.js +145 -7
  40. package/dist/mcp/tools.js.map +1 -1
  41. package/dist/namespace.d.ts +27 -5
  42. package/dist/namespace.d.ts.map +1 -1
  43. package/dist/namespace.js +30 -4
  44. package/dist/namespace.js.map +1 -1
  45. package/dist/notifications.d.ts +72 -0
  46. package/dist/notifications.d.ts.map +1 -0
  47. package/dist/notifications.js +93 -0
  48. package/dist/notifications.js.map +1 -0
  49. package/dist/runtime/proxy.d.ts +55 -0
  50. package/dist/runtime/proxy.d.ts.map +1 -0
  51. package/dist/runtime/proxy.js +79 -0
  52. package/dist/runtime/proxy.js.map +1 -0
  53. package/dist/runtime.d.ts +16 -0
  54. package/dist/runtime.d.ts.map +1 -1
  55. package/dist/runtime.js +18 -0
  56. package/dist/runtime.js.map +1 -1
  57. package/dist/server/static.d.ts +81 -0
  58. package/dist/server/static.d.ts.map +1 -0
  59. package/dist/server/static.js +465 -0
  60. package/dist/server/static.js.map +1 -0
  61. package/dist/types/cdn.d.ts +301 -0
  62. package/dist/types/cdn.d.ts.map +1 -0
  63. package/dist/types/cdn.js +10 -0
  64. package/dist/types/cdn.js.map +1 -0
  65. package/dist/types/client.d.ts +10 -0
  66. package/dist/types/client.d.ts.map +1 -1
  67. package/dist/types/edge-proxy.d.ts +50 -1
  68. package/dist/types/edge-proxy.d.ts.map +1 -1
  69. package/dist/types/index.d.ts +6 -3
  70. package/dist/types/index.d.ts.map +1 -1
  71. package/dist/types/namespace.d.ts +55 -9
  72. package/dist/types/namespace.d.ts.map +1 -1
  73. package/dist/types/notifications.d.ts +77 -0
  74. package/dist/types/notifications.d.ts.map +1 -0
  75. package/dist/types/notifications.js +3 -0
  76. package/dist/types/notifications.js.map +1 -0
  77. package/dist/types/webhooks.d.ts +52 -0
  78. package/dist/types/webhooks.d.ts.map +1 -0
  79. package/dist/types/webhooks.js +3 -0
  80. package/dist/types/webhooks.js.map +1 -0
  81. package/dist/types/workspace-resources.d.ts +48 -0
  82. package/dist/types/workspace-resources.d.ts.map +1 -1
  83. package/dist/webhooks.d.ts +53 -0
  84. package/dist/webhooks.d.ts.map +1 -0
  85. package/dist/webhooks.js +60 -0
  86. package/dist/webhooks.js.map +1 -0
  87. package/docs/analytics.md +36 -0
  88. package/docs/cdn.md +119 -0
  89. package/docs/domains.md +47 -0
  90. package/docs/edge-proxy.md +44 -0
  91. package/docs/edge-tunnel.md +42 -0
  92. package/docs/errors.md +34 -0
  93. package/docs/namespaces.md +69 -0
  94. package/docs/notifications.md +40 -0
  95. package/docs/pages.md +26 -0
  96. package/docs/runtime.md +83 -0
  97. package/docs/serve.md +84 -0
  98. package/docs/tokens.md +24 -0
  99. package/docs/webhooks.md +42 -0
  100. package/docs/workspaces.md +82 -0
  101. 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. It covers the full Oblien API surface.
7
+ This is the official TypeScript SDK — it covers the full Oblien API surface across both planes:
8
8
 
9
- **Documentation:** [https://oblien.com/docs](https://oblien.com/docs)
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
- Requires Node.js 18 or later. Zero runtime dependencies.
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
- ## Namespaces
47
+ ## Features
223
48
 
224
- Group workspaces into isolated namespaces with resource limits, spending quotas, and lifecycle controls.
49
+ The client wraps every part of the platform. Each feature has a deep-dive page in [`docs/`](./docs).
225
50
 
226
- ```typescript
227
- const ns = await client.namespaces.create({
228
- name: 'production',
229
- resource_limits: { max_workspaces: 50, max_cpus: 100 },
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
- await client.namespaces.setQuota(ns.id, {
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
- See the [Namespaces API](https://oblien.com/docs/api/namespaces) for the full reference.
242
-
243
- ---
244
-
245
- ## Edge Proxy
246
-
247
- Enterprise-only reverse proxy — route subdomains to external upstreams through the edge.
248
-
249
- ```typescript
250
- const { proxy } = await client.edgeProxy.create({
251
- name: 'staging-api',
252
- slug: 'staging-api',
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
- See the [Edge Proxy docs](https://oblien.com/docs/concepts/edge-proxy) for details.
262
-
263
- ---
264
-
265
- ## Error handling
85
+ ### Also included
266
86
 
267
- 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.
268
-
269
- ```typescript
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', // required
305
- clientSecret: 'your_client_secret', // required
306
- baseUrl: 'https://api.oblien.com', // optional, default
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 your API keys from the [dashboard](https://oblien.com/dashboard/settings).
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 type declarations shipped. All request parameters, response shapes, and event types are exported:
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
- PageCreateParams, PageData,
322
- CheckSlugParams, VerifyDomainParams,
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"}