oblien 2.3.2 → 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

@@ -29,6 +29,12 @@ 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/package.json

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