@haven_ai/sdk 0.1.3 → 0.1.5

package/README.md

@@ -68,6 +68,15 @@ The agent will pay a tiny amount (~0.01 EURe on Gnosis Chain), receive the demo
 | Gnosis Chain | `eip155:100` | EURe, USDC.e, xDAI |
 | Base | `eip155:8453` | USDC, ETH |
 
+## Credential Lifecycle
+
+- The Haven API key identifies the agent. It is not payment authority.
+- The delegate key signs payment payloads locally. Haven's backend never receives it.
+- On-chain Safe AllowanceModule state enforces the agent budget.
+- `getAllowances()` / `get_allowances` is the right path for budget, remaining amount, reset period, or "what can I spend?" questions.
+- If an API key is exposed or lost, rotate it from the Haven agent detail page. The new key is shown once and the old key stops working.
+- If a delegate key is exposed or lost, pause or revoke the agent and create a new signing path.
+
 ## Step-by-Step API
 
 For agents that need control over each step (e.g., external signing):
@@ -94,7 +103,7 @@ const result = await haven.waitForConfirmation(intent.paymentId)
 
 Production merchant acceptance, facilitator, settlement, fiat, or acquiring functionality needs separate product and legal review under the repo's [CASP / MiCA guardrails](../../docs/regulatory/casp-risk-guardrails.md). The hosted x402 endpoint is an internal technical demo, not a merchant settlement product.
 
