@haven_ai/sdk 0.1.1 → 0.1.3

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript SDK for [Haven](https://github.com/d-hinders/Haven-AI) — agent wallet infrastructure for the autonomous economy.
 
-Haven gives AI agents the ability to hold, send, and receive money within strict, user-defined guardrails. This SDK makes it trivial to integrate Haven payments into any agent.
+Haven lets AI agents request and sign payments within strict, user-approved on-chain guardrails. This SDK makes it straightforward to integrate Haven payment requests into any agent without giving Haven custody of user or agent keys.
 
 ## Install
 
@@ -92,11 +92,18 @@ const result = await haven.waitForConfirmation(intent.paymentId)
 
 ## x402 Protocol Support
 
-Haven natively supports the [x402](https://x402.org) payment protocol. When an API returns HTTP 402, Haven evaluates the payment against policy, funds the agent delegate wallet from the Haven wallet, signs the merchant's standard x402 payment payload, and retries automatically:
+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:
 
 ```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
@@ -105,7 +112,9 @@ 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)
 }
@@ -147,9 +156,10 @@ for (const block of response.content) {
 
 | Tool | Description |
 |------|-------------|
-| `make_payment` | Send a payment from the Haven-managed Safe wallet |
-| `get_payment_status` | Check the status of a previously initiated payment |
-| `authorize_x402_payment` | Fund the agent wallet and return a payment header for an HTTP 402 resource |
+| `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,33 +177,78 @@ const haven = new HavenClient({
 
 ## Payments above the on-chain allowance
 
-Haven's policy lives entirely on the Safe AllowanceModule (token, amount,
-reset period). If an agent requests a payment above the remaining allowance,
-Haven does **not** reject it — it returns HTTP 202 with `status: 'pending_approval'`
-and queues it for the wallet owner to approve in the dashboard.
+Haven's policy lives on the Safe AllowanceModule (token, amount, reset period).
+If an agent requests a payment above the remaining allowance, Haven does **not**
+reject it — it returns HTTP 202 with `status: 'pending_approval'`, a
+`payment_id`, `phase`, and `next_action`, then queues it for the wallet owner
+to approve in the dashboard.
 
 Surface that to the user: the payment isn't dead, it's waiting for a human to
-sign off. Don't retry — the same request would just queue another approval.
+sign off. Check `getPaymentStatus(payment_id)` or the `get_payment_status`
+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
+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.
 
 ```typescript
 try {
   await haven.pay({ token: 'USDC', amount: '500', to: '0xabc...' })
 } catch (err) {
-  if (err instanceof HavenApiError && err.statusCode === 202) {
-    // err.body.payment_id, err.body.remaining, err.body.requested
+  if (err instanceof HavenPaymentStateError && err.nextAction === 'wait_for_user_approval') {
+    console.log(err.paymentId, err.phase, err.nextAction)
     console.log('Queued for owner approval — visible in the Haven dashboard.')
   }
 }
+
+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',
+  })
+  const data = await response.json()
+}
 ```
 
+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.
+
 ## Error Handling
 
 ```typescript
-import { HavenApiError, HavenSigningError, HavenTimeoutError } from '@haven_ai/sdk'
+import { HavenApiError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError } from '@haven_ai/sdk'
 
 try {
   await haven.pay({ token: 'EURe', amount: '5.00', to: '0xabc...' })
 } catch (err) {
+  if (err instanceof HavenPaymentStateError) {
+    console.log(err.paymentId, err.phase, err.nextAction)
+  }
   if (err instanceof HavenApiError) {
     console.log(err.statusCode, err.message) // API returned an error
   }