@haven_ai/sdk 0.1.3 → 0.1.4

package/README.md

@@ -120,6 +120,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.
@@ -175,6 +195,62 @@ 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, such as `direct`, `x402`, or `mpp`.
+- `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'
+```
+
+```text
+agent_signature_required -> payment_submitted -> payment_confirmed
+                              |
+                              v
+user_approval_required -> user_execution_required -> funding_sent
+                              |
+                              v
+             waiting_for_additional_approvals
+```
+
+| `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. |
+| `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 +265,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 +338,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