@haven_ai/sdk 0.1.22-alpha.0 → 0.1.23-alpha.0

package/README.md

@@ -323,7 +323,9 @@ Hosted MCP and signer tools also return stable `code` values on recoverable x402
 
 | `code` | Meaning | Agent recovery |
 |--------|---------|----------------|
-| `PRICE_EXCEEDS_MAX` | The merchant-authoritative x402 price is above the caller's `max_amount` cap. No funding transfer was created. | Tell the user the live price exceeded the cap and retry only after they confirm a higher `max_amount`. |
+| `PRICE_EXCEEDS_MAX` | The merchant-authoritative x402 price is above the caller's spending cap. No funding transfer was created. | Tell the user the live price exceeded the cap and retry only after they confirm a higher one. |
+| `AMBIGUOUS_MAX_AMOUNT` | Both `max_amount` (atomic units) and `max_amount_human` (whole tokens) were sent for one purchase. Nothing was contacted and nothing was spent. | Re-send with exactly one — `max_amount_human` for a cap the user stated in tokens, `max_amount` for an exact atomic figure. |
+| `MAX_AMOUNT_UNCONVERTIBLE` | `max_amount_human` could not be converted against this quote's asset — its decimals are unknown to Haven, or the cap has more decimal places than the asset supports. Nothing was spent. | Round the cap to the asset's decimals, or re-send it as an exact atomic `max_amount`. |
 | `PAYMENT_WINDOW_EXPIRED` | The funding/quote window closed before `haven_x402_sign_header`, `haven_submit`, or `haven_complete_mcp_tool` could finish. | Re-run `haven_pay_mcp_tool` with the same `idempotency_key`, then sign and complete the fresh quote. Payloads include `retry_with_new_quote: true`. |
 | `MERCHANT_REJECTED_AFTER_FUNDING` | Haven's funding leg succeeded, but the merchant rejected the paid retry. | Stop retrying the merchant and call `haven_sweep_delegate` so the user can recover stranded delegate USDC. |
 

package/dist/index.cjs

