@haven_ai/sdk 0.1.2 → 0.1.3

package/dist/index.js

@@ -356,6 +356,9 @@ function buildExplorerUrl(chainId, txHash) {
   const base = CHAIN_EXPLORER_TX[chainId ?? 8453] ?? CHAIN_EXPLORER_TX[8453];
   return `${base}/${txHash}`;
 }
+function explorerUrlOrEmpty(chainId, txHash) {
+  return txHash ? buildExplorerUrl(chainId, txHash) : "";
+}
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
 var DEFAULT_POLLING_INTERVAL = 3e3;
@@ -418,6 +421,28 @@ function messageForState(label, status, paymentId, nextAction) {
   }
   return `${label} is ${status}; next_action=${nextAction} (payment_id: ${paymentId}).`;
 }
+function sameAddress(a, b) {
+  return Boolean(a && b && a.toLowerCase() === b.toLowerCase());
+}
+function decimalFromUsdcAtomic(value) {
+  const amount = BigInt(value);
+  const whole = amount / 1000000n;
+  const fraction = (amount % 1000000n).toString().padStart(6, "0").replace(/0+$/, "");
+  return fraction ? `${whole}.${fraction}` : whole.toString();
+}
+function normalizeDecimal(value) {
+  if (!value.includes(".")) return value.replace(/^0+(?=\d)/, "") || "0";
+  const [whole, fraction = ""] = value.split(".");
+  const normalizedWhole = whole.replace(/^0+(?=\d)/, "") || "0";
+  const normalizedFraction = fraction.replace(/0+$/, "");
+  return normalizedFraction ? `${normalizedWhole}.${normalizedFraction}` : normalizedWhole;
+}
+function parseMerchantSettlement(header) {
+  if (!header) return {};
+  const parsed = parseProtocolReceiptHeader(header);
+  const tx = typeof parsed?.transaction === "string" ? parsed.transaction : typeof parsed?.txHash === "string" ? parsed.txHash : typeof parsed?.tx_hash === "string" ? parsed.tx_hash : null;
+  return { settlementTxHash: tx };
+}
 var HavenClient = class {
   apiKey;
   delegateKey;
@@ -561,7 +586,7 @@ var HavenClient = class {
    *
    * Requires `delegateKey` to be set in the client config.
    */
-  async authorizeX402(paymentRequired) {
+  async authorizeX402(paymentRequired, options = {}) {
     if (!this.delegateKey) {
       throw new HavenSigningError(
         "delegateKey is required for x402 payments. Pass it in the HavenClient config."
@@ -577,7 +602,7 @@ var HavenClient = class {
         400
       );
     }
-    const idempotencyKey = buildX402IdempotencyKey(paymentRequired, option);
+    const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
     const cached = this.x402ReceiptCache.get(idempotencyKey);
     if (cached && cached.expiresAt > Date.now()) return cached.receipt;
     const inFlight = this.inFlightX402.get(idempotencyKey);
@@ -603,21 +628,13 @@ var HavenClient = class {
       idempotencyKey
     });
     if (raw.success && raw.tx_hash) {
-      const receipt2 = {
-        success: true,
-        paymentId: raw.payment_id,
-        txHash: raw.tx_hash,
-        token: raw.token ?? "",
-        amount: raw.amount ?? "",
-        to: raw.to ?? "",
-        resourceUrl: paymentRequired.resource.url,
-        explorerUrl: raw.explorer_url ?? (raw.tx_hash ? buildExplorerUrl(raw.chain_id, raw.tx_hash) : ""),
-        accepted: option,
-        paymentHeader,
-        merchantTo: raw.merchant_to ?? option.payTo,
-        payer: raw.payer ?? raw.safe_address,
-        chainId: raw.chain_id ?? chainIdFromNetwork(option.network)
-      };
+      const receipt2 = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw);
+      this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
+      return receipt2;
+    }
+    const state = this.paymentStateFromRaw("x402 payment", raw);
+    if (state?.nextAction === "retry_original_x402_request") {
+      const receipt2 = this.mapX402ReceiptFromStatus(paymentRequired, option, paymentHeader, state);
       this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
       return receipt2;
     }
@@ -633,24 +650,53 @@ var HavenClient = class {
     if (execResult.status !== "confirmed") {
       this.throwPaymentStateError("x402 payment", execResult);
     }
-    const receipt = {
-      success: true,
-      paymentId: raw.payment_id,
-      txHash: execResult.tx_hash ?? "",
-      token: execResult.token ?? raw.token ?? "",
-      amount: execResult.amount ?? raw.amount ?? "",
-      to: execResult.to ?? raw.to ?? "",
-      resourceUrl: paymentRequired.resource.url,
-      explorerUrl: execResult.explorer_url ?? (execResult.tx_hash ? buildExplorerUrl(execResult.chain_id, execResult.tx_hash) : ""),
-      accepted: option,
-      paymentHeader,
-      merchantTo: option.payTo,
-      payer: raw.payer ?? raw.safe_address ?? raw.sign_data?.components.safe,
-      chainId: execResult.chain_id ?? raw.chain_id ?? chainIdFromNetwork(option.network)
-    };
+    const receipt = this.mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult);
+    this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
+    return receipt;
+  }
+  async resumeAuthorizedX402(input) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "delegateKey is required for x402 payments. Pass it in the HavenClient config."
+      );
+    }
+    if (!this.delegateAddress) {
+      throw new HavenSigningError("delegateAddress could not be derived from delegateKey.");
+    }
+    const option = selectStandardPaymentOption(input.paymentRequired.accepts);
+    if (!option) {
+      throw new HavenApiError(
+        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
+        400
+      );
+    }
+    const idempotencyKey = input.idempotencyKey ?? buildX402IdempotencyKey(input.paymentRequired, option);
+    const cached = this.x402ReceiptCache.get(idempotencyKey);
+    if (cached && cached.expiresAt > Date.now()) return cached.receipt;
+    const status = await this.getPaymentStatus(input.paymentId);
+    this.assertCanResumeX402(status, input.paymentRequired, option);
+    const paymentHeader = await this.createStandardX402Header(input.paymentRequired, option);
+    const receipt = this.mapX402ReceiptFromStatus(input.paymentRequired, option, paymentHeader, status);
     this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
     return receipt;
   }
