@haven_ai/sdk 0.1.1 → 0.1.2

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";
@@ -270,12 +361,65 @@ function 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}).`;
+}
 var HavenClient = class {
   apiKey;
   delegateKey;
@@ -286,6 +430,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 +478,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 +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).
    */
@@ -472,6 +623,7 @@ var HavenClient = class {
       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,11 +633,7 @@ 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);
     }
     const receipt = {
       success: true,
@@ -522,11 +670,22 @@ var HavenClient = class {
     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);
     if (!receipt.accepted) {
@@ -542,6 +701,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,6 +725,106 @@ var HavenClient = class {
         }
       );
     }
+    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) {
@@ -569,7 +839,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 +852,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,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") {
@@ -664,27 +1041,88 @@ var HavenClient = class {
           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);
@@ -743,13 +1181,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 +1215,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 = {
@@ -826,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 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 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 [
     {
@@ -845,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
     }
   ];
 }
@@ -873,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
+      }
     }
   ];
 }
@@ -886,11 +1385,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;