@haven_ai/sdk 0.1.2 → 0.1.4

package/README.md

@@ -97,8 +97,13 @@ Production merchant acceptance, facilitator, settlement, fiat, or acquiring func
 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:
 
 ```typescript
-// Automatic — fetch() intercepts 402, pays, and retries
-const response = await haven.fetch('https://paid-api.example.com/data')
+// Automatic — fetch() intercepts 402, pays, and retries.
+// Use a stable idempotencyKey when one user intent may need manual approval.
+const response = await haven.fetch(
+  'https://paid-api.example.com/data',
+  undefined,
+  { idempotencyKey: 'paid-api-data-2026-05-22' },
+)
 const data = await response.json()
 
 // Manual — parse and authorize the 402 yourself
@@ -107,12 +112,34 @@ import { parsePaymentRequiredResponse } from '@haven_ai/sdk'
 const apiResponse = await fetch('https://paid-api.example.com/data')
 if (apiResponse.status === 402) {
   const paymentRequired = await parsePaymentRequiredResponse(apiResponse)
-  const receipt = await haven.authorizeX402(paymentRequired)
+  const receipt = await haven.authorizeX402(paymentRequired, {
+    idempotencyKey: 'paid-api-data-2026-05-22',
+  })
   // Retry with { 'X-PAYMENT': receipt.paymentHeader }
   console.log(receipt.explorerUrl)
 }
 ```
 
+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.
@@ -152,6 +179,7 @@ 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 |
 | `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 |
 
 ## Configuration
 
@@ -167,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).
@@ -179,28 +263,85 @@ Surface that to the user: the payment isn't dead, it's waiting for a human to
 sign off. Check `getPaymentStatus(payment_id)` or the `get_payment_status`
 tool later instead of retrying in a tight loop.
 
-For x402, the manual approval path has two steps. First, the user approves the
-funding movement from the Haven wallet to the agent's delegate wallet. Once
-Haven reports `next_action: 'retry_original_x402_request'`, retry the original
-paid API request so the SDK can attach the merchant x402 payment header. Do not
-rewrite the SDK while waiting for approval.
+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 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') {
-  // Retry the original paid API request.
+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:
+
+```typescript
+const receipt = await haven.resumeAuthorizedX402({
+  paymentId: status.paymentId,
+  paymentRequired,
+  idempotencyKey: 'paid-api-data-2026-05-22',
+})
+
+await fetch('https://paid-api.example.com/data', {
+  headers: { 'X-PAYMENT': receipt.paymentHeader! },
+})
+```
+
+For MCP/SSE x402 tools, keep the same MCP session and JSON-RPC payload where the
+merchant requires it: initialize, retain `mcp-session-id`, send the original
+`tools/call`, parse the 402 challenge, wait for approval if needed, then resume
+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