-Haven natively supports the [x402](https://x402.org) payment protocol. When an API returns HTTP 402, the SDK evaluates the challenge against the agent's approved limits, uses the configured delegate key for the required signature, and retries automatically:
+The SDK supports [x402](https://x402.org) client flows. When an API returns HTTP 402, the SDK evaluates the challenge against the agent's approved limits, uses the configured delegate key for the required signature, and retries automatically:
 
 ```typescript
 // Automatic — fetch() intercepts 402, pays, and retries.
@@ -120,6 +129,26 @@ if (apiResponse.status === 402) {
 }
 ```
 
+For agents that need to inspect the price before paying, use the quote-first
+path. `quoteX402()` probes the merchant and parses the HTTP 402 response, but it
+does not create a Haven payment, approval request, signature, or on-chain
+transaction.
+
+```typescript
+const quote = await haven.quoteX402(
+  'https://paid-api.example.com/data',
+  undefined,
+  { idempotencyKey: 'paid-api-data-2026-05-22' },
+)
+
+if (Number(quote.amount) > 0.05) {
+  throw new Error(`Price ${quote.amount} ${quote.token} is above the user cap`)
+}
+
+const response = await haven.payX402Quote(quote)
+const data = await response.json()
+```
+
 Merchant-verified x402 retries use the official EIP-3009 `exact` scheme on Base USDC (`base` / `eip155:8453`) and send the payment as `X-PAYMENT`. Haven's older tx-hash proof helper remains exported for Haven-native integrations, but `haven.fetch()` does not send `PAYMENT-SIGNATURE`.
 
 For standard x402, the `x402-wallet` identity is the agent delegate wallet, because that is the wallet that signs and settles the merchant payment. Integrations that scope access by Haven wallet/Safe address should use a Haven-native flow instead of standard merchant x402.
@@ -158,8 +187,12 @@ for (const block of response.content) {
 |------|-------------|
 | `make_payment` | Request and sign a payment from the user-controlled Safe within approved limits |
 | `get_payment_status` | Check the status of a payment intent or approval request |
+| `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.
 
 ## Configuration
 
@@ -175,6 +208,114 @@ const haven = new HavenClient({
 })
 ```
 
+## OpenAPI
+
+The backend serves an OpenAPI 3.1 contract at:
+
+- Production: `https://havenbackend-production-8a00.up.railway.app/openapi.json`
+- 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.
+
+## Agent payment state machine
+
+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.
+- `message`: human-readable guidance for the same state.
+
+The enum values and JSON Schema fragments are exported from `@haven_ai/sdk`:
+
+```typescript
+import {
+  AgentPaymentNextAction,
+  AgentPaymentNextActionSchema,
+  AgentPaymentPhase,
+  AgentPaymentPhaseSchema,
+  AgentPaymentRail,
+  AgentPaymentRailSchema,
+} from '@haven_ai/sdk'
+```
+
+### Flow diagram
+
+```text
+                                ┌─────────────────────────┐
+                                │ agent_signature_required│
+                                └──────────┬──────────────┘
+                                           │  sign_and_submit_payment
+                                           ▼
+                                ┌─────────────────────────┐
+                                │ payment_submitted       │
+                                └──────────┬──────────────┘
+                                           │  check_status_later
+                                ┌──────────┴──────────────┐
+                                ▼                         ▼
+                  ┌────────────────────────┐  ┌──────────────────────┐
+                  │ payment_confirmed (✔)  │  │ user_approval_required│
+                  └────────────────────────┘  └──────────┬───────────┘
+                                                         │ wait_for_user_approval
+                                       ┌─────────────────┴───────────────────┐
+                                       │ single-owner Safe                   │ multisig Safe
+                                       ▼                                     ▼
+                          ┌──────────────────────────┐    ┌──────────────────────────────────┐
+                          │ user_execution_required  │    │ waiting_for_additional_approvals │
+                          └──────────┬───────────────┘    └────────────────┬─────────────────┘
+                                     │ wait_for_user_to_complete_payment   │ wait_for_user_approval
+                                     └─────────────────┬───────────────────┘
+                                                       ▼
+                                          ┌───────────────────────┐
+                                          │ funding_sent          │
+                                          └──────────┬────────────┘
+                                                     │ retry_original_x402_request (x402)
+                                                     │ none (direct)
+                                                     ▼
+                                          ┌───────────────────────┐
+                                          │ executed (✔)          │
+                                          └───────────────────────┘
+
+Terminal from any non-confirmed phase:
+   rejected → stop_and_tell_user
+   failed   → stop_and_tell_user
+   expired  → request_again_if_user_still_wants_it
+```
+
+### `phase` reference
+
+| `phase` | Meaning | Terminal? |
+|---------|---------|-----------|
+| `agent_signature_required` | Haven prepared a payment intent; the agent must sign and submit. | no |
+| `payment_submitted` | Haven received the signed payment; the agent should poll for confirmation. | no |
+| `payment_confirmed` | Direct payment is confirmed on chain. | yes |
+| `user_approval_required` | Payment exceeds remaining on-chain allowance; wallet owner must approve in Haven. | no |
+| `user_execution_required` | Owner approved; the funding payment has not been sent yet (single-owner Safe). | no |
+| `waiting_for_additional_approvals` | Funding payment was proposed and is waiting for the remaining multisig approvals. | no |
+| `funding_sent` | Haven funding leg landed; the agent can continue the merchant/protocol leg. | no |
+| `rejected` | Owner rejected the request. | yes |
+| `expired` | Payment or approval request expired before completion. | yes |
+| `failed` | Haven could not complete the payment. | yes |
+
+The merchant settlement leg of x402 (and the MPP retry) is the agent's own request to the merchant — it does not have a Haven `phase`. The payment is `funding_sent` until the agent retries with `X-PAYMENT` (x402) or the MPP proof header; from Haven's perspective the payment becomes `executed` only after the agent successfully resumes.
+
+### `nextAction` reference
+
+| `nextAction` | What the agent should do |
+|--------------|--------------------------|
+| `sign_and_submit_payment` | Sign with the delegate key and submit the payment to Haven. |
+| `check_status_later` | Poll `getPaymentStatus(payment_id)` later. |
+| `none` | Stop polling; no more action is needed for this payment id. |
+| `wait_for_user_approval` | Tell the user the payment is waiting in Haven, then poll later. Do not create a duplicate payment. Same `nextAction` covers both the single-owner case (waiting for one owner to approve) and the multisig case (waiting for additional approvals after the first one). |
+| `wait_for_user_to_complete_payment` | The user approved the request; wait for them to finish the funding payment. |
+| `retry_original_x402_request` | Resume this payment id and retry the original x402 request with the merchant payment header. Do not start a new merchant session. |
+| `stop_and_tell_user` | Stop retrying and tell the user the payment failed or was rejected. |
+| `request_again_if_user_still_wants_it` | The request expired; ask again only if the user still wants the payment. |
+
 ## Payments above the on-chain allowance
 
 Haven's policy lives on the Safe AllowanceModule (token, amount, reset period).
@@ -189,33 +330,57 @@ tool later instead of retrying in a tight loop.
 
 For x402, approval resume is explicit. If `authorizeX402()` or `haven.fetch()`
 throws `HavenPaymentStateError` with `nextAction: 'wait_for_user_approval'`,
-stop and tell the user the request is waiting in Haven. Do not loop. After the
+stop and tell the user the Haven funding leg is waiting in Haven. Do not loop
+and do not start a new merchant or MCP session. Pending x402 states include the
+resource URL, merchant address, chain id, asset, network, atomic amount, and
+idempotency key so agents can explain what is waiting for approval. After the
 user approves, call `getPaymentStatus(payment_id)`. When Haven reports
 `nextAction: 'retry_original_x402_request'`, call `resumeX402Payment()` with the
 same user-intent idempotency key and the original x402 details.
 
+When the agent used `quoteX402()` / `payX402Quote()`, pending approval errors
+include a serializable `resumeState`. Persist it with the MCP session details
+and pass it back to `resumeX402Payment()` after approval.
+
+If the agent process restarts and only kept the `payment_id`, call
+`getResumeState(payment_id)` after approval to rehydrate the stored x402/MPP
+context from Haven, then pass that state to the matching resume helper. For
+POST-based merchant or MCP calls, rebuild the live request details before
+retrying; Haven stores payment context, not the agent's local request stream.
+
 ```typescript
+let resumeState
 try {
-  await haven.pay({ token: 'USDC', amount: '500', to: '0xabc...' })
+  await haven.payX402Quote(quote)
 } catch (err) {
-  if (err instanceof HavenPaymentStateError && err.nextAction === 'wait_for_user_approval') {
+  if (
+    err instanceof HavenPaymentStateError &&
+    err.nextAction === AgentPaymentNextAction.WaitForUserApproval &&
+    err.resumeState
+  ) {
+    resumeState = err.resumeState
     console.log(err.paymentId, err.phase, err.nextAction)
-    console.log('Queued for owner approval — visible in the Haven dashboard.')
+    console.log('Queued for owner approval. Save resumeState and wait.')
   }
 }
 
 const status = await haven.getPaymentStatus('approval-or-payment-id')
-if (status.nextAction === 'retry_original_x402_request') {
-  const response = await haven.resumeX402Payment({
-    paymentId: status.paymentId,
-    url: 'https://paid-api.example.com/data',
-    paymentRequired,
-    idempotencyKey: 'paid-api-data-2026-05-22',
-  })
+if (status.nextAction === AgentPaymentNextAction.RetryOriginalX402Request) {
+  resumeState ??= await haven.getResumeState(status.paymentId)
+  const response = await haven.resumeX402Payment(resumeState)
   const data = await response.json()
 }
 ```
 
+Think of manual approval x402 as two separate legs:
+
+- Haven funding leg: the user may need to approve a Safe AllowanceModule transfer
+  to the agent delegate wallet. Status fields such as `phase`,
+  `nextAction`, and `txHash` describe this leg.
+- Merchant x402 leg: after the funding leg is complete, the agent resumes the
+  same payment id and retries the original merchant request with `X-PAYMENT`.
+  Do not treat a new 402 probe or a new MCP session as a resume.
+
 For manual HTTP stacks, use `resumeAuthorizedX402()` to get the merchant header
 without retrying the request for you:
 
@@ -238,6 +403,10 @@ with the same `payment_id` and retry the original `tools/call` with
 `X-PAYMENT`. Use a stable `idempotencyKey` for the user intent so fresh merchant
 quotes or sessions do not become duplicate Haven approval requests.
 
+See [`examples/mcp-x402-sse.ts`](./examples/mcp-x402-sse.ts) for a complete
+MCP flow with initialize, `mcp-session-id`, JSON-RPC `tools/call`, quote
+inspection, user approval, saved resume state, and final retry.
+
 ## Error Handling
 
 ```typescript