@haven_ai/sdk 0.1.6 → 0.1.7

package/README.md

@@ -32,9 +32,10 @@ console.log(result.txHash)      // 0x...
 console.log(result.explorerUrl) // https://gnosisscan.io/tx/0x... (or basescan.org for Base)
 ```
 
-## Try it live — zero setup
+## Pay for an x402 resource
 
-Haven hosts a demo endpoint you can hit immediately after creating an agent:
+Point `haven.fetch` at any HTTP resource gated behind `402 Payment Required` —
+the SDK detects the 402, pays through Haven, and retries automatically:
 
 ```typescript
 import { HavenClient } from '@haven_ai/sdk'
@@ -46,20 +47,12 @@ const haven = new HavenClient({
 })
 
 // haven.fetch handles 402 → pay → retry automatically
-const response = await haven.fetch(
-  'https://havenbackend-production-8a00.up.railway.app/demo/x402/data',
-)
+const response = await haven.fetch('https://your-x402-endpoint.example/resource')
 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.
+The payment fits within the agent's on-chain allowance (or is queued for your
+approval if it exceeds it), and shows up in your Haven dashboard activity feed.
 
 ## Supported Networks & Tokens
 

package/dist/index.cjs

@@ -29,7 +29,15 @@ var AgentPaymentPhase = {
   /** The payment or approval request expired before completion. */
   Expired: "expired",
   /** Haven could not complete the payment; the agent should stop and surface the failure. */
-  Failed: "failed"
+  Failed: "failed",
+  /**
+   * Pre-flight check determined the delegate's existing balance plus the
+   * remaining on-chain allowance cannot cover the requested amount, so no
+   * payment intent was created. Distinct from `UserApprovalRequired`: there
+   * is no approval that would fix this — the originating Safe needs more
+   * funds or the agent's per-token allowance needs to be raised first.
+   */
+  InsufficientFunds: "insufficient_funds"
 };
 var AgentPaymentNextAction = {
   /** Sign with the delegate key and submit the payment to Haven. */
@@ -47,7 +55,13 @@ var AgentPaymentNextAction = {
   /** Stop retrying this payment and tell the user what happened. */
   StopAndTellUser: "stop_and_tell_user",
   /** Ask again only if the user still wants the payment after expiry. */
-  RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it"
+  RequestAgainIfUserStillWantsIt: "request_again_if_user_still_wants_it",
+  /**
+   * Stop and tell the user that the originating Safe needs to be funded or
+   * the agent's per-token allowance needs to be raised before the payment
+   * can succeed. A user approval will not fix this state on its own.
+   */
+  FundSafeOrRaiseAllowance: "fund_safe_or_raise_allowance"
 };
 var AgentPaymentRail = {
   /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
@@ -78,7 +92,8 @@ var AgentPaymentPhaseDescriptions = {
   [AgentPaymentPhase.FundingSent]: "The Haven funding leg was sent; the agent can continue the merchant/protocol leg.",
   [AgentPaymentPhase.Rejected]: "The wallet owner rejected the request; the agent should stop and tell the user.",
   [AgentPaymentPhase.Expired]: "The payment or approval request expired before completion.",
-  [AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure."
+  [AgentPaymentPhase.Failed]: "Haven could not complete the payment; the agent should stop and surface the failure.",
+  [AgentPaymentPhase.InsufficientFunds]: "Pre-flight check determined the delegate balance plus the remaining on-chain allowance cannot cover the requested amount, so no payment was created. The originating Safe must be funded or the agent allowance raised before retrying."
 };
 var AgentPaymentNextActionDescriptions = {
   [AgentPaymentNextAction.SignAndSubmitPayment]: "Sign with the delegate key and submit the payment to Haven.",
@@ -88,7 +103,8 @@ var AgentPaymentNextActionDescriptions = {
   [AgentPaymentNextAction.WaitForUserToCompletePayment]: "Wait for the wallet owner to finish sending the approved funding payment.",
   [AgentPaymentNextAction.RetryOriginalX402Request]: "Resume this payment id and retry the original x402 request with the merchant payment header.",
   [AgentPaymentNextAction.StopAndTellUser]: "Stop retrying this payment and tell the user what happened.",
-  [AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry."
+  [AgentPaymentNextAction.RequestAgainIfUserStillWantsIt]: "Ask again only if the user still wants the payment after expiry.",
+  [AgentPaymentNextAction.FundSafeOrRaiseAllowance]: "Stop and tell the user that the originating Safe needs to be funded or the agent allowance raised before the payment can succeed."
 };
 var AgentPaymentRailDescriptions = {
   [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
@@ -204,6 +220,7 @@ function verifySignature(hash, signature, expectedAddress) {
 }
 var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
 var X402_IDEMPOTENCY_BUCKET_MS = 3e5;
+var DECIMAL_ATOMIC_AMOUNT_RE = /^[0-9]+$/;
 function decodeBase64Json(value, label) {
   try {
     return JSON.parse(atob(value));
@@ -211,6 +228,12 @@ function decodeBase64Json(value, label) {
     throw new Error(`Failed to decode ${label}`);
   }
 }
+function isPositiveDecimalAtomicAmount(value) {
+  return DECIMAL_ATOMIC_AMOUNT_RE.test(value) && BigInt(value) > 0n;
+}
+function optionAuthorizationAmount(option) {
+  return option.maxAmountRequired ?? option.amount;
+}
 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") {
@@ -218,6 +241,10 @@ function normalizePaymentOption(value) {
   }
   const amount = typeof candidate.amount === "string" ? candidate.amount : typeof candidate.maxAmountRequired === "string" ? candidate.maxAmountRequired : null;
   if (!amount) return null;
+  if (!isPositiveDecimalAtomicAmount(amount)) return null;
+  if (candidate.maxAmountRequired !== void 0 && (typeof candidate.maxAmountRequired !== "string" || !isPositiveDecimalAtomicAmount(candidate.maxAmountRequired))) {
+    return null;
+  }
   return {
     scheme: candidate.scheme,
     network: candidate.network,
@@ -318,11 +345,13 @@ function selectPaymentOption(accepts) {
   for (const opt of accepts) {
     if (opt.network in SUPPORTED_X402_NETWORKS) {
       const networkTokens = NETWORK_TOKENS[opt.network];
-      if (networkTokens?.[opt.asset.toLowerCase()]) return opt;
+      if (networkTokens?.[opt.asset.toLowerCase()] && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
+        return opt;
+      }
     }
   }
   for (const opt of accepts) {
-    if (opt.network in SUPPORTED_X402_NETWORKS) {
+    if (opt.network in SUPPORTED_X402_NETWORKS && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
       return opt;
     }
   }
@@ -331,14 +360,18 @@ function selectPaymentOption(accepts) {
 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) {
+    if (opt.scheme === "exact" && opt.network in STANDARD_X402_NETWORKS && opt.asset.toLowerCase() === BASE_USDC_ADDRESS && isPositiveDecimalAtomicAmount(optionAuthorizationAmount(opt))) {
       return opt;
     }
   }
   return null;
 }
 function x402AuthorizationAmount(option) {
-  return option.maxAmountRequired ?? option.amount;
+  const amount = optionAuthorizationAmount(option);
+  if (!isPositiveDecimalAtomicAmount(amount)) {
+    throw new Error("Invalid x402 amount: must be a positive decimal atomic amount");
+  }
+  return amount;
 }
 function buildX402ExpectedMessage(context) {
   return `Haven x402 expected context v1
@@ -2309,13 +2342,19 @@ var toolDescriptions = {
   quoteX402: {
     summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.",
     behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior \u2014 Haven is not contacted.",
-    nextActionGuidance: ""
+    nextActionGuidance: "On success the returned quote is the input to haven_pay_x402_quote. Do not call the merchant again \u2014 Haven re-uses the captured request when paying."
   },
   payX402: {
     summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
     selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
     behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.",
-    nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming."
+    nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the originating Safe is funded or the agent allowance raised \u2014 stop and tell the user the shortfall reported on the response."
+  },
+  payX402OneShot: {
+    summary: "Fetch an x402 paid HTTP resource in a single call. Handles the full probe -> pay -> retry round trip and returns the merchant response.",
+    selectionGuidance: "Prefer this over the quote+pay split when the agent just wants the paid resource and does not need to inspect the price first. If you already have a quote from haven_quote_x402, use haven_pay_x402_quote instead. Do not use for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
+    behavior: "Calls the URL, parses any HTTP 402 x402 challenge, signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, then retries the original request with the X-PAYMENT header and returns the merchant response. If the resource returns an MPP machine-payment challenge instead of standard x402, the MPP payment path is used automatically. If the resource returns a non-402 status, returns it unchanged without contacting Haven.",
+    nextActionGuidance: "If approval is needed, preserve the returned resume_state or paymentId and call the resume tool once nextAction=retry_original_x402_request. If the response carries phase=insufficient_funds and nextAction=fund_safe_or_raise_allowance, the payment cannot be retried until the originating Safe is funded or the agent allowance raised \u2014 stop and tell the user the shortfall reported on the response."
   },
   resumeX402: {
     summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.",
@@ -2325,7 +2364,7 @@ var toolDescriptions = {
   quoteMpp: {
     summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.",
     behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only \u2014 Haven is not contacted.",
-    nextActionGuidance: ""
+    nextActionGuidance: "On success the returned quote is the input to haven_pay_mpp_challenge. Do not call the merchant again \u2014 Haven re-uses the captured request when paying."
   },
   payMpp: {
     summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",