oblien 2.7.1 → 2.8.1

package/docs/billing.md

@@ -1,4 +1,149 @@
-# Namespace billing
+# Compute and namespace billing
+
+## PAYG and prepaid monthly capacity
+
+Hobby, Pro and Scale remain credit subscriptions: they fund the existing owner
+wallet and set its resource tier. Spend that wallet on measured `payg` usage or
+a prepaid `monthly` resource pool. A monthly purchase does not create a second
+spendable balance. Stripe and wallet funds are payment sources. Both modes share the billing 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.
+
+A subscription belongs to its personal or namespace resource pool, never to a
+VM ID. One or many VMs can share it; confirmed deletion frees allocations without
+renewing or canceling the pool. Retained disks still consume storage. Each scope
+has one current capacity contract and one mode. Use separate namespaces for
+independent pools; they cannot borrow each other’s capacity. New pools share the
+owner tier’s global limits, so separate namespaces cannot multiply the account
+allowance. Monthly reservations consume that budget even when idle.
+
+New contracts report `allocationBasis: "running"`: confirmed stopped and hibernated
+VMs release running CPU/RAM, while retained disks, workspace slots and configured
+owned resources still count. Paused VMs and unresolved operations retain their
+running reservation. The account per-workspace limit and 12-vCPU platform ceiling
+still apply. Explicit namespace `max_total_*` policy remains an allocated ceiling.
+Already-sold contracts report `allocated` and retain their original scope and
+prices; this release does not change their purchased rights.
+
+PAYG uses the existing wallet balance and ordinary one-time wallet deposits.
+Adding funds does not raise resource limits. The catalog's optional
+`walletFunding` amounts and each preset's `paygEstimate.computeHourAmount` and
+`storageMonthAmount` are backend-computed USD cents. Hourly examples assume all
+CPU busy and all RAM allocated, before the cap; actual idle CPU can cost less.
+The cap limits usage charges, not the upfront deposit amount.
+
+For account wallet funding through `POST /credits/purchase`, send a fresh
+`idempotencyKey` for each deliberate deposit and reuse it unchanged after a
+timeout. Keys accept 8–128 letters, numbers, dots, colons, underscores or
+hyphens. Repeating a package is a new purchase; retrying one purchase resumes
+its saved checkout. This uses the existing wallet payment and fulfillment flow.
+
+SDK 2.8.1 adds the optional-namespace signatures below. Personal workspaces are the default. Call `billing.capacity()` without an argument to read them, and pass `null` as the first argument to capacity mutation methods. Supply an exact namespace slug to manage a separate named pool. REST requests omit `namespace` or send JSON `null` for personal billing; never send the query string `namespace=null`.
+
+```typescript
+const namespace = null; // Or a named pool's exact slug.
+const current = await client.billing.capacity(namespace);
+const catalog = current.catalog ?? await client.billing.capacityCatalog();
+const selected = catalog.presets.find(p => p.id === 'small' && p.available !== false);
+if (!selected) throw new Error('Choose a size within your account plan.');
+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 the selected scope 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'`. The dashboard uses wallet payment for new pools. Explicit recurring
+card integrations remain supported: 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, including settled credit-subscription
+invoices, can buy monthly coverage. `capacity().wallet.balance` and
+`wallet.monthlyAvailable` are USD dollars; the latter may be lower because it
+excludes gifts, test grants and unverified receipts. `accountPlan` is the owner’s
+backend-derived policy, and `available` on sizing examples indicates whether the
+size fits that plan. Quotes and confirmation recheck admission; these display
+fields never grant resources. 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. For new contracts, wallet renewal rechecks the current
+account tier before charging; a tier change never revokes the already-paid period.
+
+Monthly spending is not automatically refunded when a VM is stopped, deleted or
+replaced, or renewal is canceled. A support-approved wallet refund reverses the
+original period’s payments and coverage together, through the existing audited
+admin operation queue. The current-period refund also disables renewal. An old
+period refund cannot revoke a newer month; purchased extras are preserved. There
+is no customer SDK refund operation. Cash refunds remain provider verified.
+
+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 optional in both modes, charged only when using
+Oblien's managed internet proxy. Public routes and a customer-supplied proxy
+do not use this paid allowance. 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.
+
+Personal recurring compute uses the same management methods: `subscription()`, `cancelSubscription()`, `resumeSubscription()` and `portal()` omit the namespace; plan-change mutations take `null`. Reseller calls must always pass the namespace derived from the authenticated customer. Billing events use `namespace: null` for personal scope.
+
+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
@@ -17,7 +162,7 @@ Do not reassign a customer's namespace slug to someone else: its billing history
 stays attached to that owner/namespace identity.
 
 Omit `namespace` when creating a personal workspace. Its response has
