@haven_ai/sdk 0.1.1 → 0.1.2

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,7 +92,9 @@ 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
@@ -147,9 +149,9 @@ 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 |
 
 ## Configuration
 
@@ -167,33 +169,49 @@ 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, 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.
 
 ```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') {
+  // Retry the original paid API request.
+}
 ```
 
 ## 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
   }