@haven_ai/sdk 0.1.0 → 0.1.1

package/dist/index.js

@@ -1,6 +1,9 @@
+import { exact } from 'x402/schemes';
+import { privateKeyToAccount } from 'viem/accounts';
 import { ethers } from 'ethers';
+import { createHash } from 'crypto';
 
-// src/signer.ts
+// src/client.ts
 
 // src/types.ts
 var HavenError = class extends Error {
@@ -70,11 +73,66 @@ function verifySignature(hash, signature, expectedAddress) {
     return false;
   }
 }
-
-// src/x402.ts
+var BASE_USDC_ADDRESS = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913";
+var X402_IDEMPOTENCY_BUCKET_MS = 3e5;
+function decodeBase64Json(value, label) {
+  try {
+    return JSON.parse(atob(value));
+  } catch {
+    throw new Error(`Failed to decode ${label}`);
+  }
+}
+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") {
+    return null;
+  }
+  const amount = typeof candidate.amount === "string" ? candidate.amount : typeof candidate.maxAmountRequired === "string" ? candidate.maxAmountRequired : null;
+  if (!amount) return null;
+  return {
+    scheme: candidate.scheme,
+    network: candidate.network,
+    amount,
+    maxAmountRequired: candidate.maxAmountRequired,
+    resource: candidate.resource,
+    description: candidate.description,
+    mimeType: candidate.mimeType,
+    asset: candidate.asset,
+    payTo: candidate.payTo,
+    maxTimeoutSeconds: candidate.maxTimeoutSeconds ?? 30,
+    extra: candidate.extra
+  };
+}
+function normalizePaymentRequired(value) {
+  const candidate = value;
+  if (!candidate || typeof candidate !== "object" || typeof candidate.x402Version !== "number" || !Array.isArray(candidate.accepts)) {
+    return null;
+  }
+  const accepts = candidate.accepts.map((option) => normalizePaymentOption(option)).filter((option) => !!option);
+  if (accepts.length === 0) return null;
+  const first = accepts[0];
+  const resourceUrl = candidate.resource?.url ?? first.resource;
+  if (!resourceUrl) return null;
+  const resource = {
+    url: resourceUrl,
+    description: candidate.resource?.description ?? first.description,
+    mimeType: candidate.resource?.mimeType ?? first.mimeType
+  };
+  return {
+    x402Version: candidate.x402Version,
+    resource,
+    accepts,
+    error: candidate.error
+  };
+}
 var SUPPORTED_X402_NETWORKS = {
   "eip155:100": "Gnosis Chain",
-  "eip155:8453": "Base"
+  "eip155:8453": "Base",
+  "base": "Base"
+};
+var STANDARD_X402_NETWORKS = {
+  "eip155:8453": "base",
+  "base": "base"
 };
 var GNOSIS_TOKENS = {
   "0x0000000000000000000000000000000000000000": { symbol: "xDAI", decimals: 18 },
@@ -87,29 +145,41 @@ var BASE_TOKENS = {
 };
 var NETWORK_TOKENS = {
   "eip155:100": GNOSIS_TOKENS,
-  "eip155:8453": BASE_TOKENS
+  "eip155:8453": BASE_TOKENS,
+  "base": BASE_TOKENS
 };
 function parsePaymentRequired(response) {
   const v2Header = response.headers.get("PAYMENT-REQUIRED");
   if (v2Header) {
-    try {
-      return JSON.parse(atob(v2Header));
-    } catch {
-      throw new Error("Failed to decode PAYMENT-REQUIRED header");
-    }
+    const parsed = normalizePaymentRequired(
+      decodeBase64Json(v2Header, "PAYMENT-REQUIRED header")
+    );
+    if (parsed) return parsed;
   }
   const v1Header = response.headers.get("X-PAYMENT");
   if (v1Header) {
-    try {
-      return JSON.parse(atob(v1Header));
-    } catch {
-      throw new Error("Failed to decode X-PAYMENT header");
-    }
+    const parsed = normalizePaymentRequired(
+      decodeBase64Json(v1Header, "X-PAYMENT header")
+    );
+    if (parsed) return parsed;
   }
   throw new Error(
     "No x402 payment headers found in 402 response. Expected PAYMENT-REQUIRED (v2) or X-PAYMENT (v1) header."
   );
 }
+async function parsePaymentRequiredResponse(response) {
+  try {
+    return parsePaymentRequired(response);
+  } catch (headerErr) {
+    try {
+      const body = await response.clone().json();
+      const parsed = normalizePaymentRequired(body);
+      if (parsed) return parsed;
+    } catch {
+    }
+    throw headerErr;
+  }
+}
 function selectPaymentOption(accepts) {
   if (!accepts || accepts.length === 0) return null;
   for (const opt of accepts) {
@@ -125,13 +195,61 @@ function selectPaymentOption(accepts) {
   }
   return null;
 }
+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) {
+      return opt;
+    }
+  }
+  return null;
+}
+function toStandardPaymentRequirements(paymentRequired, option) {
+  const network = STANDARD_X402_NETWORKS[option.network];
+  if (!network) {
+    throw new Error(`x402 exact payments are not supported on ${option.network}`);
+  }
+  if (option.scheme !== "exact") {
+    throw new Error(`Unsupported x402 scheme: ${option.scheme}`);
+  }
+  return {
+    scheme: "exact",
+    network,
+    maxAmountRequired: option.maxAmountRequired ?? option.amount,
+    resource: option.resource ?? paymentRequired.resource.url,
+    description: option.description ?? paymentRequired.resource.description ?? "Haven x402 payment",
+    mimeType: option.mimeType ?? paymentRequired.resource.mimeType ?? "application/octet-stream",
+    payTo: option.payTo,
+    asset: option.asset,
+    maxTimeoutSeconds: option.maxTimeoutSeconds,
+    extra: option.extra
+  };
+}
+function buildX402IdempotencyKey(paymentRequired, option, now = Date.now()) {
+  const bucket = Math.floor(now / X402_IDEMPOTENCY_BUCKET_MS);
+  const material = [
+    paymentRequired.resource.url,
+    paymentRequired.resource.description ?? "",
+    option.payTo.toLowerCase(),
+    option.asset.toLowerCase(),
+    option.amount,
+    option.network,
+    bucket
+  ].join("|");
+  return `x402:${createHash("sha256").update(material).digest("hex").slice(0, 16)}`;
+}
 function encodePaymentProof(receipt) {
   const payload = {
     x402Version: 2,
+    resource: receipt.resourceUrl ? { url: receipt.resourceUrl } : void 0,
+    accepted: receipt.accepted,
     payload: {
+      type: "haven_tx_hash",
       txHash: receipt.txHash,
       paymentId: receipt.paymentId,
-      settledVia: "haven"
+      settledVia: "haven",
+      payer: receipt.payer,
+      chainId: receipt.chainId
     }
   };
   return btoa(JSON.stringify(payload));
@@ -144,25 +262,35 @@ var CHAIN_EXPLORER_TX = {
   8453: "https://basescan.org/tx"
 };
 function buildExplorerUrl(chainId, txHash) {
-  const base = CHAIN_EXPLORER_TX[chainId ?? 100] ?? CHAIN_EXPLORER_TX[100];
+  const base = CHAIN_EXPLORER_TX[chainId ?? 8453] ?? CHAIN_EXPLORER_TX[8453];
   return `${base}/${txHash}`;
 }
 var DEFAULT_REQUEST_TIMEOUT = 3e4;
 var DEFAULT_CONFIRMATION_TIMEOUT = 9e4;
 var DEFAULT_POLLING_INTERVAL = 3e3;
+function chainIdFromNetwork(network) {
+  if (network === "base") return 8453;
+  if (!network?.startsWith("eip155:")) return void 0;
+  const chainId = Number(network.slice("eip155:".length));
+  return Number.isFinite(chainId) ? chainId : void 0;
+}
 var HavenClient = class {
   apiKey;
   delegateKey;
   baseUrl;
+  x402Wallet;
   requestTimeout;
   confirmationTimeout;
   pollingInterval;
+  inFlightX402 = /* @__PURE__ */ new Map();
+  x402ReceiptCache = /* @__PURE__ */ new Map();
   /** Delegate address derived from the private key (if provided) */
   delegateAddress;
   constructor(config) {
     this.apiKey = config.apiKey;
     this.delegateKey = config.delegateKey;
     this.baseUrl = (config.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.x402Wallet = config.x402Wallet;
     this.requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT;
     this.confirmationTimeout = config.confirmationTimeout ?? DEFAULT_CONFIRMATION_TIMEOUT;
     this.pollingInterval = config.pollingInterval ?? DEFAULT_POLLING_INTERVAL;
@@ -202,6 +330,13 @@ var HavenClient = class {
       amount: request.amount,
       to: request.to
     });
+    if (raw.status === "pending_approval") {
+      throw new HavenApiError(
+        `Payment exceeds the on-chain allowance and was queued for owner approval (payment_id: ${raw.payment_id}).`,
+        202,
+        raw
+      );
+    }
     return {
       paymentId: raw.payment_id,
       status: "pending_signature",
@@ -269,8 +404,9 @@ var HavenClient = class {
   /**
    * Authorize an x402 payment.
    *
-   * Takes the parsed PaymentRequired from a 402 response, selects a
-   * compatible payment option, signs and executes the payment through Haven.
+   * Takes the parsed PaymentRequired from a 402 response, selects a compatible
+   * option, funds the delegate wallet through Haven, and returns the standard
+   * x402 header that the merchant can verify and settle.
    *
    * Requires `delegateKey` to be set in the client config.
    */
@@ -280,23 +416,43 @@ var HavenClient = class {
         "delegateKey is required for x402 payments. Pass it in the HavenClient config."
       );
     }
-    const option = selectPaymentOption(paymentRequired.accepts);
+    if (!this.delegateAddress) {
+      throw new HavenSigningError("delegateAddress could not be derived from delegateKey.");
+    }
+    const option = selectStandardPaymentOption(paymentRequired.accepts);
     if (!option) {
       throw new HavenApiError(
-        "No compatible payment option found in x402 requirements. Haven supports Gnosis Chain (eip155:100) and Base (eip155:8453).",
+        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
         400
       );
     }
+    const 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);
+    if (inFlight) return inFlight;
+    const promise = this.authorizeStandardX402(paymentRequired, option, idempotencyKey);
+    this.inFlightX402.set(idempotencyKey, promise);
+    try {
+      return await promise;
+    } finally {
+      this.inFlightX402.delete(idempotencyKey);
+    }
+  }
+  async authorizeStandardX402(paymentRequired, option, idempotencyKey) {
+    const paymentHeader = await this.createStandardX402Header(paymentRequired, option);
     const raw = await this.post("/x402", {
       url: paymentRequired.resource.url,
-      payTo: option.payTo,
+      payTo: this.delegateAddress,
+      merchantPayTo: option.payTo,
       amount: option.amount,
       asset: option.asset,
       network: option.network,
-      description: paymentRequired.resource.description
+      description: paymentRequired.resource.description,
+      idempotencyKey
     });
     if (raw.success && raw.tx_hash) {
-      return {
+      const receipt2 = {
         success: true,
         paymentId: raw.payment_id,
         txHash: raw.tx_hash,
@@ -304,8 +460,15 @@ var HavenClient = class {
         amount: raw.amount ?? "",
         to: raw.to ?? "",
         resourceUrl: paymentRequired.resource.url,
-        explorerUrl: raw.explorer_url ?? (raw.tx_hash ? buildExplorerUrl(raw.chain_id, raw.tx_hash) : "")
+        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)
       };
+      this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt2);
+      return receipt2;
     }
     if (!raw.sign_data?.hash) {
       throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
@@ -322,7 +485,7 @@ var HavenClient = class {
         execResult
       );
     }
-    return {
+    const receipt = {
       success: true,
       paymentId: raw.payment_id,
       txHash: execResult.tx_hash ?? "",
@@ -330,8 +493,15 @@ var HavenClient = class {
       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) : "")
+      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)
     };
+    this.cacheX402Receipt(idempotencyKey, paymentHeader, receipt);
+    return receipt;
   }
   /**
    * Fetch wrapper that automatically handles HTTP 402 responses.
@@ -347,21 +517,82 @@ var HavenClient = class {
    * Requires `delegateKey` to be set in the client config.
    */
   async fetch(url, init) {
-    const response = await globalThis.fetch(url, init);
+    const initialInit = this.withX402Wallet(init, this.x402PayerAddress());
+    const response = await globalThis.fetch(url, initialInit);
     if (response.status !== 402) return response;
     let paymentRequired;
     try {
-      paymentRequired = parsePaymentRequired(response);
+      paymentRequired = await parsePaymentRequiredResponse(response);
     } catch {
       return response;
     }
     const receipt = await this.authorizeX402(paymentRequired);
-    const retryHeaders = new Headers(init?.headers);
-    retryHeaders.set("PAYMENT-SIGNATURE", encodePaymentProof(receipt));
-    return globalThis.fetch(url, {
-      ...init,
+    if (!receipt.accepted) {
+      throw new HavenApiError("No accepted x402 option was recorded for payment retry", 500);
+    }
+    if (!receipt.paymentHeader) {
+      throw new HavenApiError("No x402 payment header was returned for payment retry", 500);
+    }
+    const retryHeaders = new Headers(initialInit?.headers);
+    retryHeaders.set("X-PAYMENT", receipt.paymentHeader);
+    const retryResponse = await globalThis.fetch(url, {
+      ...initialInit,
       headers: retryHeaders
     });
+    if (retryResponse.status === 402) {
+      throw new HavenApiError(
+        "x402 retry was rejected after Haven funded the delegate wallet; reconciliation may be required.",
+        402,
+        {
+          marker: "x402_retry_rejected_after_funding",
+          payment_id: receipt.paymentId,
+          tx_hash: receipt.txHash,
+          resource_url: receipt.resourceUrl,
+          merchant_to: receipt.merchantTo,
+          delegate_to: receipt.to
+        }
+      );
+    }
+    return retryResponse;
+  }
+  async createStandardX402Header(paymentRequired, option) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError("delegateKey is required to sign x402 payment headers.");
+    }
+    const account = privateKeyToAccount(this.delegateKey);
+    const requirements = toStandardPaymentRequirements(paymentRequired, option);
+    const header = await exact.evm.createPaymentHeader(
+      account,
+      paymentRequired.x402Version,
+      requirements
+    );
+    if (paymentRequired.x402Version < 2) return header;
+    const payment = decodeBase64Json2(header);
+    return btoa(JSON.stringify({
+      x402Version: paymentRequired.x402Version,
+      accepted: option,
+      payload: payment.payload
+    }));
+  }
+  cacheX402Receipt(idempotencyKey, paymentHeader, receipt) {
+    const expiresAt = getPaymentHeaderValidBefore(paymentHeader);
+    if (expiresAt > Date.now()) {
+      this.x402ReceiptCache.set(idempotencyKey, { expiresAt, receipt });
+    }
+  }
+  x402PayerAddress() {
+    return this.delegateAddress ?? this.x402Wallet;
+  }
+  withX402Wallet(init, wallet = this.x402PayerAddress()) {
+    if (!wallet) return init;
+    const headers = new Headers(init?.headers);
+    if (!headers.has("x402-wallet")) {
+      headers.set("x402-wallet", wallet);
+    }
+    return {
+      ...init,
+      headers
+    };
   }
   // ── Tool Execution (for agent frameworks) ────────────────────────
   /**
@@ -424,7 +655,11 @@ var HavenClient = class {
           amount: receipt.amount,
           to: receipt.to,
           resource_url: receipt.resourceUrl,
-          explorer_url: receipt.explorerUrl
+          explorer_url: receipt.explorerUrl,
+          payment_header: receipt.paymentHeader,
+          merchant_to: receipt.merchantTo,
+          payer: receipt.payer,
+          chain_id: receipt.chainId
         };
       } catch (err) {
         return {
@@ -510,6 +745,21 @@ var HavenClient = class {
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function getPaymentHeaderValidBefore(paymentHeader) {
+  try {
+    const payment = decodeBase64Json2(
+      paymentHeader
+    );
+    const payload = payment.payload;
+    const validBeforeSeconds = Number(payload.authorization?.validBefore);
+    if (Number.isFinite(validBeforeSeconds)) return validBeforeSeconds * 1e3;
+  } catch {
+  }
+  return 0;
+}
+function decodeBase64Json2(value) {
+  return JSON.parse(atob(value));
+}
 
 // src/tools.ts
 var makePaymentSchema = {
@@ -576,7 +826,7 @@ var authorizeX402Schema = {
 };
 var MAKE_PAYMENT_DESCRIPTION = "Send a payment from the Haven-managed Safe wallet. The payment will be validated against the agent's on-chain spending policy. Gnosis Chain tokens: EURe, USDC.e, xDAI. Base tokens: USDC, ETH.";
 var GET_STATUS_DESCRIPTION = "Check the status of a previously initiated payment. Returns the current status, transaction hash (if confirmed), and payment details.";
-var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns 402 with x402 payment requirements, use this tool to pay and get access. Haven evaluates the payment against policy and executes from the Safe wallet.";
+var AUTHORIZE_X402_DESCRIPTION = "Authorize payment for an HTTP 402 (Payment Required) response. When a paid API returns 402 with x402 payment requirements, use this tool to fund the agent wallet and get a merchant payment header. Haven evaluates the payment against policy before moving funds from the Haven wallet. Use the returned payment_header as the X-PAYMENT header on the retry request.";
 function claudeTools() {
   return [
     {
@@ -631,6 +881,6 @@ var havenTools = {
   openai: openaiTools
 };
 
-export { HavenApiError, HavenClient, HavenError, HavenSigningError, HavenTimeoutError, addressFromKey, encodePaymentProof, havenTools, parsePaymentRequired, selectPaymentOption, signHash, verifySignature };
+export { HavenApiError, HavenClient, HavenError, HavenSigningError, HavenTimeoutError, addressFromKey, encodePaymentProof, havenTools, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map