@haven_ai/sdk 0.0.0-dev.202609142030.8358774 → 0.0.0-dev.202609142053.7f40fec

package/README.md

@@ -406,6 +406,7 @@ Hosted MCP and signer tools also return stable `code` values on recoverable x402
 | `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. Payloads carry `next_action: stop_and_tell_user` and `retry_with_new_quote: true` — the latter means any retry needs a fresh quote, not that one should be attempted unattended. |
 | `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`. |
+| `MERCHANT_NOT_READY` | The merchant answered the quote probe with its own `503 { error: 'merchant_not_ready', reason_code, retry_after_s }` instead of a 402 — it cannot settle right now (e.g. its settlement wallet is out of gas). No payment was created. | Tell the user and retry later (`retry_after_s` in the message when given); do not treat it as a wrong endpoint. Payloads carry `next_action: stop_and_tell_user` and `retry_with_new_quote: true`. |
 | `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

@@ -195,7 +195,17 @@ var AgentPaymentFailureCode = {
    * asset can represent (truncating it would silently change the user's cap).
    * The fallback is the exact atomic `max_amount`.
    */
-  MaxAmountUnconvertible: "MAX_AMOUNT_UNCONVERTIBLE"
+  MaxAmountUnconvertible: "MAX_AMOUNT_UNCONVERTIBLE",
+  /**
+   * #2979: the merchant answered a `tools/call` probe with its own
+   * machine-readable "cannot settle right now" refusal (HTTP 503,
+   * `{ error: 'merchant_not_ready', reason_code, ... }`) instead of a 402
+   * challenge — e.g. its settlement wallet is out of gas. No 402 was ever
+   * issued and no payment was created; this is honest and (per
+   * `retry_after_s`, when present) usually transient, unlike a permanent
+   * endpoint miss.
+   */
+  MerchantNotReady: "MERCHANT_NOT_READY"
 };
 var AgentPaymentRail = {
   /** Standard Haven payment from the user's Safe through an approved delegate allowance. */
@@ -253,7 +263,8 @@ var AgentPaymentFailureCodeDescriptions = {
   [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.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."
+  [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.",
+  [AgentPaymentFailureCode.MerchantNotReady]: 'The merchant refused the probe with its own "cannot settle right now" signal instead of a 402 challenge. No payment was created. Often transient \u2014 retry later (see retry_after_s in the message, if given) rather than treating this as a broken or wrong endpoint.'
 };
 var AgentPaymentWarningCode = {
   /** No max_amount cap was supplied — the live quoted price was accepted as-is. */
@@ -348,8 +359,18 @@ var MerchantTimeoutError = class extends HavenApiError {
 };
 var X402UnexpectedStatusError = class extends HavenApiError {
   x402ErrorCode = "unexpected_non_402_status";
-  constructor(message, statusCode) {
-    super(message, statusCode);
+  /**
+   * #2979: `body` is the merchant's own JSON, when the non-402 response
+   * carried one — e.g. the demo merchant's `/mcp` readiness gate answers
+   * `503 { error: 'merchant_not_ready', reason_code, ... }`. Optional and
+   * best-effort: a non-JSON or unreadable body leaves this `undefined`, same
+   * as before this field existed. Consumers key on it (not on the message
+   * string) to distinguish an honest, machine-readable merchant refusal from
+   * a genuine "this is not the x402 endpoint" miss, which otherwise look
+   * identical — both are just "some non-402 status".
+   */
+  constructor(message, statusCode, body) {
+    super(message, statusCode, body);
     this.name = "X402UnexpectedStatusError";
   }
 };
@@ -3646,9 +3667,16 @@ var HavenClient = class {
     const request = snapshotX402Request(url, initialInit);
     const response = await this.merchantTransport.fetch(url, initialInit);
     if (response.status !== 402) {
+      let body;
+      try {
+        body = await response.clone().json();
+      } catch {
+        body = void 0;
+      }
       throw new X402UnexpectedStatusError(
         `Expected an x402 quote response with HTTP 402, got HTTP ${response.status}.`,
-        response.status || 400
+        response.status || 400,
+        body
       );
     }
     if (response.headers.get("MACHINE-PAYMENT-CHALLENGE")) {
@@ -4850,6 +4878,11 @@ present and surface \`message\` or \`error\` verbatim. Common cases:
   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_NOT_READY\`: the merchant refused the quote with its own
+  "cannot settle right now" signal (a 503 \`merchant_not_ready\` with a
+  \`reason_code\`) instead of a 402. No payment was created. Tell the user;
+  retry later (the message carries \`retry_after_s\` when the merchant gave
+  one) \u2014 this is not a wrong or broken endpoint.
 - \`MERCHANT_REJECTED_AFTER_FUNDING\`: the merchant refused the paid retry.
   Stop-and-sweep \u2014 stop retrying the merchant and use
   \`mcp__haven__haven_sweep_delegate\` to recover stranded delegate funds.