@haven_ai/sdk 0.1.13-alpha.0 → 0.1.14-alpha.0

package/dist/index.d.cts

@@ -903,6 +903,37 @@ declare class HavenClient {
      */
     payMppChallenge(quote: MppQuote, options?: MppAuthorizationOptions): Promise<Response>;
     private retryX402Request;
+    /**
+     * Deliver an already-signed x402 payment header to the merchant and return
+     * the merchant's response. Used by the hosted MCP server to complete the
+     * merchant leg of an MCP tool payment after the edge signer has built the
+     * `X-PAYMENT` header.
+     *
+     * Custody note: this never needs the delegate key. It relays a signed,
+     * amount/merchant/nonce-bound EIP-3009 authorization the edge signer already
+     * produced — the hosted server cannot mint or reuse signing authority.
+     *
+     * When the URL is MCP-shaped (`/mcp` path), runs a fresh `initialize`
+     * handshake (the quote-time session is gone once funding confirms; the x402
+     * challenge is stateless w.r.t. the MCP session, so a fresh session is
+     * accepted), threads the session + wallet headers, sets `X-PAYMENT`, and
+     * collapses an SSE JSON-RPC response to its `result`.
+     *
+     * Limitation: detects MCP only by the `/mcp` path convention, not the
+     * Coinbase Bazaar `extensions.bazaar` 402 signal that `fetch()` also honors.
+     * A Bazaar-discoverable merchant on a non-`/mcp` URL would need the standard
+     * `fetch()` path. All current MCP-tool merchants use the `/mcp` convention.
+     */
+    completeX402MerchantCall(input: {
+        url: string;
+        init?: RequestInit;
+        paymentHeader: string;
+    }): Promise<{
+        status: number;
+        ok: boolean;
+        body: unknown;
+        settlementTxHash?: string;
+    }>;
     authorizeMachinePayment(challenge: MachinePaymentChallenge, options?: MppAuthorizationOptions): Promise<MachinePaymentReceipt>;
     private authorizeMppDemoPayment;
     resumeAuthorizedMpp(input: ResumeAuthorizedMppInput): Promise<MachinePaymentReceipt>;
@@ -1188,7 +1219,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
  * this canonical string and asserts byte-for-byte equality, so the two copies
  * cannot drift.
  */
-declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n  then retry the original request.\n\n## Identity and budget come from the tools \u2014 never assume them\n\nDo not guess the wallet address, network, or budget. Read them live:\n\n- `haven_get_agent` \u2014 agent identity, Haven wallet address, network.\n- `haven_get_allowances` \u2014 current per-token budgets and what remains.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n- **Direct transfer:** `haven_pay` with recipient, amount, and token.\n- **x402 paywall:** `haven_quote_x402` to get a quote, then\n  `haven_pay_x402_quote`. In the hosted setup the signing step happens in\n  the local Haven signer; follow the tool results \u2014 they tell you the next\n  action at every step. Retry the original request only when the result says\n  `retry_original_x402_request`.\n- **Status:** `haven_get_payment_status` with a `payment_id` to check on\n  queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n  budget and is waiting for the user in Haven. Tell the user, then check\n  status later.\n- Never ask the user for private keys and never try to sign anything\n  yourself \u2014 Haven signs. If a tool reports a missing or invalid credential,\n  tell the user to re-run the Haven setup command.\n\n## Failure handling\n\nHaven errors are shaped `{ error, status, details? }` and written for\nhumans \u2014 surface the message verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- Budget exceeded: tell the user how much remains (from\n  `haven_get_allowances`) and that they can raise the budget in Haven.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
+declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n  then retry the original request.\n\n## Identity and budget come from the tools \u2014 never assume them\n\nDo not guess the wallet address, network, or budget. Read them live:\n\n- `haven_get_agent` \u2014 agent identity, Haven wallet address, network.\n- `haven_get_allowances` \u2014 current per-token budgets and what remains.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n- **Direct transfer:** `haven_pay` with recipient, amount, and token.\n- **x402 paywall:** `haven_quote_x402` to get a quote, then\n  `haven_pay_x402_quote`. In the hosted setup the signing step happens in\n  the local Haven signer; follow the tool results \u2014 they tell you the next\n  action at every step. Retry the original request only when the result says\n  `retry_original_x402_request`.\n- **Paid MCP tool call:** `haven_pay_mcp_tool` with the merchant URL, tool\n  name, and arguments. Then follow the returned steps: `haven_sign` the\n  funding hash, `haven_submit` the signature, `haven_x402_sign_header` to\n  build the payment header, and finally `haven_complete_mcp_tool` to settle\n  with the merchant and get the tool result. Pass `payment_required` and\n  `arguments` through verbatim from the `haven_pay_mcp_tool` result. Do not\n  call the merchant yourself \u2014 Haven completes the merchant leg for you.\n- **Status:** `haven_get_payment_status` with a `payment_id` to check on\n  queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n  budget and is waiting for the user in Haven. Tell the user, then check\n  status later.\n- Never ask the user for private keys and never try to sign anything\n  yourself \u2014 Haven signs. If a tool reports a missing or invalid credential,\n  tell the user to re-run the Haven setup command.\n\n## Failure handling\n\nHaven errors are shaped `{ error, status, details? }` and written for\nhumans \u2014 surface the message verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- Budget exceeded: tell the user how much remains (from\n  `haven_get_allowances`) and that they can raise the budget in Haven.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
 /** Directory name for the installed skill folder. */
 declare const SKILL_FOLDER_NAME = "haven-pay";
 

package/dist/index.d.ts

@@ -903,6 +903,37 @@ declare class HavenClient {
      */
     payMppChallenge(quote: MppQuote, options?: MppAuthorizationOptions): Promise<Response>;
     private retryX402Request;
+    /**
+     * Deliver an already-signed x402 payment header to the merchant and return
+     * the merchant's response. Used by the hosted MCP server to complete the
+     * merchant leg of an MCP tool payment after the edge signer has built the
+     * `X-PAYMENT` header.
+     *
+     * Custody note: this never needs the delegate key. It relays a signed,
+     * amount/merchant/nonce-bound EIP-3009 authorization the edge signer already
+     * produced — the hosted server cannot mint or reuse signing authority.
+     *
+     * When the URL is MCP-shaped (`/mcp` path), runs a fresh `initialize`
+     * handshake (the quote-time session is gone once funding confirms; the x402
+     * challenge is stateless w.r.t. the MCP session, so a fresh session is
+     * accepted), threads the session + wallet headers, sets `X-PAYMENT`, and
+     * collapses an SSE JSON-RPC response to its `result`.
+     *
+     * Limitation: detects MCP only by the `/mcp` path convention, not the
+     * Coinbase Bazaar `extensions.bazaar` 402 signal that `fetch()` also honors.
+     * A Bazaar-discoverable merchant on a non-`/mcp` URL would need the standard
+     * `fetch()` path. All current MCP-tool merchants use the `/mcp` convention.
+     */
+    completeX402MerchantCall(input: {
+        url: string;
+        init?: RequestInit;
+        paymentHeader: string;
+    }): Promise<{
+        status: number;
+        ok: boolean;
+        body: unknown;
+        settlementTxHash?: string;
+    }>;
     authorizeMachinePayment(challenge: MachinePaymentChallenge, options?: MppAuthorizationOptions): Promise<MachinePaymentReceipt>;
     private authorizeMppDemoPayment;
     resumeAuthorizedMpp(input: ResumeAuthorizedMppInput): Promise<MachinePaymentReceipt>;
@@ -1188,7 +1219,7 @@ type SharedToolKey = keyof typeof toolDescriptions;
  * this canonical string and asserts byte-for-byte equality, so the two copies
  * cannot drift.
  */
-declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n  then retry the original request.\n\n## Identity and budget come from the tools \u2014 never assume them\n\nDo not guess the wallet address, network, or budget. Read them live:\n\n- `haven_get_agent` \u2014 agent identity, Haven wallet address, network.\n- `haven_get_allowances` \u2014 current per-token budgets and what remains.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n- **Direct transfer:** `haven_pay` with recipient, amount, and token.\n- **x402 paywall:** `haven_quote_x402` to get a quote, then\n  `haven_pay_x402_quote`. In the hosted setup the signing step happens in\n  the local Haven signer; follow the tool results \u2014 they tell you the next\n  action at every step. Retry the original request only when the result says\n  `retry_original_x402_request`.\n- **Status:** `haven_get_payment_status` with a `payment_id` to check on\n  queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n  budget and is waiting for the user in Haven. Tell the user, then check\n  status later.\n- Never ask the user for private keys and never try to sign anything\n  yourself \u2014 Haven signs. If a tool reports a missing or invalid credential,\n  tell the user to re-run the Haven setup command.\n\n## Failure handling\n\nHaven errors are shaped `{ error, status, details? }` and written for\nhumans \u2014 surface the message verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- Budget exceeded: tell the user how much remains (from\n  `haven_get_allowances`) and that they can raise the budget in Haven.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
+declare const HAVEN_SKILL_MD = "---\nname: haven-pay\ndescription: Pay for things from the user's Haven wallet within their agent rules. Use when the user asks to send, pay, tip, or transfer crypto \u2014 or when a request hits an HTTP 402 (x402) paywall.\n---\n\n# Haven: pay from a Haven wallet\n\nThis skill lets the agent make payments from the user's Haven wallet through\nthe Haven MCP tools. Every payment is checked against the agent's on-chain\nbudget before money moves; payments above the remaining budget wait for the\nuser's approval in Haven.\n\n## When to use this skill\n\n- The user asks to send money, pay someone, tip, donate, or transfer tokens.\n- A request returns HTTP 402 (x402): use the Haven pay tools to settle it,\n  then retry the original request.\n\n## Identity and budget come from the tools \u2014 never assume them\n\nDo not guess the wallet address, network, or budget. Read them live:\n\n- `haven_get_agent` \u2014 agent identity, Haven wallet address, network.\n- `haven_get_allowances` \u2014 current per-token budgets and what remains.\n\nBudgets reset on a period the user chose. If a payment exceeds the remaining\nbudget it is queued for the user to approve in the Haven dashboard \u2014 this is\nnormal, not an error.\n\n## Paying\n\n- **Direct transfer:** `haven_pay` with recipient, amount, and token.\n- **x402 paywall:** `haven_quote_x402` to get a quote, then\n  `haven_pay_x402_quote`. In the hosted setup the signing step happens in\n  the local Haven signer; follow the tool results \u2014 they tell you the next\n  action at every step. Retry the original request only when the result says\n  `retry_original_x402_request`.\n- **Paid MCP tool call:** `haven_pay_mcp_tool` with the merchant URL, tool\n  name, and arguments. Then follow the returned steps: `haven_sign` the\n  funding hash, `haven_submit` the signature, `haven_x402_sign_header` to\n  build the payment header, and finally `haven_complete_mcp_tool` to settle\n  with the merchant and get the tool result. Pass `payment_required` and\n  `arguments` through verbatim from the `haven_pay_mcp_tool` result. Do not\n  call the merchant yourself \u2014 Haven completes the merchant leg for you.\n- **Status:** `haven_get_payment_status` with a `payment_id` to check on\n  queued or in-flight payments. Do not poll in a tight loop.\n\n## Approval semantics\n\n- A result with `pending_approval` means the payment exceeded the remaining\n  budget and is waiting for the user in Haven. Tell the user, then check\n  status later.\n- Never ask the user for private keys and never try to sign anything\n  yourself \u2014 Haven signs. If a tool reports a missing or invalid credential,\n  tell the user to re-run the Haven setup command.\n\n## Failure handling\n\nHaven errors are shaped `{ error, status, details? }` and written for\nhumans \u2014 surface the message verbatim. Common cases:\n\n- `pending_approval`: queued for the user's approval (see above).\n- `insufficient_funds`: the Haven wallet doesn't hold enough of that token.\n  Suggest the user add funds in the Haven dashboard.\n- Budget exceeded: tell the user how much remains (from\n  `haven_get_allowances`) and that they can raise the budget in Haven.\n\n## Revoke\n\nIf this agent's credential may have leaked, tell the user to pause or revoke\nthe agent in the Haven dashboard under Agents. New requests stop immediately\nfor that credential.\n";
 /** Directory name for the installed skill folder. */
 declare const SKILL_FOLDER_NAME = "haven-pay";
 

package/dist/index.js

@@ -1612,6 +1612,54 @@ var HavenClient = class {
     });
     return retryResponse;
   }
