@haven_ai/sdk 0.1.22-alpha.0 → 0.1.23-alpha.1

package/README.md

@@ -183,7 +183,6 @@ for (const block of response.content) {
 | `get_allowances` | Read configured and on-chain allowance state, including spent and remaining allowance |
 | `authorize_x402_payment` | Authorize a policy-limited x402 payment and return a payment header for an HTTP 402 resource |
 | `resume_x402_payment` | Resume an approved x402 payment and return a merchant payment header without creating a duplicate approval |
-| `authorize_machine_payment` | Authorize an internal Haven MPP demo challenge and return proof details |
 
 Use `get_allowances` for allowance, budget, spend-limit, remaining amount, reset-period, or "what can I spend?" questions. Payment tools still require the agent-held delegate key and on-chain Safe allowance state; the Haven API key identifies the agent but does not authorize spending by itself.
 
@@ -209,10 +208,13 @@ The backend serves an OpenAPI 3.1 contract at:
 - Local development: `http://localhost:3001/openapi.json`
 
 The spec covers the agent-facing payment surface: agents, direct payments,
-payment status, x402 authorization, MPP demo authorization, resume-state
-rehydration, machine-payment receipts, and transactions. Its security scheme is
-deliberate: the Haven API key identifies the agent, but payment authority still
-requires an agent-held delegate signature and on-chain Safe allowance state.
+payment status, x402 authorization, resume-state rehydration, machine-payment
+receipts, and transactions. `POST /machine-payments/authorize` (the legacy
+internal MPP demo challenge flow) is retired — it now refuses unconditionally
+with HTTP 410; use the x402 flow for agent-to-merchant payments. Its security
+scheme is deliberate: the Haven API key identifies the agent, but payment
+authority still requires an agent-held delegate signature and on-chain Safe
+allowance state.
 
 ## Agent payment state machine
 
@@ -220,7 +222,7 @@ Every payment or approval state returned by Haven includes:
 
 - `phase`: where the Haven-side payment currently is.
 - `nextAction`: the stable action an agent should take next.
-- `rail`: which payment rail produced the state. Categorical values (`direct`, `x402`, `mpp`) appear on resume-state discriminators; granular values (`mpp_demo`, `mpp_crypto`, `stripe_deposit`, `spt`) appear on response bodies.
+- `rail`: which payment rail produced the state. Categorical values (`direct`, `x402`, `mpp`) appear on resume-state discriminators; granular values (`mpp_demo`, `mpp_crypto`, `stripe_deposit`, `spt`) appear on response bodies. The `mpp` resume-state shape is a historical read only — the SDK no longer exposes a client method that acts on it (`mpp_demo` is retired, #1328).
 - `message`: human-readable guidance for the same state.
 
 The enum values and JSON Schema fragments are exported from `@haven_ai/sdk`:
@@ -323,7 +325,9 @@ Hosted MCP and signer tools also return stable `code` values on recoverable x402
 
 | `code` | Meaning | Agent recovery |
 |--------|---------|----------------|
-| `PRICE_EXCEEDS_MAX` | The merchant-authoritative x402 price is above the caller's `max_amount` cap. No funding transfer was created. | Tell the user the live price exceeded the cap and retry only after they confirm a higher `max_amount`. |
+| `PRICE_EXCEEDS_MAX` | The merchant-authoritative x402 price is above the caller's spending cap. No funding transfer was created. | Tell the user the live price exceeded the cap and retry only after they confirm a higher one. |
+| `AMBIGUOUS_MAX_AMOUNT` | Both `max_amount` (atomic units) and `max_amount_human` (whole tokens) were sent for one purchase. Nothing was contacted and nothing was spent. | Re-send with exactly one — `max_amount_human` for a cap the user stated in tokens, `max_amount` for an exact atomic figure. |
+| `MAX_AMOUNT_UNCONVERTIBLE` | `max_amount_human` could not be converted against this quote's asset — its decimals are unknown to Haven, or the cap has more decimal places than the asset supports. Nothing was spent. | Round the cap to the asset's decimals, or re-send it as an exact atomic `max_amount`. |
 | `PAYMENT_WINDOW_EXPIRED` | The funding/quote window closed before `haven_x402_sign_header`, `haven_submit`, or `haven_complete_mcp_tool` could finish. | Re-run `haven_pay_mcp_tool` with the same `idempotency_key`, then sign and complete the fresh quote. Payloads include `retry_with_new_quote: true`. |
 | `MERCHANT_REJECTED_AFTER_FUNDING` | Haven's funding leg succeeded, but the merchant rejected the paid retry. | Stop retrying the merchant and call `haven_sweep_delegate` so the user can recover stranded delegate USDC. |