@ovra/ts-sdk 0.4.1 → 0.5.0

package/README.md

@@ -8,9 +8,10 @@ infrastructure for AI agents. Issue virtual Visa cards, declare and approve
 spending intents, settle payments under signed mandates, and reconcile from
 the same typed surface.
 
-**Version: `0.4.1`** — fully bound to the `/v1/*` API. Auto-published
-from `apps/api/openapi.json` on every push to `main` that touches the
-spec or `packages/sdk/src`; see the repo
+**Version: `0.5.0`** — fully bound to the `/v1/*` API. Regenerated
+from `apps/api/openapi.json`; releases ship manually for now (see
+[Publishing](#publishing) below — auto-publish is wired but pending
+on GH Actions billing). See the repo
 [CHANGELOG](https://github.com/ovra/ovra/blob/main/CHANGELOG.md) for the
 v0 → v1 migration notes.
 
@@ -341,40 +342,154 @@ await ovra.agenticCommerce.refundOrder({
 
 ## Resource coverage
 
-`Ovra` binds the highest-traffic resources as ergonomic namespaces. The
-full v1 surface (103 paths, ~145 operations) is also available as
-tree-shakable functions via `import { … } from "@ovra/ts-sdk/api"` —
-use those directly for the long-tail resources not in the table below.
+`Ovra` binds every `/v1/*` resource as an ergonomic namespace —
+33 namespaces, 141 operations total, all of them auto-typed from the
+generated client. Listed by domain:
+
+### Money
+
+- `wallets` — `list`, `create`, `get`, `update`, `delete`
+- `transfers` — `list`, `create`, `get`
+- `beneficiaries` — `list`, `create`, `get`, `update`, `delete`
+- `refunds` — `list`, `create`, `get`
+- `paymentRequests` — `list`, `create`, `get`, `cancel`
+- `ledgerEntries` — `list`, `get` (double-entry ledger, read-only)
+- `billing` — `getSubscription`, `createSubscription`,
+  `createPortalSession`, `getPaymentMethod`, `setupPaymentMethod`,
+  `fundWallet`, `getSepaInstructions`, `getBalance`, `collectOverage`
+- `invoices` — `list`, `get`
+
+### Agents & spending
+
+- `agents` — `list`, `create`, `get`, `update`, `delete`, `freeze`,
+  `unfreeze`, `getByExternalId`
+- `cards` — `list`, `create`, `get`, `update`, `freeze`, `unfreeze`,
+  `close`, `rotate`
+- `intents` — `list`, `create`, `get`, `approve`, `deny`, `cancel`,
+  `issueCredentials`, `confirmPayment`
+- `transactions` — `list`, `get` (read-only)
+- `checkout` — `execute`, `confirm`
+- `agenticCommerce` — `listVerticals`, `search`, `getOffer`,
+  `getMerchantJwk`, `buy`, `listOrders`, `getOrder`, `verifyOrder`,
+  `refundOrder`
+- `runs` — `create`, `get`
+- `outcomes` — `list`, `create`, `get`
+- `forecast` — `get`
+- `pay()` — one-call buy convenience wrapper around
+  `agenticCommerce.buy`
+
+### Compliance & governance
+
+- `policies` — `list`, `create`, `get`, `update`, `delete`, `apply`
+- `approvalPolicies` — `create`, `get`, `update`, `delete`
+- `disputes` — `list`, `create`, `get`, `resolve`, `listEvidence`,
+  `addEvidence` (nested per-dispute)
+- `disputeEvidence` — `list`, `create` (standalone file uploads)
+- `riskEvents` — `list`, `listViolations`, `listFraudAlerts`,
+  `updateFraudAlert`, `getAgentRisk`, `unfreezeAgent`, `getConfig`,
+  `updateConfig`, `getSummary`
+- `auditEvents` — `list`, `get`, `verifyChain` (tamper-evident)
+- `accessEvents` — `list`, `get`
+- `metrics` — `list`
+
+### Identity & access
+
+- `customers` — `me`, `create`, `get`, `update`
+- `apiKeys` — `list`, `create`, `get`, `delete` (requires `sk_*` scope)
+- `delegations` — `list`, `create`, `get`, `delete` (mint `at_*` tokens)
+- `passkeys` — `list`, `revoke`
+- `merchantCategories` — `list`, `get` (MCC lookup)
+
+### Webhooks & notifications
+
+- `webhooks` — `list`, `create`, `get`, `update`, `delete`,
+  `rotateSecret`, `ping`, `listDeliveries`
+- `notifications` — `list`, `unreadCount`, `markRead`, `markAllRead`
+  (user-scoped — token credential, not `sk_*`)
+- `pushSubscriptions` — `getVapidPublicKey`, `register`, `delete`
+  (Web Push for the approve PWA)
+
+### Scope requirements
+
+Most write namespaces require an `sk_*` workspace key. The following
+will 403 with a restricted (`rk_*`) or agent (`at_*`) token:
+
+- `apiKeys.*`, `delegations.create|delete`, `webhooks.*` mutations,
+  `policies.*` mutations, `approvalPolicies.*`, `billing.*` mutations,
+  `riskEvents.updateConfig|unfreezeAgent`, `customers.create|update`
+
+Reads on those surfaces are allowed with `rk_*`. `notifications`,
+`pushSubscriptions`, and `passkeys` are user-scoped — they want a
+session credential, not a workspace key.
+
+### Plan requirements
+
+A handful of namespaces are gated on the workspace's billing plan and
+will throw `E_PLAN_UPGRADE_REQUIRED` (HTTP 402) or
+`E_PERMISSION_DENIED` (HTTP 403) on Starter:
+
+- **Business plan or higher** — `auditEvents.*`, `metrics.*`,
+  `riskEvents.*`, `delegations.*`
+
+Catch the error and surface the upgrade prompt:
 
-Bound on the `Ovra` instance:
+```ts
+try {
+  await ovra.auditEvents.list();
+} catch (err) {
+  if (err instanceof OvraError && err.code === "E_PLAN_UPGRADE_REQUIRED") {
+    // route the user to getovra.com/dashboard/billing
+  }
+}
+```
 
-- **Agents & auth** — `agents`, `passkeys`
-- **Spending** — `intents`, `cards`, `checkout`, `agenticCommerce`,
-  `paymentRequests`
-- **Money movement** — `wallets`, `transfers`, `beneficiaries`, `refunds`
-- **Policy & governance** — `policies`, `disputes`
-- **Observability** — `transactions`, `outcomes`, `runs`, `forecast`
-- **Identity** — `customers`, `webhooks`
-- **One-call buy** — `pay()` (wraps `agenticCommerce.buy`)
+### Tree-shaking
 
-Need `apiKeys`, `delegations`, `approvalPolicies`, `riskEvents`,
-`auditEvents`, `accessEvents`, `notifications`, `invoices`, `metrics`,
-`merchantCategories`, `pushSubscriptions`, `ledgerEntries`,
-`disputeEvidence`, or `billing`? Import the generated function and pass
-the client:
+Prefer raw functions over the class? Every operation is also exported
+from `@ovra/ts-sdk/api`:
 
 ```ts
-import { Ovra } from "@ovra/ts-sdk";
 import { listApiKeys } from "@ovra/ts-sdk/api";
-
-const ovra = new Ovra({ apiKey: process.env.OVRA_API_KEY! });
-// (advanced) reach into the generated client for unbound namespaces:
 const keys = await listApiKeys({ query: { limit: 10 } });
 ```
 
 The full inventory is in `apps/api/openapi.json` (single source of
 truth — the SDK is regenerated from it on every release).
 
+## Publishing
+
+> **Status (2026-05-28):** auto-publish via
+> `.github/workflows/sdk-publish.yaml` is wired correctly but
+> **currently blocked at the runner-allocation step** — the GitHub
+> account has a billing issue ("recent account payments have failed
+> or your spending limit needs to be increased"). All workflow runs
+> exit in ~3-5 s before the YAML steps start. Until billing is
+> restored, every release ships via the manual script below; both
+> `0.4.0` and `0.4.1` were published this way.
+
+Manual release flow (single command — runs regen + build + version
+check + `npm publish`):
+
+```sh
+# Bump packages/sdk/package.json version first (semver: patch / minor / major)
+pnpm --filter @ovra/ts-sdk version patch --no-git-tag-version
+
+# Then publish (refuses if local <= remote, or if git tree is dirty)
+pnpm run publish:sdk            # or: pnpm --filter @ovra/ts-sdk run publish-manual
+pnpm run publish:sdk:dry        # dry-run (no upload, full pipeline otherwise)
+```
+
+The script lives at `scripts/publish-sdk.sh`. Requirements: logged in
+to npm as a publisher on the `@ovra` scope (`npm login`), clean git
+tree, local version strictly greater than the version currently on
+npm.
+
+Once GH Actions billing is restored, every push to `main` that
+touches `apps/api/openapi.json`, `packages/sdk/src/**`,
+`packages/sdk/openapi-ts.config.ts`, or `packages/sdk/package.json`
+will regenerate, bump (patch), and publish automatically — the
+workflow is already in place.
+
 ## License
 
 Commercial — see [LICENSE](./LICENSE). The Ovra service requires a paid