@haven_ai/sdk 0.1.0 → 0.1.2

package/dist/index.cjs

@@ -1,8 +1,11 @@
 'use strict';
 
+var schemes = require('x402/schemes');
+var accounts = require('viem/accounts');
 var ethers = require('ethers');
+var crypto = require('crypto');
 
-// src/signer.ts
+// src/client.ts
 
 // src/types.ts
 var HavenError = class extends Error {
@@ -18,13 +21,30 @@ var HavenError = class extends Error {
   paymentId;
 };
 var HavenApiError = class extends HavenError {
-  constructor(message, statusCode, body) {
-    super(message, "API_ERROR", statusCode);
+  constructor(message, statusCode, body, paymentId) {
+    super(message, "API_ERROR", statusCode, paymentId);
     this.body = body;
     this.name = "HavenApiError";
   }
   body;
 };
+var HavenPaymentStateError = class extends HavenApiError {
+  constructor(message, statusCode, state, body) {
+    super(message, statusCode, body, state.paymentId);
+    this.state = state;
+    this.name = "HavenPaymentStateError";
+  }
+  state;
+  get status() {
+    return this.state.status;
+  }
+  get phase() {
+    return this.state.phase;
+  }
+  get nextAction() {
+    return this.state.nextAction;
+  }
+};
 var HavenSigningError = class extends HavenError {
   constructor(message) {
     super(message, "SIGNING_ERROR");
@@ -72,11 +92,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 },
@@ -89,29 +164,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) {
@@ -127,17 +214,139 @@ 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:${crypto.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));
 }
+function decodeBase64Json2(value, label) {
+  try {
+    return JSON.parse(atob(value));
+  } catch {
+    throw new Error(`Failed to decode ${label}`);
+  }
+}
+function normalizeChallenge(value) {
+  const candidate = value;
+  if (!candidate || typeof candidate !== "object" || candidate.rail !== "mpp_demo" || typeof candidate.version !== "string" || typeof candidate.challengeId !== "string" || typeof candidate.resource !== "string" || typeof candidate.description !== "string" || // TODO: relax these checks when non-demo machine payment rails are added.
+  candidate.network?.chainId !== 8453 || candidate.network?.name !== "base" || candidate.asset?.symbol !== "USDC" || typeof candidate.asset?.address !== "string" || candidate.asset.decimals !== 6 || typeof candidate.amount?.display !== "string" || typeof candidate.amount?.atomic !== "string" || typeof candidate.recipient !== "string" || typeof candidate.expiresAt !== "string") {
+    return null;
+  }
+  return {
+    rail: candidate.rail,
+    version: candidate.version,
+    challengeId: candidate.challengeId,
+    resource: candidate.resource,
+    description: candidate.description,
+    network: candidate.network,
+    asset: candidate.asset,
+    amount: candidate.amount,
+    recipient: candidate.recipient,
+    expiresAt: candidate.expiresAt,
+    metadata: candidate.metadata
+  };
+}
+function parseMachinePaymentChallenge(response) {
+  const header = response.headers.get("MACHINE-PAYMENT-CHALLENGE");
+  if (!header) {
+    throw new Error("No MACHINE-PAYMENT-CHALLENGE header found in 402 response.");
+  }
+  const parsed = normalizeChallenge(
+    decodeBase64Json2(header, "MACHINE-PAYMENT-CHALLENGE header")
+  );
+  if (!parsed) throw new Error("Invalid machine payment challenge");
+  return parsed;
+}
+async function parseMachinePaymentChallengeResponse(response) {
+  try {
+    return parseMachinePaymentChallenge(response);
+  } catch (headerErr) {
+    try {
+      const body = await response.clone().json();
+      const parsed = normalizeChallenge(body.challenge);
+      if (parsed) return parsed;
+    } catch {
+    }
+    throw headerErr;
+  }
+}
+function buildMachinePaymentIdempotencyKey(challenge) {
+  const material = [
+    challenge.rail,
+    challenge.challengeId,
+    challenge.resource,
+    challenge.recipient.toLowerCase(),
+    challenge.asset.address.toLowerCase(),
+    challenge.amount.atomic,
+    challenge.network.chainId
+  ].join("|");
+  return `${challenge.rail}:${crypto.createHash("sha256").update(material).digest("hex").slice(0, 16)}`;
+}
+function encodeMachinePaymentProof(receipt) {
+  return btoa(JSON.stringify({
+    rail: receipt.rail,
+    challengeId: receipt.challengeId,
+    paymentId: receipt.paymentId,
+    txHash: receipt.txHash,
+    settledVia: "haven",
+    payer: receipt.payer,
+    chainId: receipt.chainId
+  }));
+}
 
 // src/client.ts
 var DEFAULT_BASE_URL = "http://localhost:3001";
@@ -146,25 +355,89 @@ 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;
+var PAYMENT_STATE_STATUS_CODES = {
+  pending: 202,
+  pending_approval: 202,
+  approved: 202,
+  proposed: 202,
+  executed: 200,
+  pending_signature: 409,
+  submitted: 409,
+  expired: 410,
+  failed: 502,
+  rejected: 409
+};
+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;
+}
+function phaseForStatus(status) {
+  if (status === "pending_signature") return "agent_signature_required";
+  if (status === "submitted") return "payment_submitted";
+  if (status === "confirmed") return "payment_confirmed";
+  if (status === "pending" || status === "pending_approval") return "user_approval_required";
+  if (status === "approved") return "user_execution_required";
+  if (status === "proposed") return "waiting_for_additional_approvals";
+  if (status === "executed") return "funding_sent";
+  if (status === "rejected") return "rejected";
+  if (status === "expired") return "expired";
+  if (status === "failed") return "failed";
+  return null;
+}
+function nextActionForStatus(status) {
+  if (status === "pending_signature") return "sign_and_submit_payment";
+  if (status === "submitted") return "check_status_later";
+  if (status === "confirmed") return "none";
+  if (status === "pending" || status === "pending_approval") return "wait_for_user_approval";
+  if (status === "approved") return "wait_for_user_to_complete_payment";
+  if (status === "proposed") return "wait_for_user_approval";
+  if (status === "executed") return "retry_original_x402_request";
+  if (status === "rejected") return "stop_and_tell_user";
+  if (status === "expired") return "request_again_if_user_still_wants_it";
+  if (status === "failed") return "stop_and_tell_user";
+  return null;
+}
+function messageForState(label, status, paymentId, nextAction) {
+  if (status === "pending" || status === "pending_approval") {
+    return `${label} is above the remaining agent budget and is waiting for user approval in Haven (payment_id: ${paymentId}).`;
+  }
+  if (status === "executed") {
+    return "The user completed the funding payment. Retry the original x402 request.";
+  }
+  if (status === "rejected") {
+    return `The user rejected this payment request (payment_id: ${paymentId}).`;
+  }
+  if (status === "expired") {
+    return `This payment request expired (payment_id: ${paymentId}).`;
+  }
+  return `${label} is ${status}; next_action=${nextAction} (payment_id: ${paymentId}).`;
+}
 var HavenClient = class {
   apiKey;
   delegateKey;
   baseUrl;
+  x402Wallet;
   requestTimeout;
   confirmationTimeout;
   pollingInterval;
+  inFlightX402 = /* @__PURE__ */ new Map();
+  x402ReceiptCache = /* @__PURE__ */ new Map();
+  inFlightMachinePayments = /* @__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;
@@ -204,6 +477,9 @@ var HavenClient = class {
       amount: request.amount,
       to: request.to
     });
+    if (raw.status === "pending_approval") {
+      this.throwPaymentStateError("Payment", raw);
+    }
     return {
       paymentId: raw.payment_id,
       status: "pending_signature",
@@ -253,6 +529,16 @@ var HavenClient = class {
     const raw = await this.get(`/payments/${paymentId}`);
     return this.mapPaymentResult(raw);
   }
+  /**
+   * Get agent-actionable status for a payment intent or approval request.
+   *
+   * Use this for IDs returned by agent tools and machine-payment/x402 flows.
+   * `getPayment()` remains available for payment-intent-only integrations.
+   */
+  async getPaymentStatus(paymentId) {
+    const raw = await this.get(`/machine-payments/${paymentId}/status`);
+    return this.mapPaymentStatusResult(raw);
+  }
   /**
    * Poll until a payment reaches a terminal status (confirmed, failed, expired).
    */
@@ -271,8 +557,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.
    */
@@ -282,23 +569,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,
@@ -306,9 +613,17 @@ 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;
     }