@@ -104,7 +104,23 @@ var AgentPaymentFailureCode = {
    * mechanical: re-send merchant_url, tool_name, arguments, and
    * mcp_transport explicitly (the version-skew path).
    */
-  MerchantCallContextUnavailable: "MERCHANT_CALL_CONTEXT_UNAVAILABLE"
+  MerchantCallContextUnavailable: "MERCHANT_CALL_CONTEXT_UNAVAILABLE",
+  /**
+   * #1351: the caller supplied BOTH the atomic `max_amount` and the
+   * human-denominated `max_amount_human` cap for one purchase. Haven refuses
+   * to guess which the user meant — the two differ by a factor of 10^decimals,
+   * so picking wrong is exactly the silent-overspend this cap exists to
+   * prevent. Rejected before any merchant probe, funding intent, or signature.
+   */
+  AmbiguousMaxAmount: "AMBIGUOUS_MAX_AMOUNT",
+  /**
+   * #1351: a human-denominated cap was supplied, but it cannot be converted to
+   * atomic units against THIS quote — either the quote's asset has no known
+   * decimals on its network, or the cap carries more fraction digits than the
+   * asset can represent (truncating it would silently change the user's cap).
+   * The fallback is the exact atomic `max_amount`.
+   */
+  MaxAmountUnconvertible: "MAX_AMOUNT_UNCONVERTIBLE"
 };
 var AgentPaymentRail = {
   /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
@@ -159,7 +175,9 @@ var AgentPaymentFailureCodeDescriptions = {
   [AgentPaymentFailureCode.PaymentWindowExpired]: "The x402 funding/quote window expired before the signer or hosted settle step could finish. Re-quote via haven_pay_mcp_tool with the same idempotency key to avoid duplicate funding.",
   [AgentPaymentFailureCode.MerchantRejectedAfterFunding]: "The Haven funding leg succeeded, but the merchant rejected the paid retry. Stop retrying the merchant and reconcile stranded delegate funds with haven_sweep_delegate.",
   [AgentPaymentFailureCode.MerchantUnresponsiveAfterFunding]: "The Haven funding leg succeeded, but the merchant did not answer the paid retry before the timeout. The merchant may still settle late \u2014 check haven_get_payment_status (and retry haven_complete_mcp_tool once) BEFORE sweeping; sweep only if no settlement appears.",
-  [AgentPaymentFailureCode.MerchantCallContextUnavailable]: "merchant_url/tool_name were omitted and no stored merchant call context is available for this payment_id. Re-send merchant_url, tool_name, arguments, and mcp_transport explicitly."
+  [AgentPaymentFailureCode.MerchantCallContextUnavailable]: "merchant_url/tool_name were omitted and no stored merchant call context is available for this payment_id. Re-send merchant_url, tool_name, arguments, and mcp_transport explicitly.",
+  [AgentPaymentFailureCode.AmbiguousMaxAmount]: "Both max_amount (atomic units) and max_amount_human (whole tokens) were supplied for one purchase. Nothing was contacted and nothing was spent. Re-send with exactly ONE: max_amount_human for a cap the user stated in tokens, max_amount for an exact atomic figure.",
+  [AgentPaymentFailureCode.MaxAmountUnconvertible]: "max_amount_human could not be converted to atomic units against this quote's asset \u2014 either its decimals are unknown to Haven or the cap has more decimal places than the asset supports. Nothing was spent. Round the cap, or re-send it as an exact atomic max_amount."
 };
 var AgentPaymentWarningCode = {
   /** No max_amount cap was supplied — the live quoted price was accepted as-is. */
@@ -1094,8 +1112,7 @@ var HavenClient = class {
         400
       );
     }
-    const agent = await this.getAgent();
-    const fundingTo = agent.delegateAddress;
+    const fundingTo = options.delegateAddress ?? (await this.getAgent()).delegateAddress;
     if (!fundingTo) {
       throw new HavenApiError("Authenticated agent has no delegate address registered.", 502);
     }
@@ -1104,13 +1121,25 @@ var HavenClient = class {
       url: paymentRequired.resource.url,
       payTo: fundingTo,
       merchantPayTo: option.payTo,
+      // #1360: this path ALWAYS means the EIP-3009 funding leg (payTo is the
+      // agent's own delegate EOA). Saying so explicitly turns a stale/rotated
+      // delegate address into the backend's LOUD shape-mismatch 400 instead
+      // of a silent reroute to the erc7710 settlement branch (the #1358
+      // review's open-budget misroute). Legacy-rail backends ignore the field.
+      settlementScheme: "eip3009",
       amount: x402AuthorizationAmount(option),
       asset: option.asset,
       network: option.network,
       description: paymentRequired.resource.description,
       idempotencyKey,
       // #1307: persisted so the settle leg can rehydrate it by payment_id.
-      ...options.mcpCallContext ? { mcpCallContext: options.mcpCallContext } : {}
+      ...options.mcpCallContext ? { mcpCallContext: options.mcpCallContext } : {},
+      // #1355: persisted so the SIGN leg can rehydrate it by payment_id — the
+      // local signer's context fetch then carries the 402 PaymentRequired and
+      // the agent passes only payment_id. Bounded: the backend rejects >64KB,
+      // so an oversized blob is omitted here (signer falls back to the
+      // caller-supplied copy) rather than failing the intent.
+      ...new TextEncoder().encode(JSON.stringify(paymentRequired)).length <= 65536 ? { paymentRequired } : {}
     });
     if (raw.status !== "pending_signature") {
       this.throwPaymentStateError("x402 payment", raw);
@@ -1242,6 +1271,17 @@ var HavenClient = class {
    * Get the agent identity tied to this API key.
    */
   async getAgent() {
+    if (this.agentInFlight) return this.agentInFlight;
+    const request = this.fetchAgent();
+    this.agentInFlight = request;
+    request.finally(() => {
+      this.agentInFlight = null;
+    }).catch(() => {
+    });
+    return request;
+  }
+  agentInFlight = null;
+  async fetchAgent() {
     const raw = await this.get("/machine-payments/agent");
     return {
       id: raw.id,
@@ -1440,6 +1480,7 @@ var HavenClient = class {
    */
   async getPostPurchaseAllowanceSummary(paymentId) {
     const unavailable = (detail) => ({
+      payment: null,
       allowance: null,
       warnings: [
         {
@@ -1448,27 +1489,38 @@ var HavenClient = class {
         }
       ]
     });
+    const [statusResult, agentResult, allowanceResult] = await Promise.allSettled([
+      this.getPaymentStatus(paymentId),
+      this.getAgent(),
+      this.getAllowances()
+    ]);
+    if (statusResult.status === "rejected") {
+      return unavailable(statusResult.reason instanceof Error ? statusResult.reason.message : String(statusResult.reason));
+    }
+    const status = statusResult.value;
+    if (agentResult.status === "rejected") {
+      return { ...unavailable(agentResult.reason instanceof Error ? agentResult.reason.message : String(agentResult.reason)), payment: status };
+    }
+    if (allowanceResult.status === "rejected") {
+      return { ...unavailable(allowanceResult.reason instanceof Error ? allowanceResult.reason.message : String(allowanceResult.reason)), payment: status };
+    }
     try {
-      const [status, agent, allowanceSummary] = await Promise.all([
-        this.getPaymentStatus(paymentId),
-        this.getAgent(),
-        this.getAllowances()
-      ]);
       const tokenAddress = status.asset ?? status.x402?.asset ?? null;
       if (!tokenAddress) {
-        return unavailable("the settled payment does not carry a resolvable token address");
+        return { ...unavailable("the settled payment does not carry a resolvable token address"), payment: status };
       }
-      const rail = agent.executionRail;
+      const rail = agentResult.value.executionRail;
       const source = rail === "delegation" ? "active_delegations" : "allowance_module";
-      const match = allowanceSummary.allowances.find(
+      const match = allowanceResult.value.allowances.find(
         (a) => a.tokenAddress.toLowerCase() === tokenAddress.toLowerCase()
       );
       if (!match) {
-        return unavailable("no allowance/budget row matches the settled token");
+        return { ...unavailable("no allowance/budget row matches the settled token"), payment: status };
       }
       const token = resolveTokenFromAddress(match.tokenAddress);
       const remainingDisplay = token ? `${formatAtomicAmount(safeBigInt(match.onchain.remaining), token.decimals)} ${match.tokenSymbol}` : void 0;
       return {
+        payment: status,
         allowance: {
           rail,
           remaining_atomic: match.onchain.remaining,
@@ -1516,6 +1568,7 @@ var HavenClient = class {
   async discoverTools(options = {}) {
     const params = new URLSearchParams();
     if (options.category) params.set("category", options.category);
+    if (options.search !== void 0) params.set("search", options.search);
     if (options.rail) params.set("rail", options.rail);
     const query = params.size > 0 ? `?${params.toString()}` : "";
     const raw = await this.get(`/catalog${query}`);
@@ -1707,7 +1760,11 @@ var HavenClient = class {
       asset: option.asset,
       network: option.network,
       description: paymentRequired.resource.description,
-      idempotencyKey
+      idempotencyKey,
+      // #1360: same explicit funding-leg declaration as createX402Intent —
+      // this local-key path derives payTo from the key (never stale), but the
+      // declaration keeps both writers of the 3009 shape loud-by-default.
+      settlementScheme: "eip3009"
     });
     if (raw.success && raw.tx_hash) {
       const receipt2 = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw);
@@ -2910,6 +2967,11 @@ var HavenClient = class {
       amountAtomic: x402AuthorizationAmount(option),
       amount: decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
       token: token?.symbol ?? "USDC",
+      // #1351: null when the asset is unrecognised on this network — the
+      // `token` fallback above is a LABEL, not evidence of 6 decimals, and a
+      // human-denominated cap must fail closed rather than convert against a
+      // guess. Same resolution as `token`, so the two never disagree.
+      decimals: token?.decimals ?? null,
       asset: option.asset,
       network: option.network,
       chainId: chainIdOrNull(option.network),
@@ -3524,8 +3586,8 @@ var toolDescriptions = {
   discoverTools: {
     summary: "Step 1 of a purchase: discover payable services from Haven's curated merchant catalog \u2014 names, prices, and which pay tool to use next.",
     selectionGuidance: "Use this when the user asks what the agent can buy, pay for, or which paid services exist \u2014 or when you need a resource URL for a service the user described. Do NOT use for balance, budget, or spend-limit questions \u2014 use haven_get_allowances. Do NOT use to pay \u2014 each returned entry names the pay tool to use next.",
-    behavior: "Use each entry's suggested_tool field first \u2014 it names the exact next call. Read-only lookup against Haven's curated catalog; entries are periodically re-verified against the live merchant and degraded entries are flagged. Returns name, description, price, rail, resource URL, tool_name, tool_arguments, and suggested_tool. The catalog price (price_display/price_atomic, marked price_is_indicative) is a last-verified hint, NOT authoritative \u2014 the real price comes from the merchant's live 402 at pay time. Never creates a payment, signature, or approval.",
-    nextActionGuidance: "Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass max_amount when the user has a cap."
+    behavior: "Use each entry's suggested_tool field first \u2014 it names the exact next call. Read-only lookup against Haven's curated catalog; entries are periodically re-verified against the live merchant and degraded entries are flagged. Use category for a case-insensitive category filter (for example, VPN or vpn), or search for a product name, category, or description term. Returns name, description, price, rail, resource URL, tool_name, tool_arguments, and suggested_tool. The catalog price (price_display/price_atomic, marked price_is_indicative) is a last-verified hint, NOT authoritative \u2014 the real price comes from the merchant's live 402 at pay time. Never creates a payment, signature, or approval.",
+    nextActionGuidance: `Pick an entry and pay it with the tool named in suggested_tool, passing the entry's resource_url, tool_name, and tool_arguments for MCP merchants. Confirm the price from the live pay-tool result (not the catalog), and pass the user's cap as max_amount_human in whole tokens ("no more than 1 USDC" \u2192 max_amount_human: "1") \u2014 never convert it to atomic units by hand (#1351).`
   },
   sweep_delegate: {
     summary: "Sweep stranded USDC and/or ETH from the delegate wallet back to the originating Safe.",
@@ -3837,10 +3899,13 @@ normal, not an error.
 
 1. \`mcp__haven__haven_discover_tools\` to find a payable service and its
    \`catalog_id\`.
-2. \`mcp__haven__haven_prepare_catalog_purchase\` with \`catalog_id\` and
-   \`max_amount\`. \`max_amount\` (atomic units) is REQUIRED on this tool, and
-   is best practice on every paid call below too \u2014 it caps what the LIVE
-   merchant quote may charge, checked before any funding intent is created.
+2. \`mcp__haven__haven_prepare_catalog_purchase\` with \`catalog_id\` and a
+   spending cap. A cap is REQUIRED on this tool and is best practice on every
+   paid call below too \u2014 it caps what the LIVE merchant quote may charge,
+   checked before any funding intent is created. Write it the way the user
+   said it: \`max_amount_human\` is whole tokens, so "no more than 1 USDC" is
+   \`max_amount_human: "1"\`. (\`max_amount\` is the atomic-unit form, where
+   "1" means 0.000001 USDC \u2014 do not convert by hand, and never send both.)
 3. Then FOLLOW THE RESPONSE'S GUIDANCE FIELDS: \`next_action\`, \`next_tool\`,
    and \`next_arguments\` name the exact next call \u2014 act on those first; the
    prose in this section is fallback and debugging detail. If the catalog
@@ -3848,9 +3913,11 @@ normal, not an error.
    \`mcp__haven__haven_pay_mcp_tool\` (merchant URL, tool name, arguments) as
    the manual fallback.
 
-**Signing:** \`mcp__haven-signer__haven_sign_x402\` with \`payment_id\` and
-\`payment_required\` ONLY \u2014 the local signer fetches the exact signing bytes
-itself, so never relay \`typed_data\` yourself. Fallback for an older signer
+**Signing:** \`mcp__haven-signer__haven_sign_x402\` with \`payment_id\` ONLY \u2014
+the local signer fetches the exact signing bytes AND \`payment_required\`
+itself, so never relay \`typed_data\` or the 402 blob yourself. If the signer
+reports its fetched context carried no \`payment_required\` (older backend),
+re-call with \`payment_required\` added verbatim. Fallback for an older signer
 or backend: re-run the quote/prepare tool with the SAME \`idempotency_key\`
 plus \`include_signing_payload=true\`, then pass \`payload_hash\`,
 \`x402_expected\` (the nested \`x402.expected\` object), and
@@ -3920,8 +3987,14 @@ present and surface \`message\` or \`error\` verbatim. Common cases:
 - \`pending_approval\`: queued for the user's approval (see above).
 - \`insufficient_funds\`: the Haven wallet doesn't hold enough of that token.
   Suggest the user add funds in the Haven dashboard.
-- \`PRICE_EXCEEDS_MAX\`: the live merchant price exceeded your \`max_amount\`.
-  No funds moved; ask the user before retrying with a higher cap.
+- \`PRICE_EXCEEDS_MAX\`: the live merchant price exceeded your cap. No funds
+  moved; ask the user before retrying with a higher one.
+- \`AMBIGUOUS_MAX_AMOUNT\`: you sent both \`max_amount\` and
+  \`max_amount_human\`. Nothing was contacted or spent \u2014 re-send with exactly
+  one (\`max_amount_human\` for a cap the user stated in tokens).
+- \`MAX_AMOUNT_UNCONVERTIBLE\`: \`max_amount_human\` does not fit this quote's
+  asset \u2014 unknown decimals, or more decimal places than the asset supports.
+  Round the cap, or send an exact atomic \`max_amount\`.
 - \`PAYMENT_WINDOW_EXPIRED\`: re-run the quote/prepare tool with the same
   \`idempotency_key\`, then sign the fresh payload.
 - \`MERCHANT_REJECTED_AFTER_FUNDING\`: the merchant refused the paid retry.
@@ -3940,10 +4013,12 @@ present and surface \`message\` or \`error\` verbatim. Common cases:
 ## Reporting after a purchase
 
 A settled \`mcp__haven__haven_settle_mcp_tool\` response carries
-\`agent_summary\` and the remaining post-purchase allowance in \`allowance\` \u2014
-report the amount paid and what is left from those fields directly. Do not
-call \`haven_get_agent\` or \`haven_get_allowances\` again just to report a
-purchase you already made.
+\`agent_summary.purchase_summary\` and the remaining post-purchase allowance
+in \`allowance\` \u2014 report the product, Haven-derived payment/transaction
+fields, and what is left from those fields directly. \`result\` is optional
+raw merchant evidence; never use it to decide whether the purchase was paid.
+Do not call \`haven_get_agent\` or \`haven_get_allowances\` again just to
+report a purchase you already made.
 
 ## Revoke
 
@@ -3954,7 +4029,7 @@ for that credential.
 var SKILL_FOLDER_NAME = "haven-pay";
 
 // src/node-version.ts
-var HAVEN_MINIMUM_NODE_VERSION = "24.0.0";
+var HAVEN_MINIMUM_NODE_VERSION = "22.0.0";
 function parseNodeVersion(value) {
   const match = value.trim().match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
   if (!match) return [0, 0, 0];
@@ -4203,6 +4278,7 @@ exports.parseMachinePaymentChallenge = parseMachinePaymentChallenge;
 exports.parseMachinePaymentChallengeResponse = parseMachinePaymentChallengeResponse;
 exports.parsePaymentRequired = parsePaymentRequired;
 exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
+exports.resolveTokenFromAddress = resolveTokenFromAddress;
 exports.sameUrl = sameUrl;
 exports.selectPaymentOption = selectPaymentOption;
 exports.selectStandardPaymentOption = selectStandardPaymentOption;