+  async resumeX402Payment(input) {
+    const initialInit = this.withX402Wallet(input.init, this.x402PayerAddress());
+    let paymentRequired = input.paymentRequired;
+    if (!paymentRequired) {
+      const response = await globalThis.fetch(input.url, initialInit);
+      if (response.status !== 402) {
+        throw new HavenApiError("Expected the original x402 request to return HTTP 402 before resuming.", 400);
+      }
+      paymentRequired = await parsePaymentRequiredResponse(response);
+    }
+    const receipt = await this.resumeAuthorizedX402({
+      paymentId: input.paymentId,
+      paymentRequired,
+      idempotencyKey: input.idempotencyKey
+    });
+    return this.retryX402Request(input.url, initialInit, paymentRequired, receipt);
+  }
   /**
    * Fetch wrapper that automatically handles HTTP 402 responses.
    *
@@ -664,7 +710,7 @@ var HavenClient = class {
    *
    * Requires `delegateKey` to be set in the client config.
    */
-  async fetch(url, init) {
+  async fetch(url, init, options = {}) {
     const initialInit = this.withX402Wallet(init, this.x402PayerAddress());
     const response = await globalThis.fetch(url, initialInit);
     if (response.status !== 402) return response;
@@ -685,7 +731,10 @@ var HavenClient = class {
       }
       return this.fetchWithMachinePayment(url, initialInit, challenge);
     }
-    const receipt = await this.authorizeX402(paymentRequired);
+    const receipt = await this.authorizeX402(paymentRequired, options);
+    return this.retryX402Request(url, initialInit, paymentRequired, receipt);
+  }
+  async retryX402Request(url, initialInit, paymentRequired, receipt) {
     if (!receipt.accepted) {
       throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
     }
@@ -723,6 +772,14 @@ var HavenClient = class {
         }
       );
     }
+    const merchantSettlement = parseMerchantSettlement(retryResponse.headers.get("PAYMENT-RESPONSE"));
+    if (receipt.merchant && merchantSettlement.settlementTxHash) {
+      receipt.merchant.settlementTxHash = merchantSettlement.settlementTxHash;
+      receipt.merchant.settlementExplorerUrl = buildExplorerUrl(
+        receipt.chainId,
+        merchantSettlement.settlementTxHash
+      );
+    }
     await this.reportMachinePaymentEvidence({
       paymentId: receipt.paymentId,
       rail: "x402",
@@ -825,6 +882,150 @@ var HavenClient = class {
     });
     return retryResponse;
   }