-`namespace: null`, and billing uses the owner's account wallet and account plan.
+`namespace: null`. A personal capacity contract, when purchased, supplies its compute terms and resource pool. Without one, the existing account wallet and account plan apply. Personal capacity does not replace the account-tier subscription or alter any named namespace subscription.
 Namespace defaults do not apply to personal workspaces. A namespace literally named
 `default` or `null` is a separate customer budget. An enabled namespace policy,
 including an unlimited one, governs that namespace independently of the owner's
@@ -67,7 +212,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 +276,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 +303,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 +337,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 +358,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 +374,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 +434,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 +539,10 @@ 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
+These endpoints change an **existing reseller offer** or a direct personal monthly capacity subscription, without creating a second subscription or changing the owner's account-tier plan. For direct personal capacity, omit `namespace` (or send `null`) and use backend-priced capacity terms; reseller eligibility is not required for that saved direct purchase. The namespace inputs in the reseller examples below are mandatory for customer isolation. 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

@@ -2,7 +2,8 @@
 
 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 (`can_create: false`). Discover 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
@@ -37,15 +38,19 @@ 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 at creation, between 640×480 and 3840×2160. Change a stopped
-desktop's screen size with `updateSession(id, { resolution: { width, height } })`.
-Names can change while running. Reuse the same `idempotency_key` and request body
+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` or `stopping`. Other states: `running`, `stopped`, `failed`.
+`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** requires a stopped
-desktop and removes its profile, including files saved there. Other desktops and
+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.
@@ -87,6 +92,7 @@ oblien desktop create WORKSPACE_ID --name Development --resolution 1920x1080
 oblien desktop enable WORKSPACE_ID
 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

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).
 
+Account credit subscriptions fund the existing wallet and set the owner resource tier. That wallet funds 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/releases/2.8.1.md

@@ -0,0 +1,29 @@
+# SDK 2.8.1
+
+Makes namespace selection optional for direct compute purchases and management.
+`billing.capacity()` and `billing.subscription()` default to personal workspaces;
+capacity quote, checkout and change methods accept `null` as the namespace.
+`billing.portal()` also opens personal compute billing without an argument.
+
+Personal responses return `namespace: null`. The SDK omits the namespace from
+requests instead of sending the literal string `null`. Named namespaces,
+including a namespace named `default`, remain separate. Reseller checkout still
+requires an explicit customer namespace and the existing reseller permissions.
+Personal compute subscriptions do not replace account tiers or customer plans.
+
+The catalog types also expose optional backend-computed PAYG hourly/storage
+examples and wallet deposit limits, in USD cents. Monthly and PAYG both use a
+shared resource pool: creating or replacing a VM does not start a subscription.
+Wallet deposits fund usage; they do not increase the pool's resource limits.
+
+The response types also expose backend-derived `accountPlan`, wallet balances in
+USD, sizing-example `available` flags, and `allocationBasis` / `runningPool`.
+Account credit subscriptions remain the funding product. Monthly pools spend
+eligible paid wallet funds upfront; PAYG spends measured usage. There is one
+wallet and ledger. Existing direct-card contracts retain their saved terms.
+
+The matching API and dashboard are deployed. Existing namespace calls remain
+compatible. See [billing](../billing.md) for the complete flow.
+
+This patch is ready for the repository owner to publish; it has not been
+published automatically. Version 2.8.0 is already available on npm.

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.1",
+  "version": "2.8.1",
   "description": "Official TypeScript SDK for the Oblien Workspace API",
   "type": "module",
   "main": "./dist/index.js",