@haven_ai/sdk 0.1.1 → 0.1.3

package/dist/index.cjs

@@ -21,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");
@@ -256,6 +273,80 @@ function encodePaymentProof(receipt) {
   };
   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";
@@ -267,15 +358,93 @@ 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;
+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}).`;
+}
+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;
@@ -286,6 +455,7 @@ var HavenClient = class {
   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) {
@@ -333,11 +503,7 @@ var HavenClient = class {
       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
-      );
+      this.throwPaymentStateError("Payment", raw);
     }
     return {
       paymentId: raw.payment_id,
@@ -388,6 +554,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).
    */
@@ -412,7 +588,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."
@@ -428,7 +604,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);
@@ -454,24 +630,17 @@ 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;
+    }
+    this.throwIfNonSignableAuthorizationState("x402 payment", raw);
     if (!raw.sign_data?.hash) {
       throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
     }
@@ -481,30 +650,55 @@ var HavenClient = class {
       { signature: sig }
     );
     if (execResult.status !== "confirmed") {
+      this.throwPaymentStateError("x402 payment", execResult);
+    }
+    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(
-        execResult.error ?? `x402 payment ${execResult.status}`,
-        502,
-        execResult
+        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
+        400
       );
     }
-    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 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.
    *
@@ -518,17 +712,31 @@ 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;
+    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 = 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 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);
     }
@@ -542,6 +750,17 @@ var HavenClient = class {
       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,
@@ -555,8 +774,260 @@ 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",
+      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;
   }
+  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.");
@@ -569,7 +1040,7 @@ var HavenClient = class {
       requirements
     );
     if (paymentRequired.x402Version < 2) return header;
-    const payment = decodeBase64Json2(header);
+    const payment = decodeBase64Json3(header);
     return btoa(JSON.stringify({
       x402Version: paymentRequired.x402Version,
       accepted: option,
@@ -582,6 +1053,116 @@ var HavenClient = class {
       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;
   }
@@ -626,29 +1207,38 @@ 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") {
-      const { url, payTo, amount, asset, network, description } = input;
+      const { url, payTo, amount, asset, network, description, idempotencyKey } = input;
+      try {
+        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.authorizeX402({
-          x402Version: 2,
-          resource: { url, description },
-          accepts: [
-            {
-              scheme: "exact",
-              network,
-              amount,
-              asset,
-              payTo,
-              maxTimeoutSeconds: 30
-            }
-          ]
+        const receipt = await this.resumeAuthorizedX402({
+          paymentId: payment_id,
+          paymentRequired: this.toolX402PaymentRequired({ url, payTo, amount, asset, network, description }),
+          idempotencyKey
         });
+        return this.x402ToolReceipt(receipt);
+      } catch (err) {
+        return this.toolError(err);
+      }
+    }
+    if (toolName === "authorize_machine_payment") {
+      const { challenge } = input;
+      try {
+        const receipt = await this.authorizeMachinePayment(challenge);
         return {
           success: true,
           payment_id: receipt.paymentId,
@@ -658,33 +1248,107 @@ var HavenClient = class {
           to: receipt.to,
           resource_url: receipt.resourceUrl,
           explorer_url: receipt.explorerUrl,
-          payment_header: receipt.paymentHeader,
-          merchant_to: receipt.merchantTo,
+          proof_header: receipt.proofHeader,
+          rail: receipt.rail,
+          challenge_id: receipt.challengeId,
           payer: receipt.payer,
           chain_id: receipt.chainId
         };
       } catch (err) {
-        return {
-          success: false,
-          error: err instanceof Error ? err.message : String(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}`);
   }
+  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 {
+        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);
@@ -743,13 +1407,31 @@ 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 = decodeBase64Json2(
+    const payment = decodeBase64Json3(
       paymentHeader
     );
     const payload = payment.payload;
@@ -759,9 +1441,28 @@ function getPaymentHeaderValidBefore(paymentHeader) {
   }
   return 0;
 }
-function decodeBase64Json2(value) {
+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 = {
@@ -822,13 +1523,67 @@ 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 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 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.";
+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: {
+    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 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 [
     {
@@ -845,6 +1600,16 @@ function claudeTools() {
       name: "authorize_x402_payment",
       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,
+      input_schema: authorizeMachinePaymentSchema
     }
   ];
 }
@@ -873,6 +1638,22 @@ function openaiTools() {
         description: AUTHORIZE_X402_DESCRIPTION,
         parameters: authorizeX402Schema
       }
+    },
+    {
+      type: "function",
+      function: {
+        name: "resume_x402_payment",
+        description: RESUME_X402_DESCRIPTION,
+        parameters: resumeX402Schema
+      }
+    },
+    {
+      type: "function",
+      function: {
+        name: "authorize_machine_payment",
+        description: AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION,
+        parameters: authorizeMachinePaymentSchema
+      }
     }
   ];
 }
@@ -886,11 +1667,16 @@ 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;