+  assertCanResumeX402(status, paymentRequired, option) {
+    if (status.rail !== "x402") {
+      throw new HavenPaymentStateError(
+        `Payment ${status.paymentId} is ${status.rail}, not x402.`,
+        409,
+        status
+      );
+    }
+    if (status.nextAction !== "retry_original_x402_request") {
+      throw new HavenPaymentStateError(status.message, PAYMENT_STATE_STATUS_CODES[status.status] ?? 409, status);
+    }
+    if (!status.txHash) {
+      throw new HavenApiError(
+        `x402 payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    if (status.resourceUrl && status.resourceUrl !== paymentRequired.resource.url) {
+      throw new HavenApiError(
+        "x402 resume request does not match the approved resource URL.",
+        409,
+        { status, paymentRequired },
+        status.paymentId
+      );
+    }
+    if (status.merchantAddress && !sameAddress(status.merchantAddress, option.payTo)) {
+      throw new HavenApiError(
+        "x402 resume request does not match the approved merchant.",
+        409,
+        { status, selectedPayment: option },
+        status.paymentId
+      );
+    }
+    const optionChainId = chainIdFromNetwork(option.network);
+    if (status.chainId && optionChainId && status.chainId !== optionChainId) {
+      throw new HavenApiError(
+        "x402 resume request does not match the approved network.",
+        409,
+        { status, selectedPayment: option },
+        status.paymentId
+      );
+    }
+    if (status.token && status.token !== "USDC") {
+      throw new HavenApiError(
+        "x402 resume request does not match the approved token.",
+        409,
+        { status, selectedPayment: option },
+        status.paymentId
+      );
+    }
+    const approvedAmount = status.amount ? normalizeDecimal(status.amount) : "";
+    const requestedAmount = normalizeDecimal(decimalFromUsdcAtomic(option.amount));
+    if (approvedAmount && approvedAmount !== requestedAmount) {
+      throw new HavenApiError(
+        "x402 resume request does not match the approved amount.",
+        409,
+        { status, selectedPayment: option },
+        status.paymentId
+      );
+    }
+  }
+  mapX402ReceiptFromAuthorization(paymentRequired, option, paymentHeader, raw, execResult) {
+    const txHash = execResult?.tx_hash ?? raw.tx_hash ?? "";
+    const chainId = execResult?.chain_id ?? raw.chain_id ?? chainIdFromNetwork(option.network);
+    const token = execResult?.token ?? raw.token ?? "USDC";
+    const amount = execResult?.amount ?? raw.amount ?? decimalFromUsdcAtomic(option.amount);
+    const to = execResult?.to ?? raw.to ?? this.delegateAddress ?? "";
+    const explorerUrl = execResult?.explorer_url ?? raw.explorer_url ?? explorerUrlOrEmpty(chainId, txHash);
+    const merchantTo = execResult?.merchant_to ?? raw.merchant_to ?? option.payTo;
+    const payer = raw.payer ?? raw.safe_address ?? raw.sign_data?.components.safe;
+    return this.buildX402Receipt({
+      paymentId: raw.payment_id,
+      txHash,
+      token,
+      amount,
+      to,
+      resourceUrl: paymentRequired.resource.url,
+      explorerUrl,
+      accepted: option,
+      paymentHeader,
+      merchantTo,
+      payer,
+      chainId
+    });
+  }
+  mapX402ReceiptFromStatus(paymentRequired, option, paymentHeader, status) {
+    if (!status.txHash) {
+      throw new HavenApiError(
+        `x402 payment ${status.paymentId} is ready to retry but has no Haven transaction hash.`,
+        502,
+        status,
+        status.paymentId
+      );
+    }
+    return this.buildX402Receipt({
+      paymentId: status.paymentId,
+      txHash: status.txHash,
+      token: status.token || "USDC",
+      amount: status.amount || decimalFromUsdcAtomic(option.amount),
+      to: this.delegateAddress ?? "",
+      resourceUrl: paymentRequired.resource.url,
+      explorerUrl: explorerUrlOrEmpty(status.chainId, status.txHash),
+      accepted: option,
+      paymentHeader,
+      merchantTo: status.merchantAddress ?? option.payTo,
+      payer: this.x402Wallet,
+      chainId: status.chainId || chainIdFromNetwork(option.network)
+    });
+  }
+  buildX402Receipt(input) {
+    const fundingExplorerUrl = input.explorerUrl || explorerUrlOrEmpty(input.chainId, input.txHash);
+    return {
+      success: true,
+      paymentId: input.paymentId,
+      txHash: input.txHash,
+      token: input.token,
+      amount: input.amount,
+      to: input.to,
+      resourceUrl: input.resourceUrl,
+      explorerUrl: input.explorerUrl,
+      accepted: input.accepted,
+      paymentHeader: input.paymentHeader,
+      merchantTo: input.merchantTo ?? input.accepted.payTo,
+      payer: input.payer,
+      chainId: input.chainId,
+      haven: {
+        paymentId: input.paymentId,
+        fundingTxHash: input.txHash,
+        fundingExplorerUrl
+      },
+      merchant: {
+        payTo: input.merchantTo ?? input.accepted.payTo
+      },
+      x402: {
+        amount: input.accepted.amount,
+        token: input.token,
+        network: input.accepted.network,
+        asset: input.accepted.asset,
+        resource: input.accepted.resource ?? input.resourceUrl
+      }
+    };
+  }
   async createStandardX402Header(paymentRequired, option) {
     if (!this.delegateKey) {
       throw new HavenSigningError("delegateKey is required to sign x402 payment headers.");
@@ -1008,36 +1209,26 @@ var HavenClient = class {
       }
     }
     if (toolName === "authorize_x402_payment") {
-      const { url, payTo, amount, asset, network, description } = input;
+      const { url, payTo, amount, asset, network, description, idempotencyKey } = input;
       try {
-        const receipt = await this.authorizeX402({
-          x402Version: 2,
-          resource: { url, description },
-          accepts: [
-            {
-              scheme: "exact",
-              network,
-              amount,
-              asset,
-              payTo,
-              maxTimeoutSeconds: 30
-            }
-          ]
+        const receipt = await this.authorizeX402(
+          this.toolX402PaymentRequired({ url, payTo, amount, asset, network, description }),
+          { idempotencyKey }
+        );
+        return this.x402ToolReceipt(receipt);
+      } catch (err) {
+        return this.toolError(err);
+      }
+    }
+    if (toolName === "resume_x402_payment") {
+      const { payment_id, url, payTo, amount, asset, network, description, idempotencyKey } = input;
+      try {
+        const receipt = await this.resumeAuthorizedX402({
+          paymentId: payment_id,
+          paymentRequired: this.toolX402PaymentRequired({ url, payTo, amount, asset, network, description }),
+          idempotencyKey
         });
-        return {
-          success: true,
-          payment_id: receipt.paymentId,
-          tx_hash: receipt.txHash,
-          token: receipt.token,
-          amount: receipt.amount,
-          to: receipt.to,
-          resource_url: receipt.resourceUrl,
-          explorer_url: receipt.explorerUrl,
-          payment_header: receipt.paymentHeader,
-          merchant_to: receipt.merchantTo,
-          payer: receipt.payer,
-          chain_id: receipt.chainId
-        };
+        return this.x402ToolReceipt(receipt);
       } catch (err) {
         return this.toolError(err);
       }
@@ -1087,6 +1278,41 @@ var HavenClient = class {
     }
     throw new Error(`Unknown tool: ${toolName}`);
   }
+  toolX402PaymentRequired(input) {
+    return {
+      x402Version: 2,
+      resource: { url: input.url, description: input.description },
+      accepts: [
+        {
+          scheme: "exact",
+          network: input.network,
+          amount: input.amount,
+          asset: input.asset,
+          payTo: input.payTo,
+          maxTimeoutSeconds: 30
+        }
+      ]
+    };
+  }
+  x402ToolReceipt(receipt) {
+    return {
+      success: true,
+      payment_id: receipt.paymentId,
+      tx_hash: receipt.txHash,
+      token: receipt.token,
+      amount: receipt.amount,
+      to: receipt.to,
+      resource_url: receipt.resourceUrl,
+      explorer_url: receipt.explorerUrl,
+      payment_header: receipt.paymentHeader,
+      merchant_to: receipt.merchantTo,
+      payer: receipt.payer,
+      chain_id: receipt.chainId,
+      haven: receipt.haven,
+      merchant: receipt.merchant,
+      x402: receipt.x402
+    };
+  }
   toolError(err) {
     if (err instanceof HavenPaymentStateError) {
       return {
@@ -1295,10 +1521,52 @@ var authorizeX402Schema = {
     description: {
       type: "string",
       description: "Description of the resource being paid for"
+    },
+    idempotencyKey: {
+      type: "string",
+      description: "Stable caller-supplied key for this user intent. Reuse it when resuming after user approval."
     }
   },
   required: ["url", "payTo", "amount", "asset", "network"]
 };
+var resumeX402Schema = {
+  type: "object",
+  properties: {
+    payment_id: {
+      type: "string",
+      description: "The payment or approval request ID returned by authorize_x402_payment."
+    },
+    url: {
+      type: "string",
+      description: "The original URL that returned HTTP 402."
+    },
+    payTo: {
+      type: "string",
+      description: "Payment recipient address from the original 402 response."
+    },
+    amount: {
+      type: "string",
+      description: "Payment amount in atomic units from the original 402 response."
+    },
+    asset: {
+      type: "string",
+      description: "Token contract address from the original 402 response."
+    },
+    network: {
+      type: "string",
+      description: "CAIP-2 chain ID or x402 network from the original 402 response."
+    },
+    description: {
+      type: "string",
+      description: "Description of the resource being paid for."
+    },
+    idempotencyKey: {
+      type: "string",
+      description: "Stable caller-supplied key used for the original authorization."
+    }
+  },
+  required: ["payment_id", "url", "payTo", "amount", "asset", "network"]
+};
 var authorizeMachinePaymentSchema = {
   type: "object",
   properties: {
@@ -1311,7 +1579,8 @@ var authorizeMachinePaymentSchema = {
 };
 var MAKE_PAYMENT_DESCRIPTION = "Request and sign a payment from the user-controlled Safe within approved on-chain limits. Haven authenticates the agent, validates the signed intent, and relays the Safe AllowanceModule transaction; it does not hold keys or control funds. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
 var GET_STATUS_DESCRIPTION = "Check the status of a previously initiated payment. Accepts payment intent IDs and approval request IDs. Returns the current status, phase, next_action, transaction hash if available, and payment details.";
-var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns x402 payment requirements, use this tool to sign with the agent-owned delegate key and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, call get_payment_status later, and retry the original x402 request only when next_action is retry_original_x402_request. Do not rewrite the SDK or loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request.";
+var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns x402 payment requirements, use this tool to sign with the agent-owned delegate key and request a policy-limited Safe AllowanceModule top-up when needed. Haven relays signed transactions only; the agent key authorizes payment and on-chain limits enforce spend. If this returns pending_approval, tell the user it is waiting in Haven, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not loop retries while approval is pending. Use the returned payment_header as the X-PAYMENT header on the retry request when doing a manual HTTP retry.";
+var RESUME_X402_DESCRIPTION = "Resume an x402 payment after the user approved it in Haven. Use this only after get_payment_status returns next_action=retry_original_x402_request. It checks the approved payment, validates the original x402 details, and returns a merchant X-PAYMENT header without creating a new approval request.";
 var AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION = "Authorize a Haven machine-payment challenge, currently for the internal MPP demo rail. The agent signs the payment, Haven relays it within the on-chain allowance, and the tool returns a proof header for the retry request.";
 function claudeTools() {
   return [
@@ -1330,6 +1599,11 @@ function claudeTools() {
       description: AUTHORIZE_X402_DESCRIPTION,
       input_schema: authorizeX402Schema
     },
+    {
+      name: "resume_x402_payment",
+      description: RESUME_X402_DESCRIPTION,
+      input_schema: resumeX402Schema
+    },
     {
       name: "authorize_machine_payment",
       description: AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION,
@@ -1363,6 +1637,14 @@ function openaiTools() {
         parameters: authorizeX402Schema
       }
     },
+    {
+      type: "function",
+      function: {
+        name: "resume_x402_payment",
+        description: RESUME_X402_DESCRIPTION,
+        parameters: resumeX402Schema
+      }
+    },
     {
       type: "function",
       function: {