+  /**
+   * Deliver an already-signed x402 payment header to the merchant and return
+   * the merchant's response. Used by the hosted MCP server to complete the
+   * merchant leg of an MCP tool payment after the edge signer has built the
+   * `X-PAYMENT` header.
+   *
+   * Custody note: this never needs the delegate key. It relays a signed,
+   * amount/merchant/nonce-bound EIP-3009 authorization the edge signer already
+   * produced — the hosted server cannot mint or reuse signing authority.
+   *
+   * When the URL is MCP-shaped (`/mcp` path), runs a fresh `initialize`
+   * handshake (the quote-time session is gone once funding confirms; the x402
+   * challenge is stateless w.r.t. the MCP session, so a fresh session is
+   * accepted), threads the session + wallet headers, sets `X-PAYMENT`, and
+   * collapses an SSE JSON-RPC response to its `result`.
+   *
+   * Limitation: detects MCP only by the `/mcp` path convention, not the
+   * Coinbase Bazaar `extensions.bazaar` 402 signal that `fetch()` also honors.
+   * A Bazaar-discoverable merchant on a non-`/mcp` URL would need the standard
+   * `fetch()` path. All current MCP-tool merchants use the `/mcp` convention.
+   */
+  async completeX402MerchantCall(input) {
+    let mcpSessionId;
+    if (isMcpUrl(input.url)) {
+      mcpSessionId = await this.mcpInitialize(input.url, input.init);
+    }
+    let requestInit = this.withX402Wallet(input.init, this.x402PayerAddress()) ?? {};
+    if (mcpSessionId) requestInit = this.withMcpHeaders(requestInit, mcpSessionId);
+    const headers = new Headers(requestInit.headers);
+    headers.set("X-PAYMENT", input.paymentHeader);
+    requestInit = { ...requestInit, headers };
+    const response = await globalThis.fetch(input.url, requestInit);
+    const surfaced = mcpSessionId ? await this.surfaceMcpResult(response) : response;
+    const settlement = parseMerchantSettlement(surfaced.headers.get("PAYMENT-RESPONSE"));
+    const text = await surfaced.text();
+    let body;
+    try {
+      body = text ? JSON.parse(text) : null;
+    } catch {
+      body = text;
+    }
+    return {
+      status: surfaced.status,
+      ok: surfaced.ok,
+      body,
+      settlementTxHash: settlement.settlementTxHash ?? void 0
+    };
+  }
   async authorizeMachinePayment(challenge, options = {}) {
     if (!this.delegateKey) {
       throw new HavenSigningError(
@@ -3082,6 +3130,13 @@ normal, not an error.
   the local Haven signer; follow the tool results \u2014 they tell you the next
   action at every step. Retry the original request only when the result says
   \`retry_original_x402_request\`.
+- **Paid MCP tool call:** \`haven_pay_mcp_tool\` with the merchant URL, tool
+  name, and arguments. Then follow the returned steps: \`haven_sign\` the
+  funding hash, \`haven_submit\` the signature, \`haven_x402_sign_header\` to
+  build the payment header, and finally \`haven_complete_mcp_tool\` to settle
+  with the merchant and get the tool result. Pass \`payment_required\` and
+  \`arguments\` through verbatim from the \`haven_pay_mcp_tool\` result. Do not
+  call the merchant yourself \u2014 Haven completes the merchant leg for you.
 - **Status:** \`haven_get_payment_status\` with a \`payment_id\` to check on
   queued or in-flight payments. Do not poll in a tight loop.