@ovra/ts-sdk 0.4.1 → 0.5.1

package/README.md

@@ -1,381 +1,461 @@
-# Ovra TypeScript SDK
+# `@ovra/ts-sdk`
 
-[![NPM version](https://img.shields.io/npm/v/@ovra/ts-sdk.svg)](https://www.npmjs.com/package/@ovra/ts-sdk)
-[![NPM downloads](https://img.shields.io/npm/dm/@ovra/ts-sdk.svg)](https://www.npmjs.com/package/@ovra/ts-sdk)
+[![npm](https://img.shields.io/npm/v/@ovra/ts-sdk?label=npm&color=2bc760)](https://www.npmjs.com/package/@ovra/ts-sdk)
+[![downloads](https://img.shields.io/npm/dm/@ovra/ts-sdk?color=2bc760)](https://www.npmjs.com/package/@ovra/ts-sdk)
+[![bundle](https://img.shields.io/bundlephobia/minzip/@ovra/ts-sdk?label=size)](https://bundlephobia.com/package/@ovra/ts-sdk)
+[![types](https://img.shields.io/npm/types/@ovra/ts-sdk?color=3178c6)](https://www.npmjs.com/package/@ovra/ts-sdk)
 
-The official TypeScript SDK for the [Ovra API](https://getovra.com) — payment
-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.
+> Payment infrastructure for AI agents. Mint virtual Visa cards bound to
+> AP2 mandate chains, settle in one call, never see a PAN.
 
-**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
-[CHANGELOG](https://github.com/ovra/ovra/blob/main/CHANGELOG.md) for the
-v0 → v1 migration notes.
+```ts
+import { Ovra } from "@ovra/ts-sdk";
+
+const ovra = new Ovra({ apiKey: process.env.OVRA_API_KEY! });
+
+const result = await ovra.pay({
+  agentId: "agt_…",          // an active agent in your workspace
+  offerId: "aic_openai-1000", // catalog offer id
+  merchant: "OpenAI",
+  amount: 10.0,               // €10.00
+  purpose: "Top up OpenAI credits",
+});
 
-**0.4.0 is a breaking release.** The `/v1/credentials/*` and
-`/v1/authorization-grants/*` rails were removed (alongside MCP
-`ovra_pay`); the AP2 agentic-commerce buy is now the canonical payment
-flow. The `ovra.credentials` namespace is gone — use
-`ovra.agenticCommerce.{search, buy, getOrder, listOrders, verifyOrder,
-refundOrder}` instead. See "Agentic Commerce surface" below.
+if (result.status === "completed") {
+  console.log(result.orderId);                                // cmo_…
+  console.log(result.order.amount);                           // { amount: 1000, currency: "eur" }
+  console.log(result.order.authorization.network_auth_code);  // "000123"
+  console.log(result.order.receipt.id);                       // vrcpt_…
+}
+```
+
+One call. The SDK declares the intent, runs the policy gate, debits
+the wallet, mints the DPAN, signs the 4-mandate AP2 chain, captures
+with the merchant, and returns the order envelope.
+
+---
+
+## What you get
+
+- **Typed end-to-end** — every request body, response envelope, and error
+  code is generated from the live OpenAPI spec. No `any` leaking.
+- **One-call payments** — `ovra.pay()` for the AP2 happy path, or drop
+  to primitives (`agents`, `intents`, `agenticCommerce.buy`) when you
+  need control.
+- **Card data never reaches your code** — PAN/CVV stay inside Ovra;
+  you get `last4` + a single-use DPAN + cryptogram per transaction.
+- **33 namespaces** — agents, cards, wallets, intents, transactions,
+  agentic-commerce, refunds, webhooks, audit, billing, and 23 more.
+- **Idempotent by default** — every mutating call mints a UUID
+  Idempotency-Key; safe to retry on network failure.
+- **Sender-agnostic** — Node 20+, Bun, Deno, Cloudflare Workers,
+  Vercel Edge, any runtime with `fetch`.
+
+---
 
 ## Install
 
 ```sh
-npm install @ovra/ts-sdk
+npm i @ovra/ts-sdk        # or pnpm add / yarn add / bun add
 ```
 
-Requirements: Node.js 20+, or any runtime with `fetch` (Bun, Deno,
-Cloudflare Workers, Vercel Edge).
+Get a `sk_test_*` key from `app.getovra.com` → Settings → API keys.
 
-## Quickstart
+---
 
-Grab an API key at [getovra.com/dashboard](https://getovra.com/dashboard) →
-Settings → API keys, then drop straight into the canonical **one-call buy**:
+## 60-second tour
+
+### The one-call AP2 purchase (recommended)
 
 ```ts
 import { Ovra } from "@ovra/ts-sdk";
 
 const ovra = new Ovra({ apiKey: process.env.OVRA_API_KEY! });
 
-// `ovra.pay()` wraps the AP2 agentic-commerce buy — DPAN mint + the
-// 4-mandate AP2 chain + capture + receipt in one round-trip. Amount is
-// EUR (decimal); the SDK converts to cents on the wire.
-const result = await ovra.pay({
-  agentId: "agt_…",      // an active agent in your workspace
-  offerId: "off_…",      // catalog offer id (see ovra.agenticCommerce.search)
-  merchant: "Notion",
-  amount: 79.0,          // €79.00
-  purpose: "Monthly Notion Team Plan renewal",
+// 1. Discover an offer
+const { data: offers } = await ovra.agenticCommerce.search({
+  body: { vertical: "ai-credits", query: { provider: "openai", amount_usd: 10 } },
 });
 
-if (result.status === "completed") {
-  console.log(result.orderId, result.order.authorization.network_auth_code);
-} else {
-  console.error("buy failed:", result.reason);
-}
-```
-
-Prefer the raw operation? Same call, different envelope shape:
-
-```ts
-const { data: order } = await ovra.agenticCommerce.buy({
-  body: {
-    agent_id: "agt_…",
-    offer_id: "off_…",
-    purpose: "Monthly Notion Team Plan renewal",
-  },
+// 2. Buy it — one call covers intent + policy + wallet + DPAN + AP2 chain + capture
+const order = await ovra.pay({
+  agentId: "agt_…",
+  offerId: offers[0].id,
+  merchant: offers[0].merchant.name,
+  amount: offers[0].amountCents / 100,
 });
-console.log(order.order_id, order.status);
+
+console.log(order.orderId);                  // cmo_…
+console.log(order.status);                   // "completed" | "pending_approval" | "failed"
+console.log(order.order?.receipt?.id);       // vrcpt_…
+console.log(order.order?.mandate_chain);     // { open_checkout, open_payment, closed_checkout, closed_payment }
 ```
 
-Need the lower-level intent / checkout pipeline (custom approval UI,
-out-of-band capture)? The primitives are still here:
+### Reading + reconciling
 
 ```ts
-// 1. Provision an agent. `policy` is required — fetch one via
-//    `ovra.policies.list()`. `profile.purpose` is required.
-const { data: agent } = await ovra.agents.create({
-  body: {
-    name: "Notion Buyer",
-    policy: "po_…",
-    profile: { purpose: "Monthly Notion Team Plan renewal" },
-  },
-});
+// List orders (cursor-paginated, auto-unwrapped)
+const orders = await ovra.agenticCommerce.listOrders();
+for (const o of orders.data) console.log(o.id, o.status, o.totals);
 
-// 2. Declare a spending intent (`agent`, not `agent_id`).
-const { data: intent } = await ovra.intents.create({
-  body: {
-    agent: agent.id,
-    merchant: "Notion",
-    amount: { amount: 7900, currency: "eur" }, // €79.00
-    purpose: "Monthly Notion Team Plan renewal",
-  },
-});
+// Get one with the full UCP envelope (line_items + fulfillment + adjustments)
+const detail = await ovra.agenticCommerce.getOrder({ path: { order_id: "cmo_…" } });
+
+// Verify the AP2 chain integrity server-side
+const verified = await ovra.agenticCommerce.verifyOrder({ path: { order_id: "cmo_…" } });
+if (!verified.data.valid) console.warn("chain tampered:", verified.data.reasons);
+```
 
-// 3. Approve the intent (production: this comes from the human
-//    approving in the dashboard or a passkey assertion).
-await ovra.intents.approve({ path: { id: intent.id } });
+### Refunds
 
-// 4. Execute the checkout — `intent` + `target_url` (the merchant URL
-//    the DPAN will be submitted to) are both required.
-const { data: result } = await ovra.checkout.execute({
-  body: {
-    intent: intent.id,
-    target_url: "https://www.notion.so/checkout",
-  },
+```ts
+// Partial refund — order goes COMPLETED → COMPENSATED
+await ovra.agenticCommerce.refundOrder({
+  path: { order_id: "cmo_…" },
+  body: { amount_cents: 500, reason: "customer cancellation" },
 });
 
-console.log(result.transaction_id, result.status);
+// Or full refund (no body) — order goes COMPLETED → REFUNDED
+await ovra.agenticCommerce.refundOrder({ path: { order_id: "cmo_…" } });
 ```
 
-Amounts on the wire are integers in the currency's minor units
-(`amount: 7900` = €79.00). Card PAN / CVV are **never** returned — only
-`last4` and a tokenized DPAN reach your code.
+---
 
-## Authentication
+## Auth scopes
 
-The constructor accepts any Ovra credential prefix. Pick the smallest scope
-that fits the call site.
+The constructor takes any Ovra credential prefix. Pick the smallest scope that fits.
 
-| Prefix              | What it is             | Use when                                                            |
-| ------------------- | ---------------------- | ------------------------------------------------------------------- |
-| `sk_live_…`         | Full workspace key     | Server-side production code that needs to mint/rotate/manage.       |
-| `sk_test_…`         | Full key, sandbox mode | Local dev and CI; `livemode: false` on every response.              |
-| `rk_…` / `rk_test_…` | Restricted key         | Read + scoped writes; blocked from key, webhook, billing, policy mutations. Safe to embed in less-trusted runtimes. |
-| `at_…`              | Agent token            | Scoped to one agent with a hard spend cap. The credential you ship to an agent runtime. |
+| Prefix         | What                  | When                                                                       |
+| -------------- | --------------------- | -------------------------------------------------------------------------- |
+| `sk_live_…`    | Full live key         | Server-side prod code that mints / rotates / manages.                      |
+| `sk_test_…`    | Full sandbox key      | Local dev + CI. Every envelope returns `livemode: false`.                  |
+| `rk_…`         | Restricted key        | Read + scoped writes. Blocked from keys / webhooks / billing / policies.   |
+| `at_…`         | Agent token           | Bound to one agent with a hard spend cap. The credential you ship to the agent runtime. |
 
 ```ts
 const ovra = new Ovra({
   apiKey: process.env.OVRA_API_KEY!,
-  // Sent as the `X-Ovra-Client-App` header on every request — used for
-  // analytics and to help support trace issues back to your integration.
-  appInfo: { name: "AcmeCRM", version: "1.4.2" },
+  appInfo: { name: "AcmeCRM", version: "1.4.2" }, // X-Ovra-Client-App header
 });
 
-// Best-effort scope hint derived from the key prefix — useful for
-// dev-time logging only; the server is the source of truth.
-//   sk_* → "full"   |   rk_* → "restricted"   |   at_* → "agent"
-console.log(ovra.keyScope);
+console.log(ovra.keyScope); // "full" | "restricted" | "agent" | "unknown" (dev-time hint)
 ```
 
-Test-mode keys produce objects with `livemode: false`; live keys produce
-`livemode: true`. Whenever the API is deployed against the sandbox card
-issuer, **every** response is `livemode: false` regardless of key — the
-whole workspace is sandbox until the real issuer ships.
-
-## Money
-
-Money is `{ amount, currency }` everywhere on the wire. `amount` is an
-integer in minor units; `currency` is a three-letter ISO code lowercased.
-
-| Display      | Wire value                                |
-| ------------ | ----------------------------------------- |
-| €50.00       | `{ amount: 5000, currency: "eur" }`       |
-| €0.99        | `{ amount: 99, currency: "eur" }`         |
-| £1,234.56    | `{ amount: 123456, currency: "gbp" }`     |
-| ¥1,000 (JPY) | `{ amount: 1000, currency: "jpy" }` (JPY has no minor units; treat the integer as the whole-yen amount.) |
-
-Floats and decimal strings are rejected at the validation layer. There is
-no implicit unit conversion — what you send is what gets compared against
-the policy.
-
-## Timestamps
-
-Every timestamp is an ISO 8601 string in the `created` field
-(`"2026-05-25T18:04:16Z"`). The legacy `created_at` / `createdAt` / epoch
-millis variants are gone.
+---
 
 ## Errors
 
-API errors throw a typed subclass of `OvraError`. Branch on type, status,
-or — preferred — `code`:
+Typed exceptions per error category — branch on `e.code` (machine-readable),
+show `e.message` to humans, link to `e.docUrl` from your own UI.
 
 ```ts
 import {
   Ovra,
   OvraError,
+  OvraAuthenticationError,
+  OvraPermissionError,
+  OvraPaymentRequiredError,
+  OvraConflictError,
   OvraNotFoundError,
-  OvraRateLimitError,
 } from "@ovra/ts-sdk";
 
 try {
-  await ovra.cards.get({ path: { id: "crd_…" } });
-} catch (err) {
-  if (err instanceof OvraNotFoundError) {
-    // 404 — card doesn't exist or isn't yours
-  } else if (err instanceof OvraRateLimitError) {
-    // 429 — back off and retry
-  } else if (err instanceof OvraError && err.code === "E_POLICY_DENIED") {
-    // policy gate refused the spend; `err.message` is the human string,
-    // `err.param` points at the offending body field if any.
-  } else {
-    throw err;
+  await ovra.pay({ agentId, offerId, merchant, amount });
+} catch (e) {
+  if (!(e instanceof OvraError)) throw e;
+
+  switch (e.code) {
+    case "E_INSUFFICIENT_FUNDS":     return refillAndRetry(e.message);
+    case "E_POLICY_LIMIT_EXCEEDED":  return showLimits(e.escalationReason);
+    case "E_OFFER_EXPIRED":          return reSearch();
+    case "E_MANDATE_BINDING_FAIL":   return audit(e.requestId);
+    case "E_FSM_INVALID_TRANSITION": return refreshState();
+    default:                          return showError(e.message, e.docUrl);
   }
 }
 ```
 
-On the wire, every error body matches the v1 envelope:
+Every error envelope carries `code`, `type`, `message`, `param`, `docUrl`,
+`requestId`, and `status`. See the [error reference](https://app.getovra.com/docs/errors).
 
-```json
-{
-  "error": {
-    "type": "policy_error",
-    "code": "E_POLICY_DENIED",
-    "message": "Spend exceeds the configured policy limit.",
-    "param": "amount",
-    "doc_url": "https://docs.getovra.com/errors/E_POLICY_DENIED",
-    "request_id": "req_…",
-    "status": 403
-  }
-}
-```
-
-The thrown `OvraError` flattens that envelope onto the instance —
-`err.type`, `err.code`, `err.message`, `err.param`, `err.docUrl`,
-`err.requestId`, `err.status`. Branch on `err.code` — it's typed,
-~50 canonical values, stable across releases. Never parse `err.message`
-— it's a human string and may change.
+---
 
 ## Idempotency
 
-Mutating requests (`POST`, `PATCH`, `DELETE`) require an `Idempotency-Key`
-header. **The SDK auto-mints a fresh UUID per call**, so retries through
-the built-in retry policy are safe by default. Override per-call when you
-want explicit deduplication across processes:
+Every mutating call (POST / PATCH / DELETE) is idempotent by default — the
+SDK mints a UUID `Idempotency-Key` per logical operation and reuses it
+across retries. Replays inside the 24h dedup window return the original
+response with `X-Idempotent-Replayed: true`.
+
+Bring your own key when you need cross-process dedup:
 
 ```ts
-await ovra.transfers.create({
-  headers: { "Idempotency-Key": "transfer-2026-q2-invoice-4711" },
-  body: {
-    from_wallet: "wal_…",
-    to_beneficiary: "ben_…",
-    amount: { amount: 250000, currency: "eur" },
-  },
+await ovra.intents.create({
+  body: { agent: "agt_…", merchant: "Notion", amount: { amount: 7900, currency: "eur" }, purpose: "…" },
+  headers: { "Idempotency-Key": "your-stable-key" },
 });
 ```
 
-Re-sending the same key + identical body returns the original response.
-Re-sending the same key with a *different* body returns
-`E_IDEMPOTENCY_CONFLICT` (HTTP 409). An in-flight collision returns
-`E_IDEMPOTENCY_IN_FLIGHT`.
+---
 
 ## Pagination
 
-Every list method is cursor-paginated and returns the canonical envelope
-directly — the SDK auto-strips hey-api's outer `{data, request, response}`
-wrapper for any `list*` call so you get the list shape verbatim:
+List endpoints return `{ data, has_more, next_cursor }` (auto-unwrapped from
+the hey-api envelope). Walk pages with `next_cursor`:
 
 ```ts
-const page1 = await ovra.cards.list({ query: { limit: 50 } });
-//      ^? { object: "list", data: Card[], has_more, next_cursor, url }
+let cursor: string | undefined;
+do {
+  const page = await ovra.transactions.list({ query: { limit: 100, starting_after: cursor } });
+  for (const tx of page.data) process(tx);
+  cursor = page.has_more ? page.next_cursor : undefined;
+} while (cursor);
+```
 
-for (const card of page1.data) {
-  console.log(card.id, card.last4);
-}
+Default `limit` is 50, max 100. Bad cursors return `400 E_VALIDATION` —
+no silent full-list fallback.
 
-if (page1.has_more) {
-  const page2 = await ovra.cards.list({
-    query: { limit: 50, starting_after: page1.next_cursor! },
-  });
-}
-```
+---
 
-Or use the `paginate` helper to iterate the full set:
+## Money
+
+Wire amounts are integer cents inside a Money object: `{ amount, currency }`.
 
 ```ts
-import { paginate } from "@ovra/ts-sdk";
+import { parseMoney, formatMoney } from "@ovra/ts-sdk";
 
-for await (const card of paginate(
-  (args) => ovra.cards.list({ query: args }),
-  { limit: 50 },
-)) {
-  console.log(card.id, card.last4);
-}
+parseMoney(79.0)                                        // { amount: 7900, currency: "eur" }
+parseMoney("79.00", "usd")                              // { amount: 7900, currency: "usd" }
+formatMoney({ amount: 7900, currency: "eur" }, "de-DE") // "79,00 €"
 ```
 
-The wire envelope (what `page1` deserializes to):
+`ovra.pay()` accepts decimals (`amount: 79.0` = €79.00) and converts at the
+boundary. Lower-level `agents/intents/transactions` operate on Money objects
+directly.
 
-```json
-{
-  "object": "list",
-  "data": [ /* … */ ],
-  "has_more": true,
-  "next_cursor": "card_01HE…",
-  "url": "/v1/cards"
-}
-```
+---
 
-## Retries
+## Resource matrix
 
-Connection errors and 5xx / 429 / 408 responses retry automatically with
-jittered exponential backoff (500 ms → 4 s, 30 s wall-clock budget).
-Tune or disable per-client:
+33 typed namespaces. Scope + plan gating shown.
 
-```ts
-const ovra = new Ovra({
-  apiKey: "…",
-  retry: { maxRetries: 5, maxElapsedMs: 60_000 },
-  // or: retry: false
-});
-```
+<details><summary><b>Money &amp; orders</b> (8 namespaces) — click to expand</summary>
+
+| Namespace                | Ops                                                | Scope | Plan |
+| ------------------------ | -------------------------------------------------- | :---: | :--: |
+| `wallets`                | list / get / fund / topup                          | any   | free |
+| `transactions`           | list / get / memo                                  | any   | free |
+| `intents`                | create / list / get / approve / cancel / verify    | any   | free |
+| `agenticCommerce`        | listVerticals / search / getOffer / buy / listOrders / getOrder / verifyOrder / refundOrder | any | free |
+| `ledgerEntries`          | list                                               | full  | free |
+| `invoices`               | list / get                                         | full  | free |
+| `billing`                | getBalance / addPaymentMethod                      | full  | free |
+
+</details>
+
+<details><summary><b>Agents &amp; spending</b> (7 namespaces)</summary>
+
+| Namespace          | Ops                                                                     | Scope | Plan     |
+| ------------------ | ----------------------------------------------------------------------- | :---: | :------: |
+| `agents`           | create / list / get / update / attest / freeze / unfreeze               | any   | free     |
+| `cards`            | issue / list / get / freeze / unfreeze / rotate / close                 | any   | free     |
+| `policies`         | list / get / create / update / delete / assign                          | full  | free     |
+| `delegations`      | create / list / get / redeem / revoke                                   | full  | pro      |
+| `approvalPolicies` | list / get / create / update / delete                                   | full  | business |
+| `costAllocations`  | list / create / assign / delete                                         | full  | pro      |
+| `spendAnomalies`   | list / ack / dismiss                                                    | full  | pro      |
+
+</details>
+
+<details><summary><b>Compliance &amp; governance</b> (5 namespaces)</summary>
+
+| Namespace          | Ops                                       | Scope | Plan     |
+| ------------------ | ----------------------------------------- | :---: | :------: |
+| `riskEvents`       | list                                      | full  | business |
+| `disputeEvidence`  | list / upload / get                       | any   | free     |
+| `auditEvents`      | list                                      | full  | business |
+| `accessEvents`     | list                                      | any   | free     |
+| `metrics`          | list                                      | full  | business |
+
+</details>
+
+<details><summary><b>Identity &amp; access</b> (3 namespaces)</summary>
+
+| Namespace            | Ops                                  | Scope | Plan |
+| -------------------- | ------------------------------------ | :---: | :--: |
+| `customers`          | get / update / gdpr_* (dashboard)    | full  | free |
+| `apiKeys`            | list / create / revoke               | full  | free |
+| `merchantCategories` | list / explain                       | any   | free |
+
+</details>
+
+<details><summary><b>Webhooks &amp; notifications</b> (3 namespaces)</summary>
 
-## Agentic Commerce surface
+| Namespace           | Ops                                                  | Scope | Plan |
+| ------------------- | ---------------------------------------------------- | :---: | :--: |
+| `webhooks`          | list / create / get / update / delete / rotate-secret| full  | free |
+| `notifications`     | list / unread_count / mark_read / mark_all_read      | any   | free |
+| `pushSubscriptions` | subscribe / unsubscribe / vapidPublicKey             | any   | free |
 
-The AP2 sandbox is the canonical buy pipeline as of 0.4.0. Catalog
-discovery, the buy orchestrator, and the UCP-shaped order envelope
-(line_items / fulfillment / adjustments / totals / permalink_url) all
-live under `ovra.agenticCommerce`:
+</details>
+
+> **Want a different namespace?** Generated functions for every operation
+> live in `@ovra/ts-sdk/api` — bypass the bound facade and call them
+> directly. The bindings exist for ergonomics; nothing's hidden.
+
+---
+
+## Recipes
+
+<details><summary><b>Manual intent → approve → checkout</b></summary>
 
 ```ts
-// Browse the 10-vertical catalog
-const offers = await ovra.agenticCommerce.search({
-  body: { vertical: "saas-subscriptions", query: { merchant: "notion", plan: "team" } },
+// 1. Create an agent (policy is required; profile.purpose is required)
+const { data: agent } = await ovra.agents.create({
+  body: {
+    name: "Notion Buyer",
+    policy: "po_…",
+    profile: { purpose: "Monthly Notion Team Plan renewal" },
+  },
 });
 
-// One-call buy — mints DPAN + signs the 4-mandate AP2 chain + captures.
-// The route reads `agent_id`, `offer_id`, `purpose`, optional `card_id`
-// + `intent_id`. Amount + merchant are derived from the offer.
-const order = await ovra.agenticCommerce.buy({
+// 2. Declare a spending intent (field is `agent`, not `agent_id`)
+const { data: intent } = await ovra.intents.create({
   body: {
-    agent_id: "agt_…",
-    offer_id: "off_…",
+    agent: agent.id,
+    merchant: "Notion",
+    amount: { amount: 7900, currency: "eur" },
     purpose: "Monthly Notion Team Plan renewal",
   },
 });
 
-// Re-verify the AP2 chain against the cached mandate set
-const check = await ovra.agenticCommerce.verifyOrder({
-  path: { order_id: order.data.order_id },
-});
+// 3. Approve (production: passkey ceremony; sandbox: viaFixture=true)
+await ovra.intents.approve({ path: { id: intent.id }, body: { confirm: true } });
 
-// UCP-conformant refund — append to adjustments, debit totals, flip
-// status to REFUNDED (full) or COMPENSATED (partial)
-await ovra.agenticCommerce.refundOrder({
-  path: { order_id: order.data.order_id },
-  body: { amount_cents: 7900, reason: "customer cancelled" },
+// 4. Execute the checkout — `intent` + `target_url` both required
+const { data: result } = await ovra.checkout.execute({
+  body: { intent: intent.id, target_url: "https://www.notion.so/checkout" },
 });
+console.log(result.transaction_id, result.status);
 ```
 
-## Resource coverage
+</details>
 
-`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.
+<details><summary><b>List + reconcile transactions for one agent</b></summary>
 
-Bound on the `Ovra` instance:
+```ts
+let cursor: string | undefined;
+const all: Transaction[] = [];
+do {
+  const page = await ovra.transactions.list({
+    query: { agent: "agt_…", limit: 100, starting_after: cursor },
+  });
+  all.push(...page.data);
+  cursor = page.has_more ? page.next_cursor : undefined;
+} while (cursor);
+
+const totalCents = all
+  .filter(t => t.status === "completed")
+  .reduce((sum, t) => sum + t.amount.amount, 0);
+```
 
-- **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`)
+</details>
 
-Need `apiKeys`, `delegations`, `approvalPolicies`, `riskEvents`,
-`auditEvents`, `accessEvents`, `notifications`, `invoices`, `metrics`,
-`merchantCategories`, `pushSubscriptions`, `ledgerEntries`,
-`disputeEvidence`, or `billing`? Import the generated function and pass
-the client:
+<details><summary><b>Register a webhook + handle delivery</b></summary>
 
 ```ts
-import { Ovra } from "@ovra/ts-sdk";
-import { listApiKeys } from "@ovra/ts-sdk/api";
+// One-time setup
+const { data: hook } = await ovra.webhooks.create({
+  body: {
+    url: "https://app.example.com/ovra/webhook",
+    events: ["intent.approved", "transaction.completed", "order.refunded"],
+  },
+});
+console.log("save this secret:", hook.signing_secret);
+
+// In your HTTP handler — verify signature with the shared secret.
+// Ovra uses HMAC-SHA256 over the raw body (Stripe-style):
+//   sig = hex( hmac_sha256(secret, raw_body) )
+//   compare in constant time against the `X-Ovra-Signature` header
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const expected = createHmac("sha256", process.env.OVRA_WEBHOOK_SECRET!)
+  .update(rawBody)
+  .digest("hex");
+const got = (req.headers["x-ovra-signature"] as string).replace(/^sha256=/, "");
+if (!timingSafeEqual(Buffer.from(expected, "hex"), Buffer.from(got, "hex"))) {
+  return res.status(401).send("bad signature");
+}
+```
 
-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 } });
+</details>
+
+<details><summary><b>Issue a delegation (sub-agent / B2B2B)</b></summary>
+
+```ts
+const { data: delegation } = await ovra.delegations.create({
+  body: {
+    grantor_agent: "agt_…",
+    purpose: "Marketing team — quarterly spend",
+    spend_cap_cents: 500_00,
+    ttl_seconds: 60 * 60 * 24 * 90, // 90 days
+  },
+});
+// Hand `delegation.redemption_url` to the delegate; they exchange for an at_*
+```
+
+</details>
+
+---
+
+## MCP server
+
+Prefer using Ovra straight from Claude / Cursor / any MCP-capable agent?
+The same surface lives in [`@ovra/mcp`](https://www.npmjs.com/package/@ovra/mcp)
+(10 tools). Add to `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ovra": {
+      "command": "npx",
+      "args": ["-y", "@ovra/mcp"],
+      "env": { "OVRA_API_KEY": "sk_test_…" }
+    }
+  }
+}
+```
+
+---
+
+## Publishing
+
+<details><summary>How releases ship (npm + GitHub Actions)</summary>
+
+The SDK is regenerated from `apps/api/openapi.json` whenever the spec or
+`packages/sdk/src` changes. The publish workflow at
+`.github/workflows/sdk-publish.yaml` is wired but currently **blocked on
+GitHub Actions billing**. Until that's resolved, releases ship manually:
+
+```sh
+# From the repo root
+pnpm run publish:sdk           # builds, tests, publishes (refuses dirty tree)
+pnpm run publish:sdk:dry       # rehearsal — no actual npm publish
 ```
 
-The full inventory is in `apps/api/openapi.json` (single source of
-truth — the SDK is regenerated from it on every release).
+Or directly: `cd packages/sdk && pnpm run publish-manual`.
+
+The script enforces:
+- Clean working tree (refuses to publish over uncommitted changes)
+- Local version > current npm `latest`
+- Valid `npm whoami` (must be authenticated)
+- Regen + build + tests must all pass before `npm publish`
+
+</details>
+
+---
 
 ## License
 
-Commercial — see [LICENSE](./LICENSE). The Ovra service requires a paid
-subscription.
+UNLICENSED — internal use only until the public release lands. See the
+repo for the in-progress [terms](https://github.com/ovra/ovra/blob/main/LICENSE).