oblien 2.4.0 → 2.6.0

package/docs/namespaces.md

@@ -6,6 +6,13 @@ Group workspaces into isolated namespaces with **resource limits**, **spending q
 const ns = client.namespaces;
 ```
 
+Account namespace counts are enforced atomically by both `create` and `ensure`:
+the owner row is locked and the count and namespace insert share a transaction.
+At the account limit a new namespace returns `409 namespace_limit_exceeded`;
+ensuring an existing namespace remains idempotent. The owner's paid or
+admin-granted Enterprise tier has no namespace-count cap. A customer namespace
+subscription cannot raise it.
+
 ## Create + resource limits
 
 ```typescript
@@ -20,7 +27,19 @@ const { data } = await ns.create({
 });
 ```
 
-Resource limits are enforced **atomically at workspace create and resource upgrade** — over-limit returns `409 NAMESPACE_LIMIT_REACHED`. `max_workspaces` is race-proof (the namespace row is locked + the count re-checked inside the insert transaction). Update them with `ns.update(id, { resource_limits })`.
+Workspace count is reserved **atomically at workspace create**; effective resource caps are checked at create, resize and start/resume/restart/wake/snapshot-resume — over-limit returns `409 NAMESPACE_LIMIT_REACHED`. `max_workspaces` is race-proof (the namespace row is locked + the count re-checked inside the insert transaction). Update them with `ns.update(id, { resource_limits })`.
+
+Declare policy directly. `null` inherits Oblien capacity; zero denies that
+allocation. VM policy integers may exceed current capacity: Oblien applies the
+strictest declared, committed paid-offer, account and platform cap. Clients do
+not calculate or copy the account's machine ceiling into customer contracts.
+Invalid numbers and unknown keys return `invalid_resource_limits`.
+
+`create`, `ensure`, `get` and `update` expose both `data.resource_limits` (saved
+policy) and `data.effective_resource_limits` (current enforced ceilings). The
+latter can change with account capacity while saved customer terms stay intact.
+These limits do not reserve host capacity or funds. Account pool usage and
+credits are checked independently at allocation time.
 
 ## Lifecycle
 
@@ -67,3 +86,53 @@ data.totals.vcpu_hours;   // cpu_time_minutes/60, gb_hours, network_gb, disk_io_
 A namespace-scoped key is pinned to its namespace: list/get/usage/webhooks all auto-filter to it, and it can't widen scope. `user_id` is always the tenant gate.
 
 **Full reference:** [Namespaces API](https://oblien.com/docs/api/namespaces)
+
+
+## Namespace credit alerts and customer recovery
+
+Oblien computes the warning state from the same quota row that enforces spending.
+Read `quota.alert` from `GET /billing/entitlement?namespace=...`, or `alert` from
+`GET /billing/balance?namespace=...`. Namespace quota rows also include `alert`.
+Its `state` is `ok`, `low`, `grace`, `depleted`, `unlimited`, or `disabled`.
+`percent` uses **included allowance + purchased top-ups**, excluding grace.
+`remaining` is paid allowance left; `balance` also includes configured grace.
+All amounts are JSON numbers in Oblien credits. Never add grace to `balance` again.
+
+Subscribe to `namespace.quota.threshold`, `credits.low`, and `credits.depleted`:
+
+- Warning percentages default to **80% and 95%** and can be configured per service.
+  `notificationThresholds: []` disables percentage warnings, not enforcement or
+  exhaustion alerts. A large usage window reports the most urgent crossed state.
+- `credits.low` reports entry into configured grace. Zero grace remains the default.
+  `credits.depleted` reports exhaustion at `balance <= 0`.
+- The usage debit, threshold marker and outgoing alert commit in **one payments
+  transaction**. Delivery retries after failures and API restarts, retaining its
+  signed body and event ID. Metering does not wait for your webhook or email server.
+- Each event identifies `data.namespace`, `data.service`, `data.transaction_id`
+  and a numeric `data.alert` snapshot. Resolve the customer from your saved namespace
+  mapping, verify the signature, and durably save the event and notification job
+  before acknowledging. Deduplicate event IDs, then re-read current entitlement;
+  an old alert may arrive after a top-up or renewal. Do not use event amounts to
+  grant credits or override the current quota.
+- Show a warning banner and a billing action. Use your server-defined top-up offer
+  to create a namespace-bound checkout after the customer chooses to buy. Payment
+  fulfillment increases purchased allowance once; your next entitlement read
+  clears the warning when funded. Workspaces stopped for billing can then be
+  restarted. A top-up does not change the plan's resource caps or grace policy.
+- Paid renewals re-arm warnings and preserve custom notification percentages.
+  A top-up or usage refund that lowers usage below a warning band re-arms that
+  band for the larger remaining budget. Mode A cycles must still be reset by
+  your backend; Mode B cycles renew after verified paid invoices.
+
+External email delivery is asynchronous and can repeat after a lost acknowledgment.
+Use a durable notification queue, honor verified recipient preferences, recheck
+organization membership before delivery, and bind billing links to the intended
+organization. Keep a read-only dashboard warning while email is unavailable.
+
+## Combined capacity (SDK 2.6.0)
+
+Set `max_total_vcpus`, `max_total_ram_mb` and `max_total_disk_gb` alongside per-VM caps. Total caps include stopped workspaces, build hosts, managed disks and pending resizes. `null` inherits, zero denies allocation. An Enterprise owner does not grant each namespace unlimited resources.
+
+`namespaces.get()` returns `data.allocated_resource_usage` with `workspaces`, `vcpus`, `ram_mb`, `disk_gb` and `pending_updates`, plus `effective_resource_limits`. These are observations, not capacity reservations. Oblien checks again atomically on create/resize. A resource update may return `pending_capacity_verification: true`; its reservation remains until the provider confirms configuration and live allocation.
+
+Use `billing.catalog().reseller.aggregateResourceLimits` to check deployed support. Credit top-ups do not change hardware capacity. Resource-limit patches preserve omitted fields atomically.

package/docs/releases/2.6.0.md

@@ -0,0 +1,16 @@
+# SDK 2.6.0
+
+This release adds typed total namespace capacity (`max_total_vcpus`,
+`max_total_ram_mb`, `max_total_disk_gb`), `allocated_resource_usage`, and the
+`billing.catalog().reseller.aggregateResourceLimits` capability. Deploy the
+matching API before depending on total capacity enforcement. Credits and
+hardware limits remain independent.
+
+Log reads and streams now accept cancellation signals. Stopping iteration
+cancels the underlying stream reader instead of leaving a connection open.
+`workloads.logs(id, workload, { tail, signal })` keeps the signal out of the URL.
+These fixes replace Openship's temporary log-cancellation package patch.
+
+The package is prepared locally as 2.6.0 and must be published before consumers
+can install it. Openship's capacity PR uses published 2.5.0 with the compatibility
+patch, so its deployment does not require this release to be published first.

package/docs/runtime.md

@@ -10,6 +10,8 @@ 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.
 
+After starting, stopping, restarting or resuming a workspace, call `workspace.runtime()` again. These lifecycle calls invalidate its cached connection; an already-held `Runtime` object is not rewritten. Use `runtime({ force: true })` when the workspace was restarted outside this client.
+
 ## Namespaces
 
 | Namespace | What it does |

package/docs/webhooks.md

@@ -40,3 +40,45 @@ await wh.delete(webhook.id);
 `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)
