oblien 2.3.2 → 2.5.0

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