oblien 2.7.0 → 2.8.0

package/docs/billing.md

@@ -1,5 +1,96 @@
 # Namespace billing
 
+## PAYG and prepaid monthly capacity
+
+Compute has two modes, `payg` and `monthly`. Stripe and wallet funds are payment
+sources. Both modes share the namespace contract, resource enforcement, usage
+ledger and signed billing events. Direct capacity purchases are available to
+the account owner; hosting a customer checkout through reseller `offer` still
+requires an Enterprise owner.
+
+```typescript
+const catalog = await client.billing.capacityCatalog();
+const selected = catalog.presets.find(p => p.id === 'small')!;
+const { quote } = await client.billing.previewCapacity(namespace, {
+  capacity: selected.capacity,
+  billingMode: 'monthly', paymentSource: 'wallet', autoRenew: false,
+  idempotencyKey: savedOrder.previewKey,
+});
+// Review backend-calculated amounts and effectiveAt before confirming.
+await client.billing.confirmCapacity(namespace, {
+  quoteId: quote.id, idempotencyKey: savedOrder.confirmKey,
+});
+const { capacity, catalog: savedPrices } = await client.billing.capacity(namespace);
+```
+
+Existing subscriptions retain their saved model after an SDK upgrade. Read `capacity(namespace)` first; a null capacity means this namespace has not adopted the capacity contract. An existing hosted reseller subscription uses plan changes to adopt monthly capacity at renewal. A quota edit cannot perform that conversion.
+
+For PAYG use `billingMode: 'payg'` and `paymentSource: 'wallet'`. For recurring
+card payment use `paymentSource: 'stripe'` and confirm the saved quote with
+`capacityCheckout` instead. Native Stripe Checkout is the default, with the
+existing optional `allowPromotionCodes` and `checkoutMode` controls. Returning
+from checkout never proves payment: inspect committed coverage and signed events.
+
+Quotes use USD **cents**; savings use USD **dollars**. Rates and presets come from
+the backend, and existing contracts return their saved-tariff catalog. Only
+eligible verified paid wallet funds can buy monthly coverage. Namespace
+allowances and promotional grants are not money. Read `computeCovered` and
+`periodEnd`: a prepaid month has no additional compute-credit ceiling, and a
+zero wallet cannot remove that paid compute coverage. The manual namespace
+suspension and purchased resource pool still apply.
+
+Wallet monthly renewal is opt-in through
+`setCapacityAutoRenew(namespace, { autoRenew, idempotencyKey })`. Wallet changes
+use the same preview and confirm methods; pending reductions can be canceled
+with `cancelCapacityChange(namespace, { quoteId, idempotencyKey })`. Hosted
+subscription changes use `previewPlanChange` / `changePlan`, and renewal uses
+`cancelSubscription` / `resumeSubscription`. Do not start a competing checkout
+for an existing live subscription. Upgrades charge the prorated difference and
+preserve usage/top-ups; reductions wait for the next period. Failed payment
+retains the prior plan.
+
+Use `previewCapacity` with `billingMode: 'payg'` and `paymentSource: 'wallet'`
+to switch a hosted monthly pool to PAYG. Confirming schedules cancellation of
+the old subscription at its paid-through date. The PAYG period starts only
+after Stripe confirms the old subscription has ended. Cancel the pending
+switch with `cancelCapacityChange` before the boundary to restore renewal.
+An active wallet period keeps wallet payment for pool or mode changes; fund
+that wallet by card if needed.
+
+`billing.capacity(namespace).pendingCheckout` exposes the existing checkout URL
+and quote ID after a lost response or reload. Resume that URL or cancel with
+`cancelCapacityChange`; do not open a competing checkout.
+
+At expiry compute stops, and the initial tariff retains disks for at least
+30 days without automatic deletion. Provisioned storage is charged until
+deleted. `capacity.retention.amountDue` and `storagePerGiBMonth` are USD dollars;
+`quote.retainedStorageAmountDue` is USD cents, separate from compute pricing.
+Fund the wallet to settle storage arrears before restarting. A confirmed late
+renewal reverses storage charges for any time it covers.
+
+Managed proxy transfer is separate in both modes. Quote a transfer pack with
+`previewNetworkTopup(namespace, { unitAmount, idempotencyKey })`, then redeem it
+through `confirmCapacity`. The pack uses eligible wallet funds and grants the
+returned `networkBytes`; unused bytes carry forward. Compute remains covered
+when its paid period is active even if the transfer allowance runs out.
+
+`capacity.savings.monthlyDifference` includes the prepaid fee and may be negative
+for an idle pool. `billing.savings({ namespace, month: '2026-10' })` returns a
+ledger comparison for a UTC month; `monthlyCoveredUsage` excludes subscription
+fees and is not cash savings. Respect `complete: false` for incomplete historical
+breakdowns. Do not manufacture dollar conversions or savings locally.
+
+Owner-only billing events include `capacity.changed`, `capacity.renewed`,
+`capacity.expired`, `capacity.payment_required`, `capacity.revoked`,
+`network.topup_applied`, `network.allowance.low`, `network.allowance.depleted`,
+`storage.retention.payment_required` and `storage.retention.paid`.
+They use the same signature, event-ID deduplication and namespace checks as the
+existing subscription events. Keep all billing credentials on the server.
+
+Full terms and routes: https://oblien.com/docs/concepts/compute-billing.
+
+## Existing metered subscriptions
+
 Namespace management is available from `oblien@2.3.0`; reseller checkout and
 status reads from `2.4.0`. The `2.5.0` source adds typed offer policy/resource
 caps and exported reseller types, with the matching API deployment.
