@haven_ai/sdk 0.1.5 → 0.1.7

package/dist/index.js

@@ -27,7 +27,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. */
@@ -45,7 +53,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. */
@@ -76,7 +90,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.",
@@ -86,7 +101,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.",
@@ -202,6 +218,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));
@@ -209,6 +226,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") {
@@ -216,6 +239,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,
@@ -316,11 +343,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;
     }
   }
@@ -329,14 +358,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
@@ -1176,7 +1209,7 @@ var HavenClient = class {
       ...initialInit,
       headers: retryHeaders
     });
-    if (retryResponse.status === 402) {
+    if (!retryResponse.ok) {
       await this.recordMerchantRetryRejected({
         rail: "x402",
         paymentId: receipt.paymentId,
@@ -1189,8 +1222,8 @@ var HavenClient = class {
         }
       });
       throw new HavenApiError(
-        "x402 retry was rejected after Haven funded the delegate wallet; reconciliation may be required.",
-        402,
+        "x402 retry failed after Haven funded the delegate wallet; reconciliation may be required.",
+        retryResponse.status,
         {
           marker: "x402_retry_rejected_after_funding",
           payment_id: receipt.paymentId,
@@ -1329,7 +1362,7 @@ var HavenClient = class {
       ...initialInit,
       headers: retryHeaders
     });
-    if (retryResponse.status === 402) {
+    if (!retryResponse.ok) {
       await this.recordMerchantRetryRejected({
         rail: receipt.rail,
         paymentId: receipt.paymentId,
@@ -1341,8 +1374,8 @@ var HavenClient = class {
         }
       });
       throw new HavenApiError(
-        "Machine payment retry was rejected after Haven sent the payment.",
-        402,
+        "Machine payment retry failed after Haven sent the payment.",
+        retryResponse.status,
         {
           marker: "machine_payment_retry_rejected_after_payment",
           payment_id: receipt.paymentId,
@@ -2225,7 +2258,7 @@ var HavenClient = class {
     };
   }
   mapPaymentReceipt(raw) {
-    return {
+    const receipt = {
       id: raw.id,
       paymentId: raw.payment_id,
       rail: raw.rail,
@@ -2252,6 +2285,13 @@ var HavenClient = class {
       createdAt: raw.created_at,
       updatedAt: raw.updated_at
     };
+    if ("payment_intent_id" in raw) {
+      receipt.paymentIntentId = raw.payment_intent_id ?? null;
+    }
+    if ("approval_request_id" in raw) {
+      receipt.approvalRequestId = raw.approval_request_id ?? null;
+    }
+    return receipt;
   }
 };
 function sleep(ms) {
@@ -2300,13 +2340,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.",
@@ -2316,7 +2362,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.",