@haven_ai/sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # @haven_ai/sdk
 
-TypeScript SDK for [Haven](https://github.com/d-hinders/Haven) — agent wallet infrastructure for the autonomous economy.
+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.
 
@@ -32,6 +32,35 @@ console.log(result.txHash)      // 0x...
 console.log(result.explorerUrl) // https://gnosisscan.io/tx/0x... (or basescan.org for Base)
 ```
 
+## Try it live — zero setup
+
+Haven hosts a demo endpoint you can hit immediately after creating an agent:
+
+```typescript
+import { HavenClient } from '@haven_ai/sdk'
+
+const haven = new HavenClient({
+  apiKey: process.env.HAVEN_API_KEY!,       // from Haven dashboard
+  delegateKey: process.env.DELEGATE_KEY!,   // agent's delegate private key
+  baseUrl: 'https://havenbackend-production-8a00.up.railway.app', // hosted Haven, or your self-hosted URL
+})
+
+// haven.fetch handles 402 → pay → retry automatically
+const response = await haven.fetch(
+  'https://havenbackend-production-8a00.up.railway.app/demo/x402/data',
+)
+const data = await response.json()
+
+console.log(data.message)     // "You paid! Here's your demo data."
+console.log(data.fact)        // a fun fact about the agent economy
+console.log(data.explorerUrl) // link to the on-chain payment tx
+```
+
+Tell your agent:
+> "Use Haven to fetch `https://havenbackend-production-8a00.up.railway.app/demo/x402/data` and show me what came back."
+
+The agent will pay a tiny amount (~0.01 EURe on Gnosis Chain), receive the demo payload, and you'll see the payment in your Haven dashboard activity feed — no local server or extra config required.
+
 ## Supported Networks & Tokens
 
 | Network | CAIP-2 | Tokens |
@@ -63,7 +92,7 @@ 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, executes from the Safe, and retries automatically:
+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:
 
 ```typescript
 // Automatic — fetch() intercepts 402, pays, and retries
@@ -71,17 +100,20 @@ const response = await haven.fetch('https://paid-api.example.com/data')
 const data = await response.json()
 
 // Manual — parse and authorize the 402 yourself
-import { parsePaymentRequired } from '@haven_ai/sdk'
+import { parsePaymentRequiredResponse } from '@haven_ai/sdk'
 
 const apiResponse = await fetch('https://paid-api.example.com/data')
 if (apiResponse.status === 402) {
-  const paymentRequired = parsePaymentRequired(apiResponse)
+  const paymentRequired = await parsePaymentRequiredResponse(apiResponse)
   const receipt = await haven.authorizeX402(paymentRequired)
+  // Retry with { 'X-PAYMENT': receipt.paymentHeader }
   console.log(receipt.explorerUrl)
 }
 ```
 
-Supported x402 networks: `eip155:100` (Gnosis Chain) and `eip155:8453` (Base).
+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.
 
 ## AI Agent Integration
 
@@ -97,7 +129,7 @@ const haven = new HavenClient({ apiKey, delegateKey })
 const anthropic = new Anthropic()
 
 const response = await anthropic.messages.create({
-  model: 'claude-opus-4-6',
+  model: 'claude-opus-4-7',
   tools: havenTools.claude(),  // or havenTools.openai() for OpenAI
   messages: [{ role: 'user', content: 'Pay 5 EURe to 0xabc for API access' }],
 })
@@ -117,7 +149,7 @@ for (const block of response.content) {
 |------|-------------|
 | `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` | Pay for an HTTP 402 resource via the x402 protocol |
+| `authorize_x402_payment` | Fund the agent wallet and return a payment header for an HTTP 402 resource |
 
 ## Configuration
 
@@ -126,12 +158,34 @@ const haven = new HavenClient({
   apiKey: 'sk_agent_xxx',          // required — Haven agent API key
   delegateKey: '0x...',             // optional — enables .pay() and .sign()
   baseUrl: 'http://localhost:3001', // default
+  x402Wallet: '0x...',              // optional fallback when no delegate key is configured
   requestTimeout: 30000,           // per-request timeout (ms)
   confirmationTimeout: 90000,      // polling timeout (ms)
   pollingInterval: 3000,           // polling interval (ms)
 })
 ```
 
+## 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.
+
+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.
+
+```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
+    console.log('Queued for owner approval — visible in the Haven dashboard.')
+  }
+}
+```
+
 ## Error Handling
 
 ```typescript