@@ -67,7 +158,7 @@ an unapproved host returns `billing_redirect_not_allowed`. Supplied URLs require
 to the first namespace checkout, without copying the API-key owner's details.
 Reuse an idempotency key only when retrying the identical request.
 
-Paid subscriptions provision the namespace and set its quota. Renewals reset usage
+Paid metered subscriptions provision the namespace and set its quota. Renewals reset usage
 once per cycle; purchased top-ups increase the ceiling and carry only their unused remainder into renewal.
 Top-ups, renewals, and funded policy changes clear suspensions caused by billing;
 manual suspensions stay in place. Workspaces can then be started explicitly.
@@ -131,7 +222,9 @@ is uncapped. `overdraft` must not exceed `suspendThreshold` when both are set.
 
 ## Access and reconciliation
 
-`entitlement()` returns `active`, `past_due`, `credit_exhausted`, or `canceled`.
+`entitlement()` preserves `active`, `past_due`, `credit_exhausted`, and `canceled` across both contracts. Capacity responses include `tierId: 'capacity'`, `billingMode`, `computeCovered` and `capacity`. Their compatibility quota has null limit/balance and no alert. Read the returned `balance().blocking`, coverage and resource pool; do not infer an unlimited physical pool or a finite compute allowance from that quota. Monthly coverage survives an empty owner wallet, while manual suspension and resource admission remain enforced.
+
+The following allowance/tier behavior applies to existing metered subscriptions.
 
 The paid tier and period belong to that namespace's subscription. An account or
 sibling namespace subscription cannot supply them. A namespace that has never
@@ -156,6 +249,8 @@ Billing events use a durable outbox with retry. Reconcile with `entitlement()` a
 
 `POST /billing/checkout` also accepts a server-defined `offer` instead of a catalog `planTierId` or `packId`. Keep this request behind your authenticated backend and resolve the customer's namespace from your own database.
 