+
+
+## Namespace credit alerts and customer recovery
+
+Oblien computes the warning state from the same quota row that enforces spending.
+Read `quota.alert` from `GET /billing/entitlement?namespace=...`, or `alert` from
+`GET /billing/balance?namespace=...`. Namespace quota rows also include `alert`.
+Its `state` is `ok`, `low`, `grace`, `depleted`, `unlimited`, or `disabled`.
+`percent` uses **included allowance + purchased top-ups**, excluding grace.
+`remaining` is paid allowance left; `balance` also includes configured grace.
+All amounts are JSON numbers in Oblien credits. Never add grace to `balance` again.
+
+Subscribe to `namespace.quota.threshold`, `credits.low`, and `credits.depleted`:
+
+- Warning percentages default to **80% and 95%** and can be configured per service.
+  `notificationThresholds: []` disables percentage warnings, not enforcement or
+  exhaustion alerts. A large usage window reports the most urgent crossed state.
+- `credits.low` reports entry into configured grace. Zero grace remains the default.
+  `credits.depleted` reports exhaustion at `balance <= 0`.
+- The usage debit, threshold marker and outgoing alert commit in **one payments
+  transaction**. Delivery retries after failures and API restarts, retaining its
+  signed body and event ID. Metering does not wait for your webhook or email server.
+- Each event identifies `data.namespace`, `data.service`, `data.transaction_id`
+  and a numeric `data.alert` snapshot. Resolve the customer from your saved namespace
+  mapping, verify the signature, and durably save the event and notification job
+  before acknowledging. Deduplicate event IDs, then re-read current entitlement;
+  an old alert may arrive after a top-up or renewal. Do not use event amounts to
+  grant credits or override the current quota.
+- Show a warning banner and a billing action. Use your server-defined top-up offer
+  to create a namespace-bound checkout after the customer chooses to buy. Payment
+  fulfillment increases purchased allowance once; your next entitlement read
+  clears the warning when funded. Workspaces stopped for billing can then be
+  restarted. A top-up does not change the plan's resource caps or grace policy.
+- Paid renewals re-arm warnings and preserve custom notification percentages.
+  A top-up or usage refund that lowers usage below a warning band re-arms that
+  band for the larger remaining budget. Mode A cycles must still be reset by
+  your backend; Mode B cycles renew after verified paid invoices.
+
+External email delivery is asynchronous and can repeat after a lost acknowledgment.
+Use a durable notification queue, honor verified recipient preferences, recheck
+organization membership before delivery, and bind billing links to the intended
+organization. Keep a read-only dashboard warning while email is unavailable.

package/docs/workspaces.md

@@ -38,7 +38,7 @@ 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)**.
+Creating in a namespace enforces that namespace's **resource limits** (max workspaces, per-workspace and total 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

package/package.json

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