package/dist/index.cjs

@@ -1,8 +1,11 @@
 'use strict';
 
+var schemes = require('x402/schemes');
+var accounts = require('viem/accounts');
 var ethers = require('ethers');
+var crypto = require('crypto');
 
-// src/signer.ts
+// src/client.ts
 
 // src/types.ts
 var HavenError = class extends Error {
@@ -72,11 +75,66 @@ function verifySignature(hash, signature, expectedAddress) {
     return false;
   }
 }
-
-// src/x402.ts
+var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+var X402_IDEMPOTENCY_BUCKET_MS = 3e5;
+function decodeBase64Json(value, label) {
+  try {
+    return JSON.parse(atob(value));
+  } catch {
+    throw new Error(`Failed to decode ${label}`);
+  }
+}
+function normalizePaymentOption(value) {
+  const candidate = value;
+  if (!candidate || typeof candidate !== "object" || typeof candidate.scheme !== "string" || typeof candidate.network !== "string" || typeof candidate.asset !== "string" || typeof candidate.payTo !== "string") {
+    return null;
+  }
+  const amount = typeof candidate.amount === "string" ? candidate.amount : typeof candidate.maxAmountRequired === "string" ? candidate.maxAmountRequired : null;
+  if (!amount) return null;
+  return {
+    scheme: candidate.scheme,
+    network: candidate.network,
+    amount,
+    maxAmountRequired: candidate.maxAmountRequired,
+    resource: candidate.resource,
+    description: candidate.description,
+    mimeType: candidate.mimeType,
+    asset: candidate.asset,
+    payTo: candidate.payTo,
+    maxTimeoutSeconds: candidate.maxTimeoutSeconds ?? 30,
+    extra: candidate.extra
+  };
+}
+function normalizePaymentRequired(value) {
+  const candidate = value;
+  if (!candidate || typeof candidate !== "object" || typeof candidate.x402Version !== "number" || !Array.isArray(candidate.accepts)) {
+    return null;
+  }
+  const accepts = candidate.accepts.map((option) => normalizePaymentOption(option)).filter((option) => !!option);
+  if (accepts.length === 0) return null;
+  const first = accepts[0];
+  const resourceUrl = candidate.resource?.url ?? first.resource;
+  if (!resourceUrl) return null;
+  const resource = {
+    url: resourceUrl,
+    description: candidate.resource?.description ?? first.description,
+    mimeType: candidate.resource?.mimeType ?? first.mimeType
+  };
+  return {
+    x402Version: candidate.x402Version,
+    resource,
+    accepts,
+    error: candidate.error
+  };
+}
 var SUPPORTED_X402_NETWORKS = {
   "eip155:100": "Gnosis Chain",
-  "eip155:8453": "Base"
+  "eip155:8453": "Base",
+  "base": "Base"
+};
+var STANDARD_X402_NETWORKS = {
+  "eip155:8453": "base",
+  "base": "base"
 };
 var GNOSIS_TOKENS = {
   "0x0000000000000000000000000000000000000000": { symbol: "xDAI", decimals: 18 },
@@ -89,29 +147,41 @@ var BASE_TOKENS = {
 };
 var NETWORK_TOKENS = {
   "eip155:100": GNOSIS_TOKENS,
-  "eip155:8453": BASE_TOKENS
+  "eip155:8453": BASE_TOKENS,
+  "base": BASE_TOKENS
 };
 function parsePaymentRequired(response) {
   const v2Header = response.headers.get("PAYMENT-REQUIRED");
   if (v2Header) {
-    try {
-      return JSON.parse(atob(v2Header));
-    } catch {
-      throw new Error("Failed to decode PAYMENT-REQUIRED header");
-    }
+    const parsed = normalizePaymentRequired(
+      decodeBase64Json(v2Header, "PAYMENT-REQUIRED header")
+    );
+    if (parsed) return parsed;
   }
   const v1Header = response.headers.get("X-PAYMENT");
   if (v1Header) {
-    try {
-      return JSON.parse(atob(v1Header));
-    } catch {
-      throw new Error("Failed to decode X-PAYMENT header");
-    }
+    const parsed = normalizePaymentRequired(
+      decodeBase64Json(v1Header, "X-PAYMENT header")
+    );
+    if (parsed) return parsed;
   }
   throw new Error(
     "No x402 payment headers found in 402 response. Expected PAYMENT-REQUIRED (v2) or X-PAYMENT (v1) header."
   );
 }
+async function parsePaymentRequiredResponse(response) {
+  try {
+    return parsePaymentRequired(response);
+  } catch (headerErr) {
+    try {
+      const body = await response.clone().json();
+      const parsed = normalizePaymentRequired(body);
+      if (parsed) return parsed;
+    } catch {
+    }
+    throw headerErr;
+  }
+}
 function selectPaymentOption(accepts) {
   if (!accepts || accepts.length === 0) return null;
   for (const opt of accepts) {
@@ -127,13 +197,61 @@ function selectPaymentOption(accepts) {
   }
   return null;
 }
+function selectStandardPaymentOption(accepts) {
+  if (!accepts || accepts.length === 0) return null;
+  for (const opt of accepts) {
+    if (opt.scheme === "exact" && opt.network in STANDARD_X402_NETWORKS && opt.asset.toLowerCase() === BASE_USDC_ADDRESS) {
+      return opt;
+    }
+  }
+  return null;
+}
+function toStandardPaymentRequirements(paymentRequired, option) {
+  const network = STANDARD_X402_NETWORKS[option.network];
+  if (!network) {
+    throw new Error(`x402 exact payments are not supported on ${option.network}`);
+  }
+  if (option.scheme !== "exact") {
+    throw new Error(`Unsupported x402 scheme: ${option.scheme}`);
+  }
+  return {
+    scheme: "exact",
+    network,
+    maxAmountRequired: option.maxAmountRequired ?? option.amount,
+    resource: option.resource ?? paymentRequired.resource.url,
+    description: option.description ?? paymentRequired.resource.description ?? "Haven x402 payment",
+    mimeType: option.mimeType ?? paymentRequired.resource.mimeType ?? "application/octet-stream",
+    payTo: option.payTo,
+    asset: option.asset,
+    maxTimeoutSeconds: option.maxTimeoutSeconds,
+    extra: option.extra
+  };
+}
+function buildX402IdempotencyKey(paymentRequired, option, now = Date.now()) {
+  const bucket = Math.floor(now / X402_IDEMPOTENCY_BUCKET_MS);
+  const material = [
+    paymentRequired.resource.url,
+    paymentRequired.resource.description ?? "",
+    option.payTo.toLowerCase(),
+    option.asset.toLowerCase(),
+    option.amount,
+    option.network,
+    bucket
+  ].join("|");
+  return `x402:${crypto.createHash("sha256").update(material).digest("hex").slice(0, 16)}`;
+}
 function encodePaymentProof(receipt) {
   const payload = {
     x402Version: 2,
+    resource: receipt.resourceUrl ? { url: receipt.resourceUrl } : void 0,
+    accepted: receipt.accepted,
     payload: {
+      type: "haven_tx_hash",
       txHash: receipt.txHash,
       paymentId: receipt.paymentId,
-      settledVia: "haven"
+      settledVia: "haven",
+      payer: receipt.payer,
+      chainId: receipt.chainId
     }
   };
   return btoa(JSON.stringify(payload));
@@ -146,25 +264,35 @@ var CHAIN_EXPLORER_TX = {
   8453: "https://basescan.org/tx"
 };
 function buildExplorerUrl(chainId, txHash) {
-  const base = CHAIN_EXPLORER_TX[chainId ?? 100] ?? CHAIN_EXPLORER_TX[100];
+  const base = CHAIN_EXPLORER_TX[chainId ?? 8453] ?? CHAIN_EXPLORER_TX[8453];
   return `${base}/${txHash}`;
 }
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
 var DEFAULT_POLLING_INTERVAL = 3e3;
+function chainIdFromNetwork(network) {
+  if (network === "base") return 8453;
+  if (!network?.startsWith("eip155:")) return void 0;
+  const chainId = Number(network.slice("eip155:".length));
+  return Number.isFinite(chainId) ? chainId : void 0;
+}
 var HavenClient = class {
   apiKey;
   delegateKey;
   baseUrl;
+  x402Wallet;
   requestTimeout;
   confirmationTimeout;
   pollingInterval;
+  inFlightX402 = /* @__PURE__ */ new Map();
+  x402ReceiptCache = /* @__PURE__ */ new Map();
   /** Delegate address derived from the private key (if provided) */
   delegateAddress;
   constructor(config) {
     this.apiKey = config.apiKey;
     this.delegateKey = config.delegateKey;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.x402Wallet = config.x402Wallet;
     this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
     this.confirmationTimeout = config.confirmationTimeout ?? DEFAULT_CONFIRMATION_TIMEOUT;
     this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
@@ -204,6 +332,13 @@ var HavenClient = class {
       amount: request.amount,
       to: request.to
     });
+    if (raw.status === "pending_approval") {
+      throw new HavenApiError(
+        `Payment exceeds the on-chain allowance and was queued for owner approval (payment_id: ${raw.payment_id}).`,
+        202,
+        raw
+      );
+    }
     return {
       paymentId: raw.payment_id,
       status: "pending_signature",
@@ -271,8 +406,9 @@ var HavenClient = class {
   /**
    * Authorize an x402 payment.
    *
-   * Takes the parsed PaymentRequired from a 402 response, selects a
-   * compatible payment option, signs and executes the payment through Haven.
+   * Takes the parsed PaymentRequired from a 402 response, selects a compatible
+   * option, funds the delegate wallet through Haven, and returns the standard
+   * x402 header that the merchant can verify and settle.
    *
    * Requires `delegateKey` to be set in the client config.
    */
@@ -282,23 +418,43 @@ var HavenClient = class {
         "delegateKey is required for x402 payments. Pass it in the HavenClient config."
       );
     }
-    const option = selectPaymentOption(paymentRequired.accepts);
+    if (!this.delegateAddress) {
+      throw new HavenSigningError("delegateAddress could not be derived from delegateKey.");
+    }
+    const option = selectStandardPaymentOption(paymentRequired.accepts);
     if (!option) {
       throw new HavenApiError(
-        "No compatible payment option found in x402 requirements. Haven supports Gnosis Chain (eip155:100) and Base (eip155:8453).",
+        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
         400
       );
     }
+    const idempotencyKey = buildX402IdempotencyKey(paymentRequired, option);
+    const cached = this.x402ReceiptCache.get(idempotencyKey);
+    if (cached && cached.expiresAt > Date.now()) return cached.receipt;
+    const inFlight = this.inFlightX402.get(idempotencyKey);
+    if (inFlight) return inFlight;
+    const promise = this.authorizeStandardX402(paymentRequired, option, idempotencyKey);
+    this.inFlightX402.set(idempotencyKey, promise);
+    try {
+      return await promise;
+    } finally {
+      this.inFlightX402.delete(idempotencyKey);
+    }
+  }
+  async authorizeStandardX402(paymentRequired, option, idempotencyKey) {
+    const paymentHeader = await this.createStandardX402Header(paymentRequired, option);
     const raw = await this.post("/x402", {
       url: paymentRequired.resource.url,
-      payTo: option.payTo,
+      payTo: this.delegateAddress,
+      merchantPayTo: option.payTo,
       amount: option.amount,
       asset: option.asset,
       network: option.network,
-      description: paymentRequired.resource.description
+      description: paymentRequired.resource.description,
+      idempotencyKey
     });
     if (raw.success && raw.tx_hash) {
-      return {
+      const receipt2 = {
         success: true,
         paymentId: raw.payment_id,
         txHash: raw.tx_hash,
@@ -306,8 +462,15 @@ var HavenClient = class {
         amount: raw.amount ?? "",
         to: raw.to ?? "",
         resourceUrl: paymentRequired.resource.url,
-        explorerUrl: raw.explorer_url ?? (raw.tx_hash ? buildExplorerUrl(raw.chain_id, raw.tx_hash) : "")
+        explorerUrl: raw.explorer_url ?? (raw.tx_hash ? buildExplorerUrl(raw.chain_id, raw.tx_hash) : ""),
+        accepted: option,
+        paymentHeader,
+        merchantTo: raw.merchant_to ?? option.payTo,
+        payer: raw.payer ?? raw.safe_address,
+        chainId: raw.chain_id ?? chainIdFromNetwork(option.network)
       };
+      this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
+      return receipt2;
     }
     if (!raw.sign_data?.hash) {
       throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
@@ -324,7 +487,7 @@ var HavenClient = class {
         execResult
       );
     }
-    return {
+    const receipt = {
       success: true,
       paymentId: raw.payment_id,
       txHash: execResult.tx_hash ?? "",
@@ -332,8 +495,15 @@ var HavenClient = class {
       amount: execResult.amount ?? raw.amount ?? "",
       to: execResult.to ?? raw.to ?? "",
       resourceUrl: paymentRequired.resource.url,
-      explorerUrl: execResult.explorer_url ?? (execResult.tx_hash ? buildExplorerUrl(execResult.chain_id, execResult.tx_hash) : "")
+      explorerUrl: execResult.explorer_url ?? (execResult.tx_hash ? buildExplorerUrl(execResult.chain_id, execResult.tx_hash) : ""),
+      accepted: option,
+      paymentHeader,
+      merchantTo: option.payTo,
+      payer: raw.payer ?? raw.safe_address ?? raw.sign_data?.components.safe,
+      chainId: execResult.chain_id ?? raw.chain_id ?? chainIdFromNetwork(option.network)
     };
+    this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
+    return receipt;
   }
   /**
    * Fetch wrapper that automatically handles HTTP 402 responses.
@@ -349,21 +519,82 @@ var HavenClient = class {
    * Requires `delegateKey` to be set in the client config.
    */
   async fetch(url, init) {
-    const response = await globalThis.fetch(url, init);
+    const initialInit = this.withX402Wallet(init, this.x402PayerAddress());
+    const response = await globalThis.fetch(url, initialInit);
     if (response.status !== 402) return response;
     let paymentRequired;
     try {
-      paymentRequired = parsePaymentRequired(response);
+      paymentRequired = await parsePaymentRequiredResponse(response);
     } catch {
       return response;
     }
     const receipt = await this.authorizeX402(paymentRequired);
-    const retryHeaders = new Headers(init?.headers);
-    retryHeaders.set("PAYMENT-SIGNATURE", encodePaymentProof(receipt));
-    return globalThis.fetch(url, {
-      ...init,
+    if (!receipt.accepted) {
+      throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
+    }
+    if (!receipt.paymentHeader) {
+      throw new HavenApiError("No x402 payment header was returned for payment retry", 500);
+    }
+    const retryHeaders = new Headers(initialInit?.headers);
+    retryHeaders.set("X-PAYMENT", receipt.paymentHeader);
+    const retryResponse = await globalThis.fetch(url, {
+      ...initialInit,
       headers: retryHeaders
     });
+    if (retryResponse.status === 402) {
+      throw new HavenApiError(
+        "x402 retry was rejected after Haven funded the delegate wallet; reconciliation may be required.",
+        402,
+        {
+          marker: "x402_retry_rejected_after_funding",
+          payment_id: receipt.paymentId,
+          tx_hash: receipt.txHash,
+          resource_url: receipt.resourceUrl,
+          merchant_to: receipt.merchantTo,
+          delegate_to: receipt.to
+        }
+      );
+    }
+    return retryResponse;
+  }
+  async createStandardX402Header(paymentRequired, option) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError("delegateKey is required to sign x402 payment headers.");
+    }
+    const account = accounts.privateKeyToAccount(this.delegateKey);
+    const requirements = toStandardPaymentRequirements(paymentRequired, option);
+    const header = await schemes.exact.evm.createPaymentHeader(
+      account,
+      paymentRequired.x402Version,
+      requirements
+    );
+    if (paymentRequired.x402Version < 2) return header;
+    const payment = decodeBase64Json2(header);
+    return btoa(JSON.stringify({
+      x402Version: paymentRequired.x402Version,
+      accepted: option,
+      payload: payment.payload
+    }));
+  }
+  cacheX402Receipt(idempotencyKey, paymentHeader, receipt) {
+    const expiresAt = getPaymentHeaderValidBefore(paymentHeader);
+    if (expiresAt > Date.now()) {
+      this.x402ReceiptCache.set(idempotencyKey, { expiresAt, receipt });
+    }
+  }
+  x402PayerAddress() {
+    return this.delegateAddress ?? this.x402Wallet;
+  }
+  withX402Wallet(init, wallet = this.x402PayerAddress()) {
+    if (!wallet) return init;
+    const headers = new Headers(init?.headers);
+    if (!headers.has("x402-wallet")) {
+      headers.set("x402-wallet", wallet);
+    }
+    return {
+      ...init,
+      headers
+    };
   }
   // ── Tool Execution (for agent frameworks) ────────────────────────
   /**
@@ -426,7 +657,11 @@ var HavenClient = class {
           amount: receipt.amount,
           to: receipt.to,
           resource_url: receipt.resourceUrl,
-          explorer_url: receipt.explorerUrl
+          explorer_url: receipt.explorerUrl,
+          payment_header: receipt.paymentHeader,
+          merchant_to: receipt.merchantTo,
+          payer: receipt.payer,
+          chain_id: receipt.chainId
         };
       } catch (err) {
         return {
@@ -512,6 +747,21 @@ var HavenClient = class {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function getPaymentHeaderValidBefore(paymentHeader) {
+  try {
+    const payment = decodeBase64Json2(
+      paymentHeader
+    );
+    const payload = payment.payload;
+    const validBeforeSeconds = Number(payload.authorization?.validBefore);
+    if (Number.isFinite(validBeforeSeconds)) return validBeforeSeconds * 1e3;
+  } catch {
+  }
+  return 0;
+}
+function decodeBase64Json2(value) {
+  return JSON.parse(atob(value));
+}
 
 // src/tools.ts
 var makePaymentSchema = {
@@ -578,7 +828,7 @@ var authorizeX402Schema = {
 };
 var MAKE_PAYMENT_DESCRIPTION = "Send a payment from the Haven-managed Safe wallet. The payment will be validated against the agent's on-chain spending policy. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
 var GET_STATUS_DESCRIPTION = "Check the status of a previously initiated payment. Returns the current status, transaction hash (if confirmed), and payment details.";
-var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns 402 with x402 payment requirements, use this tool to pay and get access. Haven evaluates the payment against policy and executes from the Safe wallet.";
+var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns 402 with x402 payment requirements, use this tool to fund the agent wallet and get a merchant payment header. Haven evaluates the payment against policy before moving funds from the Haven wallet. Use the returned payment_header as the X-PAYMENT header on the retry request.";
 function claudeTools() {
   return [
     {
@@ -642,6 +892,7 @@ exports.addressFromKey = addressFromKey;
 exports.encodePaymentProof = encodePaymentProof;
 exports.havenTools = havenTools;
 exports.parsePaymentRequired = parsePaymentRequired;
+exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
 exports.selectPaymentOption = selectPaymentOption;
 exports.signHash = signHash;
 exports.verifySignature = verifySignature;