+    this.throwIfNonSignableAuthorizationState("x402 payment", raw);
     if (!raw.sign_data?.hash) {
       throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
     }
@@ -318,13 +633,9 @@ var HavenClient = class {
       { signature: sig }
     );
     if (execResult.status !== "confirmed") {
-      throw new HavenApiError(
-        execResult.error ?? `x402 payment ${execResult.status}`,
-        502,
-        execResult
-      );
+      this.throwPaymentStateError("x402 payment", execResult);
     }
-    return {
+    const receipt = {
       success: true,
       paymentId: raw.payment_id,
       txHash: execResult.tx_hash ?? "",
@@ -332,8 +643,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.
@@ -349,21 +667,314 @@ 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;
+    const machineChallengeHeader = response.headers.get("MACHINE-PAYMENT-CHALLENGE");
+    if (machineChallengeHeader) {
+      const challenge = await parseMachinePaymentChallengeResponse(response);
+      return this.fetchWithMachinePayment(url, initialInit, challenge);
+    }
     let paymentRequired;
     try {
-      paymentRequired = parsePaymentRequired(response);
+      paymentRequired = await parsePaymentRequiredResponse(response);
     } catch {
-      return response;
+      let challenge;
+      try {
+        challenge = await parseMachinePaymentChallengeResponse(response);
+      } catch {
+        return response;
+      }
+      return this.fetchWithMachinePayment(url, initialInit, challenge);
     }
     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) {
+      await this.recordMerchantRetryRejected({
+        rail: "x402",
+        paymentId: receipt.paymentId,
+        txHash: receipt.txHash,
+        resourceUrl: receipt.resourceUrl,
+        retryResponse,
+        details: {
+          merchant_to: receipt.merchantTo,
+          delegate_to: receipt.to
+        }
+      });
+      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
+        }
+      );
+    }
+    await this.reportMachinePaymentEvidence({
+      paymentId: receipt.paymentId,
+      rail: "x402",
+      txHash: receipt.txHash,
+      resourceUrl: receipt.resourceUrl,
+      merchantStatus: retryResponse.status,
+      challengePayload: paymentRequired,
+      selectedPayment: receipt.accepted,
+      paymentProofHeaderName: "X-PAYMENT",
+      paymentProofHeader: receipt.paymentHeader,
+      protocolReceiptHeaderName: "PAYMENT-RESPONSE",
+      protocolReceiptHeader: retryResponse.headers.get("PAYMENT-RESPONSE") ?? void 0
+    });
+    return retryResponse;
+  }
+  async authorizeMachinePayment(challenge) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError(
+        "delegateKey is required for machine payments. Pass it in the HavenClient config."
+      );
+    }
+    if (challenge.rail !== "mpp_demo") {
+      throw new HavenApiError(`Unsupported machine payment rail: ${challenge.rail}`, 400);
+    }
+    const idempotencyKey = buildMachinePaymentIdempotencyKey(challenge);
+    const inFlight = this.inFlightMachinePayments.get(idempotencyKey);
+    if (inFlight) return inFlight;
+    const promise = this.authorizeMppDemoPayment(challenge, idempotencyKey);
+    this.inFlightMachinePayments.set(idempotencyKey, promise);
+    try {
+      return await promise;
+    } finally {
+      this.inFlightMachinePayments.delete(idempotencyKey);
+    }
+  }
+  async authorizeMppDemoPayment(challenge, idempotencyKey) {
+    const raw = await this.post(
+      "/machine-payments/authorize",
+      { challenge, idempotencyKey }
+    );
+    if (raw.success && raw.tx_hash) {
+      return this.mapMachinePaymentReceipt(challenge, raw, raw.tx_hash);
+    }
+    this.throwIfNonSignableAuthorizationState("Machine payment", raw);
+    if (!raw.sign_data?.hash) {
+      throw new HavenApiError("No sign_hash returned from machine payment authorization", 500, raw);
+    }
+    const sig = signHash(this.delegateKey, raw.sign_data.hash);
+    const execResult = await this.post(
+      `/payments/${raw.payment_id}/sign`,
+      { signature: sig }
+    );
+    if (execResult.status !== "confirmed" || !execResult.tx_hash) {
+      this.throwPaymentStateError("Machine payment", execResult);
+    }
+    return this.mapMachinePaymentReceipt(challenge, raw, execResult.tx_hash, execResult);
+  }
+  async fetchWithMachinePayment(url, initialInit, challenge) {
+    const receipt = await this.authorizeMachinePayment(challenge);
+    const retryHeaders = new Headers(initialInit?.headers);
+    retryHeaders.set("MACHINE-PAYMENT-PROOF", receipt.proofHeader);
+    const retryResponse = await globalThis.fetch(url, {
+      ...initialInit,
+      headers: retryHeaders
+    });
+    if (retryResponse.status === 402) {
+      await this.recordMerchantRetryRejected({
+        rail: receipt.rail,
+        paymentId: receipt.paymentId,
+        txHash: receipt.txHash,
+        resourceUrl: receipt.resourceUrl,
+        retryResponse,
+        details: {
+          challenge_id: receipt.challengeId
+        }
+      });
+      throw new HavenApiError(
+        "Machine payment retry was rejected after Haven sent the payment.",
+        402,
+        {
+          marker: "machine_payment_retry_rejected_after_payment",
+          payment_id: receipt.paymentId,
+          tx_hash: receipt.txHash,
+          resource_url: receipt.resourceUrl,
+          rail: receipt.rail
+        }
+      );
+    }
+    await this.reportMachinePaymentEvidence({
+      paymentId: receipt.paymentId,
+      rail: receipt.rail,
+      txHash: receipt.txHash,
+      resourceUrl: receipt.resourceUrl,
+      merchantStatus: retryResponse.status,
+      challengePayload: challenge,
+      paymentProofHeaderName: "MACHINE-PAYMENT-PROOF",
+      paymentProofHeader: receipt.proofHeader,
+      protocolReceiptHeaderName: retryResponse.headers.has("Payment-Receipt") ? "Payment-Receipt" : retryResponse.headers.has("MACHINE-PAYMENT-RESPONSE") ? "MACHINE-PAYMENT-RESPONSE" : void 0,
+      protocolReceiptHeader: retryResponse.headers.get("Payment-Receipt") ?? retryResponse.headers.get("MACHINE-PAYMENT-RESPONSE") ?? void 0
+    });
+    return retryResponse;
+  }
+  async createStandardX402Header(paymentRequired, option) {
+    if (!this.delegateKey) {
+      throw new HavenSigningError("delegateKey is required to sign x402 payment headers.");
+    }
+    const account = accounts.privateKeyToAccount(this.delegateKey);
+    const requirements = toStandardPaymentRequirements(paymentRequired, option);
+    const header = await schemes.exact.evm.createPaymentHeader(
+      account,
+      paymentRequired.x402Version,
+      requirements
+    );
+    if (paymentRequired.x402Version < 2) return header;
+    const payment = decodeBase64Json3(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 });
+    }
+  }
+  mapMachinePaymentReceipt(challenge, raw, txHash, execResult) {
+    const receiptWithoutHeader = {
+      success: true,
+      rail: challenge.rail,
+      paymentId: raw.payment_id,
+      challengeId: challenge.challengeId,
+      txHash,
+      token: execResult?.token ?? raw.token ?? challenge.asset.symbol,
+      amount: execResult?.amount ?? raw.amount ?? challenge.amount.display,
+      to: execResult?.to ?? raw.to ?? challenge.recipient,
+      resourceUrl: raw.resource_url ?? challenge.resource,
+      explorerUrl: execResult?.explorer_url ?? raw.explorer_url ?? buildExplorerUrl(execResult?.chain_id ?? raw.chain_id ?? challenge.network.chainId, txHash),
+      payer: raw.payer ?? raw.safe_address,
+      chainId: execResult?.chain_id ?? raw.chain_id ?? challenge.network.chainId
+    };
+    return {
+      ...receiptWithoutHeader,
+      proofHeader: encodeMachinePaymentProof(receiptWithoutHeader)
+    };
+  }
+  async recordMerchantRetryRejected(input) {
+    try {
+      await this.post("/machine-payments/reconciliation-events", {
+        paymentId: input.paymentId,
+        rail: input.rail,
+        eventType: "merchant_retry_rejected_after_payment",
+        txHash: input.txHash,
+        reason: `Merchant returned HTTP ${input.retryResponse.status} after Haven payment confirmation`,
+        details: {
+          resource_url: input.resourceUrl,
+          retry_status: input.retryResponse.status,
+          retry_body: await responseSnippet(input.retryResponse),
+          ...input.details
+        }
+      });
+    } catch {
+    }
+  }
+  async reportMachinePaymentEvidence(input) {
+    try {
+      await this.post("/machine-payments/evidence", {
+        paymentId: input.paymentId,
+        rail: input.rail,
+        txHash: input.txHash,
+        resourceUrl: input.resourceUrl,
+        merchantStatus: input.merchantStatus,
+        challengePayload: input.challengePayload,
+        selectedPayment: input.selectedPayment,
+        paymentProofHeaderName: input.paymentProofHeaderName,
+        paymentProofHeader: input.paymentProofHeader,
+        protocolReceiptHeaderName: input.protocolReceiptHeaderName,
+        protocolReceiptHeader: input.protocolReceiptHeader,
+        protocolReceiptPayload: input.protocolReceiptHeader ? parseProtocolReceiptHeader(input.protocolReceiptHeader) : void 0
+      });
+    } catch {
+    }
+  }
+  throwIfNonSignableAuthorizationState(label, raw) {
+    if (raw.status === "pending_signature") return;
+    this.throwPaymentStateError(label, raw);
+  }
+  throwPaymentStateError(label, raw) {
+    const statusCode = PAYMENT_STATE_STATUS_CODES[raw.status] ?? 502;
+    const state = this.paymentStateFromRaw(label, raw);
+    if (state) {
+      throw new HavenPaymentStateError(state.message, statusCode, state, raw);
+    }
+    if (raw.status === "pending_approval") {
+      throw new HavenApiError(
+        `${label} exceeds the on-chain allowance and was queued for owner approval (payment_id: ${raw.payment_id}).`,
+        statusCode,
+        raw
+      );
+    }
+    if (raw.status === "expired") {
+      throw new HavenApiError(
+        `${label} expired before it could be completed (payment_id: ${raw.payment_id}).`,
+        statusCode,
+        raw
+      );
+    }
+    const paymentId = raw.payment_id ? ` (payment_id: ${raw.payment_id})` : "";
+    const message = raw.error ?? `${label} ${raw.status}${paymentId}`;
+    throw new HavenApiError(message, statusCode, raw);
+  }
+  paymentStateFromRaw(label, raw) {
+    if (!raw.payment_id || !raw.status) return null;
+    const phase = raw.phase ?? phaseForStatus(raw.status);
+    const nextAction = raw.next_action ?? nextActionForStatus(raw.status);
+    if (!phase || !nextAction) return null;
+    const amount = raw.amount ?? raw.requested ?? "";
+    const token = raw.token ?? "";
+    const message = raw.message ?? raw.error ?? messageForState(label, raw.status, raw.payment_id, nextAction);
+    return {
+      paymentId: raw.payment_id,
+      kind: raw.kind === "payment_intent" ? "payment_intent" : "approval_request",
+      rail: raw.rail ?? "direct",
+      status: raw.status === "pending" ? "pending_approval" : raw.status,
+      phase,
+      nextAction,
+      amount,
+      token,
+      resourceUrl: raw.resource_url ?? null,
+      merchantAddress: raw.merchant_to ?? null,
+      txHash: raw.tx_hash ?? null,
+      expiresAt: raw.expires_at ?? "",
+      chainId: raw.chain_id ?? 0,
+      message
+    };
+  }
+  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) ────────────────────────
   /**
@@ -395,10 +1006,7 @@ var HavenClient = class {
           error: result.errorMessage
         };
       } catch (err) {
-        return {
-          success: false,
-          error: err instanceof Error ? err.message : String(err)
-        };
+        return this.toolError(err);
       }
     }
     if (toolName === "authorize_x402_payment") {
@@ -426,30 +1034,95 @@ 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 this.toolError(err);
+      }
+    }
+    if (toolName === "authorize_machine_payment") {
+      const { challenge } = input;
+      try {
+        const receipt = await this.authorizeMachinePayment(challenge);
         return {
-          success: false,
-          error: err instanceof Error ? err.message : String(err)
+          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,
+          proof_header: receipt.proofHeader,
+          rail: receipt.rail,
+          challenge_id: receipt.challengeId,
+          payer: receipt.payer,
+          chain_id: receipt.chainId
         };
+      } catch (err) {
+        return this.toolError(err);
       }
     }
     if (toolName === "get_payment_status") {
       const { payment_id } = input;
-      const result = await this.getPayment(payment_id);
+      const result = await this.getPaymentStatus(payment_id);
       return {
         payment_id: result.paymentId,
+        kind: result.kind,
+        rail: result.rail,
         status: result.status,
+        phase: result.phase,
+        next_action: result.nextAction,
         tx_hash: result.txHash,
         token: result.token,
         amount: result.amount,
-        to: result.to,
-        explorer_url: result.explorerUrl
+        resource_url: result.resourceUrl,
+        merchant_address: result.merchantAddress,
+        expires_at: result.expiresAt,
+        chain_id: result.chainId,
+        message: result.message
       };
     }
     throw new Error(`Unknown tool: ${toolName}`);
   }
+  toolError(err) {
+    if (err instanceof HavenPaymentStateError) {
+      return {
+        success: false,
+        payment_id: err.state.paymentId,
+        kind: err.state.kind,
+        rail: err.state.rail,
+        status: err.state.status,
+        phase: err.state.phase,
+        next_action: err.state.nextAction,
+        tx_hash: err.state.txHash,
+        token: err.state.token,
+        amount: err.state.amount,
+        resource_url: err.state.resourceUrl,
+        merchant_address: err.state.merchantAddress,
+        expires_at: err.state.expiresAt,
+        chain_id: err.state.chainId,
+        message: err.state.message,
+        error: err.message
+      };
+    }
+    if (err instanceof HavenApiError) {
+      return {
+        success: false,
+        status_code: err.statusCode,
+        error: err.message,
+        body: err.body
+      };
+    }
+    return {
+      success: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
   // ── HTTP Helpers ─────────────────────────────────────────────────
   async post(path, body) {
     return this.request("POST", path, body);
@@ -508,10 +1181,62 @@ var HavenClient = class {
       expiresAt: raw.expires_at
     };
   }
+  mapPaymentStatusResult(raw) {
+    return {
+      paymentId: raw.payment_id,
+      kind: raw.kind,
+      rail: raw.rail,
+      status: raw.status,
+      phase: raw.phase,
+      nextAction: raw.next_action,
+      amount: raw.amount,
+      token: raw.token,
+      resourceUrl: raw.resource_url,
+      merchantAddress: raw.merchant_address,
+      txHash: raw.tx_hash,
+      expiresAt: raw.expires_at,
+      chainId: raw.chain_id,
+      message: raw.message
+    };
+  }
 };
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+function getPaymentHeaderValidBefore(paymentHeader) {
+  try {
+    const payment = decodeBase64Json3(
+      paymentHeader
+    );
+    const payload = payment.payload;
+    const validBeforeSeconds = Number(payload.authorization?.validBefore);
+    if (Number.isFinite(validBeforeSeconds)) return validBeforeSeconds * 1e3;
+  } catch {
+  }
+  return 0;
+}
+function decodeBase64Json3(value) {
+  return JSON.parse(atob(value));
+}
+function parseProtocolReceiptHeader(value) {
+  try {
+    return JSON.parse(atob(value));
+  } catch {
+    try {
+      return JSON.parse(value);
+    } catch {
+      return void 0;
+    }
+  }
+}
+async function responseSnippet(response) {
+  try {
+    const text = await response.clone().text();
+    return text.slice(0, 1e3) || null;
+  } catch {
+    return null;
+  }
+}
 
 // src/tools.ts
 var makePaymentSchema = {
@@ -576,9 +1301,20 @@ var authorizeX402Schema = {
   },
   required: ["url", "payTo", "amount", "asset", "network"]
 };
-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 authorizeMachinePaymentSchema = {
+  type: "object",
+  properties: {
+    challenge: {
+      type: "object",
+      description: "Machine payment challenge returned by a Haven demo endpoint"
+    }
+  },
+  required: ["challenge"]
+};
+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_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 [
     {
@@ -595,6 +1331,11 @@ function claudeTools() {
       name: "authorize_x402_payment",
       description: AUTHORIZE_X402_DESCRIPTION,
       input_schema: authorizeX402Schema
+    },
+    {
+      name: "authorize_machine_payment",
+      description: AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION,
+      input_schema: authorizeMachinePaymentSchema
     }
   ];
 }
@@ -623,6 +1364,14 @@ function openaiTools() {
         description: AUTHORIZE_X402_DESCRIPTION,
         parameters: authorizeX402Schema
       }
+    },
+    {
+      type: "function",
+      function: {
+        name: "authorize_machine_payment",
+        description: AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION,
+        parameters: authorizeMachinePaymentSchema
+      }
     }
   ];
 }
@@ -636,12 +1385,18 @@ var havenTools = {
 exports.HavenApiError = HavenApiError;
 exports.HavenClient = HavenClient;
 exports.HavenError = HavenError;
+exports.HavenPaymentStateError = HavenPaymentStateError;
 exports.HavenSigningError = HavenSigningError;
 exports.HavenTimeoutError = HavenTimeoutError;
 exports.addressFromKey = addressFromKey;
+exports.buildMachinePaymentIdempotencyKey = buildMachinePaymentIdempotencyKey;
+exports.encodeMachinePaymentProof = encodeMachinePaymentProof;
 exports.encodePaymentProof = encodePaymentProof;
 exports.havenTools = havenTools;
+exports.parseMachinePaymentChallenge = parseMachinePaymentChallenge;
+exports.parseMachinePaymentChallengeResponse = parseMachinePaymentChallengeResponse;
 exports.parsePaymentRequired = parsePaymentRequired;
+exports.parsePaymentRequiredResponse = parsePaymentRequiredResponse;
 exports.selectPaymentOption = selectPaymentOption;
 exports.signHash = signHash;
 exports.verifySignature = verifySignature;