oblien 2.3.0 → 2.4.0

package/docs/on-demand.md

@@ -0,0 +1,43 @@
+# Sleep and wake on request
+
+Automatic sleep is opt-in for permanent workspaces with memory snapshot support. It covers every exposed HTTP port URL and connected custom domain for that workspace.
+
+```ts
+import Oblien from 'oblien';
+
+const client = new Oblien({
+  clientId: process.env.OBLIEN_CLIENT_ID,
+  clientSecret: process.env.OBLIEN_CLIENT_SECRET,
+});
+const ws = client.workspace('YOUR_WORKSPACE_ID');
+
+// Start your app on 0.0.0.0:3000, then publish it.
+const port = await ws.publicAccess.expose({ port: 3000 });
+await ws.lifecycle.setIdle({ suspend_after: '15m' });
+console.log(port);
+
+// Read the policy/capability or disable automatic sleep.
+console.log(await ws.lifecycle.get());
+await ws.lifecycle.setIdle(null);
+```
+
+Creation accepts the same policy under `config.idle`:
+
+```ts
+const workspace = await client.workspaces.create({
+  image: 'oblien/node:24', mode: 'permanent',
+  config: { idle: { suspend_after: '15m' } },
+});
+```
+
+`suspend_after` accepts seconds or a duration string, with a minimum of 120 seconds. The default `stop_after: 0` keeps saved RAM until wake. An optional retention time of at least one hour discards saved RAM after that long asleep; files remain, but the next wake cold-boots. For example `{ suspend_after: '15m', stop_after: '72h' }` requires an app that starts at boot.
+
+The API coalesces concurrent wake/restore attempts across workers, ports and aliases. The edge waits for the requested application port and forwards each request after readiness. If startup exceeds its wait budget, it returns 503 with `Retry-After: 1`; wake continues. Retry with a deadline/backoff and use application idempotency keys for writes.
+
+Requests and streams through the HTTP edge keep the workspace awake. For background jobs, direct TCP, SSH or runtime work, call `ws.lifecycle.ping()` periodically within the idle timeout or disable automatic sleep. External connections can expire during hibernation and need application-level reconnection.
+
+While this policy is enabled, an existing public route can wake a stopped workspace too. `ws.lifecycle.setIdle(null)` disables automatic sleep and public wake; explicit Restore/Resume remains available. Revoke public ports/disconnect domains to remove public access entirely. Nested KVM workspaces currently reject automatic sleep because Firecracker cannot preserve their nested VM state.
+
+CLI: `oblien lifecycle idle WORKSPACE_ID --after 15m`, optionally `--stop-after 72h`; disable with `--disable`.
+
+See [the hosted guide](https://oblien.com/docs/workspace/on-demand) for dashboard setup and operational details.

package/docs/workspace-limit-report.md

@@ -0,0 +1,40 @@
+# Openship workspace-limit HTTP status report
+
+Reported 2026-09-17. Openship already rejects this response safely; it is not an
+independent release blocker for Openship.
+
+Some API deployments returned HTTP 200 when workspace creation failed:
+
+```json
+{
+  "success": false,
+  "error": "SANDBOX_LIMIT_REACHED",
+  "code": "SANDBOX_LIMIT_REACHED",
+  "message": "Workspace count limit reached.",
+  "current": 3,
+  "max": 3
+}
+```
+
+Expected behavior is HTTP 409 with the failure code and quota details. The API now
+maps workspace, namespace, and owned-pool limits to 409. A namespace admission
+failure also now sets `success: false`, so the response cannot take the success path.
+
+The SDK patch retains compatibility with legacy HTTP 200 failure envelopes, maps
+these limit codes to `ConflictError`, and preserves the actual response status.
+It also rejects non-2xx JSON responses that omit `success: false`. Creation failures
+do not enter readiness polling or issue a second create request.
+
+Verification: `npm test` passes all 19 SDK tests, including
+`tests/http-errors.test.mjs` for legacy 200, current 409, uppercase error-only codes,
+403/500 JSON responses, and successful asynchronous creation.
+
+The 2026-09-17 live account/namespace billing canary also verified that a second
+workspace in a namespace capped at one workspace returns HTTP 409 with
+`NAMESPACE_LIMIT_REACHED`, through the SDK. See the API repository's
+`docs/ACCOUNT_WORKSPACE_BILLING_FIX_20260917.md` for that run and the broader
+190-check API regression suite.
+
+This report and patch are recorded in the SDK repository for maintainers. No external
+issue or team message has been sent from this environment. The public npm version
+checked during this work is 2.3.0; these SDK changes require the next SDK release.

package/docs/workspaces.md

@@ -1,5 +1,18 @@
 # Workspaces
 
+`create()` waits for the workspace's default runtime. To return its ID immediately:
+
+```ts
+const pending = await client.workspaces.create({
+  image: 'oblien/ubuntu:24.04',
+  wait_ready: false,
+  idempotency_key: 'my-create-request',
+});
+const ready = await client.workspaces.waitUntilReady(pending.id, { timeoutMs: 300_000 });
+```
+
+Read `workspace.provisioning` for progress and failure details, and `workspace.ready` for readiness. `waitUntilReady` supports `signal`; a timeout or abort stops waiting while creation continues. Errors include `details.workspace_id`. Reuse the same `idempotency_key` if a create response is lost. Failed creation can be retried with `retryCreation(id)` or deleted with `delete(id)`. A deletion accepted with `accepted: true` completes in the background.
+
 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)**.
@@ -27,6 +40,12 @@ 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)**.
 
+Workspace count, namespace, and owned resource pool limits return HTTP 409 with
+`SANDBOX_LIMIT_REACHED`, `NAMESPACE_LIMIT_REACHED`, or `POOL_LIMIT_REACHED`. The SDK
+throws `ConflictError` for these codes, including older API responses that incorrectly
+used HTTP 200 with `success: false`. It preserves the actual HTTP status in
+`error.status` and rejects before polling for readiness.
+
 ## Power
 
 ```typescript
@@ -37,6 +56,15 @@ await ws.pause(id);    // freeze to disk
 await ws.resume(id);   // thaw
 ```
 
+During billing or manual namespace suspension, scoped credentials can still inspect,
+stop, and delete their own workspaces. Create, start, restart, resume, and other
+mutations return `403 namespace_suspended`. Funding can restore a billing suspension;
+manual suspension requires explicit namespace activation. Restoration leaves
+workspaces stopped until the customer starts them.
+
+Stop is safe to retry when automatic exhaustion or an earlier request has already
+stopped the VM. The API returns success only after the VM node confirms that state.
+
 ## Scoped handle
 
 Bind to one workspace so you never pass the ID again:
@@ -79,4 +107,6 @@ Accessed as namespaces on `client.workspaces`:
 | `logs` | Boot and command logs |
 | `images` | Available base images |
 
+Native macOS SSH uses public-key authentication and the `oblien` login account. Save a public key with `client.workspaces.ssh.setKey(id, { public_key })`, then call `client.workspaces.ssh.enable(id)`. SSH status includes `auth_methods` and the SSH/SCP connection commands. Public SSH can be disabled without affecting the Mac runtime or its private boot connection.
+
 **Full reference:** [API docs](https://oblien.com/docs/api/workspaces)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oblien",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Official TypeScript SDK for the Oblien Workspace API",
   "type": "module",
   "main": "./dist/index.js",