+Choose the offer type explicitly. The example below is a **metered credit offer**. Monthly capacity uses `billingMode: 'monthly'`, `capacity: { vcpus, memoryMb, diskGb, workspaces }`, `credits: 0`, and no `policy`. It requires a monthly subscription, a retail price covering the saved provider cost, and successful physical admission. See [the monthly reseller example](https://oblien.com/docs/saas-reselling#monthly-capacity-offer).
+
 ```json
 {
   "namespace": "tenant-a",
@@ -188,9 +283,12 @@ This charges **$10**, funds the **owner's Oblien wallet** at the standard rate (
 | `offer.description` | Optional customer-facing text, at most 500 characters |
 | `offer.unitAmount` | Required integer USD cents, 100–1,000,000 ($1–$10,000) |
 | `offer.currency` | `usd` only; defaults to `usd` |
-| `offer.credits` | Required integer namespace allowance, 1–1,000,000,000; independent of wallet funding |
-| `offer.policy` | Subscription only: optional `overdraft`, `suspendThreshold`, `onOverdraftAction`; defaults to zero grace and `stop_workspaces` |
-| `offer.resourceLimits` | Subscription only: nonempty subset of `max_workspaces`, `max_vcpus`, `max_ram_mb`, `max_disk_gb`; values are integers 0–1,000,000,000 or `null` |
+| `offer.billingMode` | `monthly` purchases capacity; omit for a metered allowance. The historical `payg` offer value also selects that allowance product; new capped PAYG uses `previewCapacity`. |
+| `offer.capacity` | Monthly only: required shared `vcpus`, `memoryMb`, `diskGb`, `workspaces`. |
+| `offer.tariffId` | Monthly only: optional published tariff ID; saved terms are preserved by default. |
+| `offer.credits` | Metered: integer 1–1,000,000,000. Monthly: `0` (the API also defaults an omitted value to zero). |
+| `offer.policy` | Metered subscription only: optional `overdraft`, `suspendThreshold`, `onOverdraftAction`. Rejected for monthly capacity. |
+| `offer.resourceLimits` | Subscription only: nonempty subset of `max_workspaces`, `max_vcpus`, `max_ram_mb`, `max_disk_gb`, `max_total_vcpus`, `max_total_ram_mb`, `max_total_disk_gb`; integer values 0–1,000,000,000 or `null`. These can further restrict a paid pool. |
 | `metadata` | Optional, only with `offer`: at most 35 string entries; key `[A-Za-z0-9_]`, length 1–40; value at most 500 characters without control characters |
 | `idempotencyKey` | Required with `offer`, nonempty string up to 200 characters; reuse only for an identical request |
 
@@ -206,7 +304,7 @@ Check `billing.catalog().reseller` before enabling offers with policy or limits:
 capability. SDK 2.4.0 already transports reseller offers; the 2.5.0 source adds
 these TypeScript fields and public reseller type exports.
 
-Grace is zero by default. To permit 60 extra namespace credits, save
+For metered offers, grace is zero by default. To permit 60 extra namespace credits, save
 `policy: { overdraft: 60, suspendThreshold: 60, onOverdraftAction: 'stop_workspaces' }`
 on the subscription offer. `suspendThreshold` must be at least `overdraft`.
 `quota.balance` already includes grace (`limit + overdraft - used`); never add it
@@ -222,7 +320,7 @@ refund of the current cycle removes its remaining allowance and grace; an old
 invoice refund cannot erase a newer cycle.
 
 `max_workspaces` counts allocated workspaces in this namespace. CPU, RAM and disk
-are per-workspace caps. Oblien resolves the strictest cap from the saved offer,
+are per-workspace caps. The three `max_total_*` fields additionally bound combined allocated resources, including stopped workspaces and pending changes. Oblien resolves the strictest cap from the saved offer,
 configured namespace policy, owner account and platform. `null` inherits capacity;
 it never removes another layer's restriction. Clients submit policy directly
 without fetching account quota or calculating capacity. Namespace detail and
@@ -282,6 +380,8 @@ Requires an `admin` or `billing` credential. Looks up both owner and namespace b
 
 `fulfilled` means initial processing finished; always inspect the net credit fields and `fulfillmentStatus` for `partially_refunded`, `refunded` or `disputed`. Use `GET /billing/entitlement` and `/billing/balance` for current access. The lookup describes the checkout's initial payment, not its later renewal invoices. Reseller subscriptions also expose `offer` and `metadata` through `GET /billing/subscription`; their `tierId` is `reseller` and does not upgrade owner capacity.
 
+Monthly checkout results expose gross `walletCreditsFunded`, `capacityCreditsCharged` and signed `walletCreditDelta`, with zero `namespaceCreditsGranted`. Gross funding is not the spendable remainder; read committed capacity coverage instead of granting credits again.
+
 Custom `payment.succeeded`, `subscription.renewed` and `entitlement.changed` events include `orgRef`, `namespace`, `kind`, `checkoutId`, `paymentId`, saved `offer`, application `metadata`, `amount: { unitAmount, currency }`, net `walletCredits` and `namespaceCredits`. Fulfillment uses stable receipt-based event IDs. Verify the raw-body HMAC, deduplicate by event ID, then re-read entitlement to handle reordering. Financial billing events are committed to a durable outbox with retries. Keep reconciliation polling to handle delayed or exhausted delivery and event reordering.
 
 ### Useful checkout and portal errors
@@ -385,9 +485,11 @@ Errors use `{ success:false, code, message, requestId }`, with safe diagnostic d
 
 ## Reseller subscription plan changes
 
+The same methods also change hosted monthly capacity. Monthly offers use zero compute credits and no credit policy. The provider reserves the new pool and applies an immediate upgrade only after confirmed funding. Resource reductions and billing-mode changes wait for renewal, even when retail price increases. The quote's direction and effective date are authoritative. The prorated credit-increase formula below applies to metered offers. Direct owner capacity subscriptions use these methods without requiring reseller Enterprise eligibility.
+
 
 These endpoints change an **existing reseller offer**, without creating a second
-subscription or changing the owner's account plan. New quotes and acceptance require
+subscription or changing the owner's account plan. New reseller quotes and acceptance require
 an Enterprise owner and a server API key with `billing` or `admin` scope. Read and
 cancel operations remain available if reseller eligibility later ends. End-user
 namespace/workspace tokens cannot call billing APIs. Your backend must derive the

package/docs/desktop.md

@@ -1,115 +1,104 @@
-# Remote desktop
+# Remote desktop sessions
 
-Desktop is an image capability. The same API works for Mac and Linux desktop
-providers. Access defaults off and changes without reboot. Disabling it closes
-desktop sessions and preserves terminal/SSH/workloads. The saved choice survives
-workspace restart.
+Desktop is an image capability. Linux virtual-display providers support named,
+saved desktops with independent applications, profiles and resolutions. The
+current macOS provider exposes one console connection, which can be renamed,
+deleted and added again. Discover the
+capabilities rather than branching on image names.
 
 ```ts
-const runtime = await client.workspaces.runtime(workspaceId);
-if ((await runtime.desktop.status()).supported) {
+const vm = client.workspace(workspaceId);
+const installation = await vm.desktop.installation();
+if (installation.choices?.length && !installation.installed) {
+  await vm.desktop.install({ desktop: installation.choices[0].id, restart: true });
+  // Poll installation() until ready. Adding software can restart the workspace.
+}
+const runtime = await vm.runtime();
+const { sessions, capabilities } = await vm.desktop.listSessions();
+if (capabilities.can_create) {
+  const { session } = await vm.desktop.createSession({
+    name: 'Development',
+    resolution: { width: 1920, height: 1080 },
+    idempotency_key: 'development-desktop',
+  });
+  // Poll vm.desktop.getSession(session.id) until session.available is true.
   await runtime.desktop.enable();
-  const viewerUrl = runtime.desktop.url(); // Credential-bearing URL: keep private.
-  const tunnel = await runtime.desktop.tunnel({ port: 5901 }); // Node.js only
-  // Connect a VNC client to tunnel.url (vnc://127.0.0.1:5901).
-  await tunnel.close();
-  await runtime.desktop.disable();
+  const privateViewer = runtime.desktop.url({ sessionId: session.id });
+  const tunnel = await runtime.desktop.tunnel({ sessionId: session.id, port: 5901 });
+  // Connect a native VNC app to tunnel.url. Node.js only.
+  await tunnel.close(); // Leaves desktop applications running.
 }
 ```
 
-Status includes `supported`, `enabled`, `available`, `credentials` and
-`transports`. If `credentials` is true, `runtime.desktop.credentials()` returns
-the image's OS account. For Mac this is `oblien` with its per-workspace password,
-also used by SSH. The method requires enabled desktop access.
-
-Creation accepts `config.desktop: { enabled: true }`. Live changes use these
-methods without changing CPU, RAM or boot settings. `forTarget()` changes command
-and file targets, while desktop continues to address the workspace image.
-
-## Add desktop
+`listSessions`, `createSession`, `getSession`, `updateSession`, `startSession`,
+`stopSession` and `deleteSession` are available on both `vm.desktop` and
+`runtime.desktop`. The first uses the control API with normal workspace audit
+and scope checks; the second calls the authenticated runtime directly. Desktop
+routing remains on the image gateway, independent of `runtime.forTarget()`.
+
+The default limit is 10 saved desktops, including stopped ones. Each running
+desktop uses the workspace's CPU/RAM; software packages remain shared read-only.
+Resolution is required for virtual desktops at creation, between 640×480 and
+3840×2160. Change a running or stopped Linux desktop's screen size with `updateSession(id, { resolution: { width, height } })`.
+Live resizing keeps applications open. Check `session.can_resize`; OS consoles
+without this capability use their native display settings. Names can change while running. Reuse the same `idempotency_key` and request body
+on creation retries. Responses contain `{success: true, session}`; poll while
+`state` is `starting`, `stopping` or `deleting`. Other states: `running`, `stopped`, `failed`.
+
+Disconnecting preserves running applications. **Stop** ends that desktop's apps
+and keeps its profile. **Start** opens it again. **Delete** automatically stops a running virtual desktop and removes its profile,
+including files saved there. It returns once deletion is accepted; poll the
+session list until it disappears. A main OS console has no private profile: Delete
+removes its saved connection and disconnects viewers, preserving OS apps and files.
+Add it again with `createSession({name: "Main desktop"})`, omitting resolution. Other desktops and
+shared workspace files remain. A workspace cold boot restarts previously running
+desktops with their profiles; it does not restore open app RAM. Use the existing
+supported Linux VM memory snapshot/restore for that.
+
+Sessions are not separate security boundaries. Workspace runtime permission
+authorizes all of its desktops and files. Use separate workspaces for tenants.
+Runtime access and desktop access must be enabled to connect. Desktop disable
+closes all display connections, leaving apps, terminals and workloads running.
+Token rotation or runtime disable revokes display streams as well.
 
-Ubuntu 24.04/26.04 and Debian 13 offer prepared Cinnamon layers. Discover choices
-from the owned workspace, then add the selected desktop:
+## Native SSH/VNC apps
 
 ```ts
-const desktop = client.workspace(workspaceId).desktop;
-const installation = await desktop.installation();
-if (installation.choices?.length) {
-  await desktop.install({ desktop: installation.choices[0].id, restart: true });
-}
+const connection = await vm.desktop.sshConnection({ session_id: desktopId });
+// Keep connection.ssh.password secret. It is bound to this desktop.
 ```
 
-`restart: true` explicitly permits restarting a running workspace. Stopped
-workspaces stay stopped. Poll `installation()` while `phase === 'installing'`;
-`stage` describes progress. Completion is `ready`, or `stopped` with
-`installed: true`. Failures include `error`; retry after fixing the cause.
-An explicit Stop cancels the preparer's deferred restart.
+Use the returned SSH host (`ssh.oblien.com`), username, temporary password and
+host fingerprint in a VNC app with SSH tunneling. Its virtual VNC destination is
+`127.0.0.1:5900`, with no additional VNC authentication. The ticket grants no SSH
+shell, SFTP, arbitrary forwarding or access to another display. Owner tickets
+expire after eight hours; delegated tickets can expire sooner and follow sharing
+revocation. Consult `expires_at`. Stop/deletion closes that session's streams.
 
-After preparation, obtain the current connection with
-`await client.workspace(workspaceId).runtime()`. Recreate any Runtime object or
-stream held across the restart, as with an ordinary workspace restart.
-
-Prepared programs are shared read-only with private profiles and writes. There
-are no per-workspace downloads, public desktop disk IDs or extra image names.
-Creation with `config.desktop.enabled: true` attaches before first boot and
-honors normal `wait_ready`. Compatible custom/application images without a
-prepared choice still support `install()` using the download-based recipe.
-
-Use `client.disks.listSoftware({ workspace_id: workspaceId })` to browse software
-compatible with a workspace's base OS. Desktop artifacts remain internal.
+Browser and CLI tunnels use HTTPS/WSS on `workspace.oblien.com:443`. No public raw
+VNC port is opened. Viewer URLs contain a credential in a fragment; do not log
+or share them. Direct private runtime URLs also need the HTTP query credential
+to load their authenticated viewer. OS login, where required, is separate;
+`runtime.desktop.credentials()` is available only when the provider supplies it.
 
 ## CLI
 
-The desktop-enabled 2.3.2 build is an official downloadable package:
+Use the SDK/CLI build containing desktop session support:
 
 ```sh
-npm install -g https://oblien.com/downloads/oblien-2.3.2.tgz
 oblien login
-oblien desktop status WORKSPACE_ID
+oblien desktop list WORKSPACE_ID
+oblien desktop create WORKSPACE_ID --name Development --resolution 1920x1080
 oblien desktop enable WORKSPACE_ID
-oblien desktop vnc WORKSPACE_ID --port 5901
-```
-
-Keep the command running and open `vnc://127.0.0.1:5901` in a VNC client.
-`oblien desktop credentials WORKSPACE_ID` retrieves the optional OS login account.
-Ctrl+C closes the local tunnel. `oblien desktop disable WORKSPACE_ID` disconnects
-all desktop clients for that workspace.
-
-Browser and native VNC traffic use the same authenticated WSS gateway route.
-The Node tunnel sends its credential in an Authorization header, binds only to
-local loopback and applies stream backpressure. No public raw VNC port is needed.
-Token rotation or Runtime API disable revokes these connections too; obtain a
-fresh runtime credential to reconnect. The package is downloadable independently
-of npm registry publication.
-
-## Native SSH/VNC apps
-
-Enable desktop access, then issue an eight-hour desktop-only connection:
-
-```ts
-const connection = await client.workspaces.desktop.sshConnection(workspaceId);
-// Or: await client.workspace(workspaceId).desktop.sshConnection();
-// Treat connection.ssh.password as a secret; do not log it.
+oblien desktop vnc WORKSPACE_ID --session DESKTOP_ID --port 5901
+oblien desktop ssh WORKSPACE_ID --session DESKTOP_ID
+oblien desktop update WORKSPACE_ID DESKTOP_ID --resolution 1600x900
+oblien desktop stop WORKSPACE_ID DESKTOP_ID
+oblien desktop start WORKSPACE_ID DESKTOP_ID
+oblien desktop delete WORKSPACE_ID DESKTOP_ID
 ```
 
-```sh
-oblien desktop ssh WORKSPACE_ID
-```
-
-The response contains `ssh: { host, port, username, password, host_key_fingerprint }`,
-`vnc: { host, port, authentication }` and `expires_at`. In a VNC app with built-in
-SSH tunneling, use the supplied SSH settings and the VNC destination
-`127.0.0.1:5900`. SSH password authentication grants access only to this desktop,
-with no shell or arbitrary forwarding. Verify the host fingerprint on first use.
-No local CLI relay or enabled guest SSH service is required for this path.
-
-Expiry closes active connections. Desktop disable rejects access while disabled;
-re-enable permits unexpired credentials again. Runtime token rotation permanently
-revokes previous desktop credentials. Issuing another connection does not revoke
-older ones. The OS login, if required, uses separate account credentials.
-
-Browser/CLI WSS stays on `workspace.oblien.com` port 443, and managed SSH uses
-`ssh.oblien.com` port 22. Both reach the same private runtime desktop endpoint.
-There is no public raw VNC port. See the
-[native connection guide](https://oblien.com/docs/workspace/desktop#mobile-and-remote-devices)
-for client settings, expiry, security and clipboard limitations.
+Keep the `vnc` command running; Ctrl+C closes its local tunnel. The normal `install`,
+`installation`, `status`, `enable`, `disable` and `credentials` commands remain.
+REST session routes work independently of SDK publication; see the
+[public desktop guide](https://oblien.com/docs/workspace/desktop#saved-desktops).

package/docs/namespaces.md

@@ -2,6 +2,8 @@
 
 Group workspaces into isolated namespaces with **resource limits**, **spending quotas**, lifecycle controls, and **per-namespace usage** — the building block for multi-tenant setups (one namespace per customer/team).
 
+Current compute uses a [capped PAYG or prepaid monthly contract](./billing.md#payg-and-prepaid-monthly-capacity). A paid monthly pool has no second finite compute-credit allowance. Existing credit contracts retain their quota rules; resource policy edits alone do not purchase or migrate coverage. Omitting a workspace namespace creates a personal account workspace with `namespace: null`; the literal `default` is a separate named namespace.
+
 ```typescript
 const ns = client.namespaces;
 ```
@@ -20,7 +22,7 @@ const { data } = await ns.create({
   name: 'production',
   resource_limits: {
     max_workspaces: 50,
-    max_vcpus: 16,      // per-workspace cap
+    max_vcpus: 12,      // per-workspace platform maximum
     max_ram_mb: 32768,
     max_disk_gb: 100,
   },
@@ -38,8 +40,9 @@ 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.
+These policy limits do not reserve host capacity or funds. Account capacity and
+the namespace's applicable billing contract are checked at allocation time.
+Monthly coverage comes from the separate verified capacity purchase.
 
 ## Lifecycle
 
@@ -52,16 +55,17 @@ const { namespaces } = await ns.list();
 
 ## Quotas (optional)
 
-Spending limits per service, with overdraft + threshold webhooks. Skip these if you bill externally (use **usage units** below instead).
+Spending limits for credit-metered services, with overdraft and threshold webhooks. This Mode A example applies when your backend owns a metered allowance cycle. Hosted subscriptions reconcile their own paid cycles. Monthly compute uses paid capacity coverage instead of these finite compute quotas.
 
 ```typescript
 await ns.setQuota({
-  namespace: 'production', service: 'sandbox',
+  namespace: 'production', service: 'workspace_vm',
   quotaLimit: 500, overdraft: 50,
   onOverdraftAction: 'stop_workspaces',
   notificationThresholds: [80, 95],   // fires namespace.quota.threshold webhooks
 });
-await ns.resetQuota({ namespace: 'production', service: 'sandbox' });
+// After external payment, reuse the same cycle end on retry.
+await client.billing.resetQuota('production', { periodEnd: '2026-11-01T00:00:00Z' });
 await ns.listWithQuotas();
 ```
 
@@ -90,6 +94,8 @@ A namespace-scoped key is pinned to its namespace: list/get/usage/webhooks all a
 
 ## Namespace credit alerts and customer recovery
 
+Use these alerts for metered allowances. For monthly capacity, read coverage, transfer and retained-storage state with `billing.capacity(namespace)` and the [capacity events](./billing.md#payg-and-prepaid-monthly-capacity). A transfer warning alone does not revoke paid compute.
+
 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`.

package/docs/releases/2.8.0.md

@@ -0,0 +1,19 @@
+# SDK 2.8.0
+
+Adds typed capped PAYG and prepaid monthly capacity APIs, wallet redemption,
+Stripe checkout, renewal preferences, pending checkout recovery, capacity
+changes and managed proxy transfer packs. Both compute modes use the backend's
+saved tariff, namespace contract and existing billing events.
+
+Responses distinguish paid compute coverage, retained-storage balances,
+resource limits, purchased transfer and recorded cap savings. Quote amounts
+are cents; savings and retention balances are dollars. Storage and transfer
+events use the existing signed webhook contract.
+
+Requires the matching capacity API and compatible VM nodes. Read
+`billing.capacityCatalog()` before enabling sales, and use saved idempotency
+keys for every confirmation. Existing namespace, workspace and reseller
+methods remain compatible. See [billing](../billing.md) for the full flow.
+
+This release is prepared for the repository owner to publish. It has not been
+published automatically.

package/docs/webhooks.md

@@ -14,6 +14,8 @@ const { events } = await wh.events();
 
 Includes: `vm.stopped`, `vm.archived`, `workload.started|exited|failed|stopped|restart_loop`, `credits.usage`, `credits.low`, `credits.depleted`, `namespace.quota.threshold`.
 
+Compute billing also publishes `capacity.changed`, `capacity.renewed`, `capacity.expired`, `capacity.payment_required`, `capacity.revoked`, `network.topup_applied`, `network.allowance.low`, `network.allowance.depleted`, `storage.retention.payment_required` and `storage.retention.paid`. These use durable signed billing delivery. Reconcile current coverage, transfer and storage with `billing.capacity(namespace)` after deduplicating the event ID.
+
 ## Create (namespace-scoped or account-wide)
 
 ```typescript
@@ -25,7 +27,7 @@ const { webhook } = await wh.create({
 });
 ```
 
-A namespace-bound webhook receives only events that carry that namespace; account-wide webhooks receive everything. Namespace-scoped API keys are auto-pinned to their namespace.
+A namespace-bound webhook receives only events that carry that namespace; account-wide webhooks receive their owner's authorized events. Register billing, credit, capacity, transfer and retained-storage hooks with an owner `admin` credential. Namespace-scoped keys can manage authorized operational hooks in their own namespace, but cannot manage billing webhook configurations.
 
 ## Manage
 
@@ -44,6 +46,8 @@ await wh.delete(webhook.id);
 
 ## Namespace credit alerts and customer recovery
 
+These describe metered allowances. Monthly capacity has no additional compute-credit budget to exhaust; use the capacity, transfer and retained-storage events above. Read the API's `blocking` value rather than deriving access from a numeric credit balance.
+
 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`.

package/package.json

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