@haven_ai/sdk 0.1.4 → 0.1.5

package/dist/index.js

@@ -52,8 +52,16 @@ var AgentPaymentRail = {
   Direct: "direct",
   /** x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg. */
   X402: "x402",
-  /** Machine Payment Protocol flow. */
-  Mpp: "mpp"
+  /** Machine Payment Protocol family — categorical value used as a resume-state discriminator. */
+  Mpp: "mpp",
+  /** Haven internal MPP demo rail. Not for production traffic. */
+  MppDemo: "mpp_demo",
+  /** Crypto-settled MPP rail. */
+  MppCrypto: "mpp_crypto",
+  /** Stripe-deposit-backed MPP rail. */
+  StripeDeposit: "stripe_deposit",
+  /** Stripe Payment Token MPP rail. */
+  Spt: "spt"
 };
 var AGENT_PAYMENT_PHASE_VALUES = Object.values(AgentPaymentPhase);
 var AGENT_PAYMENT_NEXT_ACTION_VALUES = Object.values(AgentPaymentNextAction);
@@ -83,7 +91,11 @@ var AgentPaymentNextActionDescriptions = {
 var AgentPaymentRailDescriptions = {
   [AgentPaymentRail.Direct]: "Standard Haven payment from the user-controlled Safe through an approved delegate allowance.",
   [AgentPaymentRail.X402]: "x402 HTTP 402 payment flow with a Haven funding leg and merchant retry leg.",
-  [AgentPaymentRail.Mpp]: "Machine Payment Protocol flow."
+  [AgentPaymentRail.Mpp]: "Categorical MPP rail value used as a resume-state discriminator. Response bodies carry a granular mpp_* value instead.",
+  [AgentPaymentRail.MppDemo]: "Haven internal MPP demo rail. Not for production traffic.",
+  [AgentPaymentRail.MppCrypto]: "Crypto-settled MPP rail.",
+  [AgentPaymentRail.StripeDeposit]: "Stripe-deposit-backed MPP rail.",
+  [AgentPaymentRail.Spt]: "Stripe Payment Token MPP rail."
 };
 var AgentPaymentPhaseSchema = {
   type: "string",
@@ -323,6 +335,23 @@ function selectStandardPaymentOption(accepts) {
   }
   return null;
 }
+function x402AuthorizationAmount(option) {
+  return option.maxAmountRequired ?? option.amount;
+}
+function buildX402ExpectedMessage(context) {
+  return `Haven x402 expected context v1
+${stableStringify({
+    version: 1,
+    kind: "haven.x402.expected",
+    paymentId: context.paymentId,
+    payloadHash: context.payloadHash.toLowerCase(),
+    resourceUrl: context.resourceUrl,
+    merchantTo: context.merchantTo.toLowerCase(),
+    amount: context.amount,
+    asset: context.asset.toLowerCase(),
+    network: context.network
+  })}`;
+}
 function toStandardPaymentRequirements(paymentRequired, option) {
   const network = STANDARD_X402_NETWORKS[option.network];
   if (!network) {
@@ -334,7 +363,7 @@ function toStandardPaymentRequirements(paymentRequired, option) {
   return {
     scheme: "exact",
     network,
-    maxAmountRequired: option.maxAmountRequired ?? option.amount,
+    maxAmountRequired: x402AuthorizationAmount(option),
     resource: option.resource ?? paymentRequired.resource.url,
     description: option.description ?? paymentRequired.resource.description ?? "Haven x402 payment",
     mimeType: option.mimeType ?? paymentRequired.resource.mimeType ?? "application/octet-stream",
@@ -351,7 +380,7 @@ function buildX402IdempotencyKey(paymentRequired, option, now = Date.now()) {
     paymentRequired.resource.description ?? "",
     option.payTo.toLowerCase(),
     option.asset.toLowerCase(),
-    option.amount,
+    x402AuthorizationAmount(option),
     option.network,
     bucket
   ].join("|");
@@ -380,6 +409,15 @@ function resolveTokenFromAddress(address, network) {
   }
   return ALL_TOKENS[lower] ?? null;
 }
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") {
+    const primitive = JSON.stringify(value);
+    return primitive === void 0 ? "undefined" : primitive;
+  }
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  const object = value;
+  return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(object[key])}`).join(",")}}`;
+}
 function decodeBase64Json2(value, label) {
   try {
     return JSON.parse(atob(value));
@@ -657,6 +695,70 @@ var HavenClient = class {
       signData: raw.sign_data
     };
   }
+  /**
+   * Keyless x402 construct.
+   *
+   * The non-custodial half of an x402 payment: posts the funding request to
+   * `/x402` and returns the unsigned funding hash plus the data the caller
+   * needs to build and sign the EIP-3009 merchant header itself. Crucially it
+   * does **not** sign — neither the funding hash nor the merchant header — so
+   * it works without a `delegateKey`. Both delegate signatures happen on the
+   * machine that holds the key (the edge); the hosted MCP server relays only.
+   *
+   * Use this from the hosted, keyless server. The all-in-one `authorizeX402`
+   * remains for local clients that hold the key.
+   *
+   * Throws (via the shared payment-state path) when the amount exceeds the
+   * on-chain allowance — there is nothing to sign until the user approves.
+   */
+  async createX402Intent(paymentRequired, options = {}) {
+    const option = selectStandardPaymentOption(paymentRequired.accepts);
+    if (!option) {
+      throw new HavenApiError(
+        "No compatible payment option found in x402 requirements. Haven supports standard x402 exact payments on Base USDC.",
+        400
+      );
+    }
+    const agent = await this.getAgent();
+    const fundingTo = agent.delegateAddress;
+    if (!fundingTo) {
+      throw new HavenApiError("Authenticated agent has no delegate address registered.", 502);
+    }
+    const idempotencyKey = options.idempotencyKey ?? buildX402IdempotencyKey(paymentRequired, option);
+    const raw = await this.post("/x402", {
+      url: paymentRequired.resource.url,
+      payTo: fundingTo,
+      merchantPayTo: option.payTo,
+      amount: x402AuthorizationAmount(option),
+      asset: option.asset,
+      network: option.network,
+      description: paymentRequired.resource.description,
+      idempotencyKey
+    });
+    if (raw.status !== "pending_signature") {
+      this.throwPaymentStateError("x402 payment", raw);
+    }
+    if (!raw.sign_data?.hash) {
+      throw new HavenApiError("No sign_hash returned from x402/authorize", 500, raw);
+    }
+    if (!raw.x402_expected_auth) {
+      throw new HavenApiError("No x402 expected-context binding returned from x402/authorize", 500, raw);
+    }
+    return {
+      paymentId: raw.payment_id,
+      status: "pending_signature",
+      expiresAt: raw.expires_at,
+      signData: raw.sign_data,
+      accepted: option,
+      resourceUrl: paymentRequired.resource.url,
+      merchantTo: raw.merchant_to ?? option.payTo,
+      amountAtomic: x402AuthorizationAmount(option),
+      asset: option.asset,
+      network: option.network,
+      expectedAuth: raw.x402_expected_auth,
+      fundingTo
+    };
+  }
   /**
    * Step 2: Sign a hash with the delegate key.
    *
@@ -880,7 +982,7 @@ var HavenClient = class {
       url: paymentRequired.resource.url,
       payTo: this.delegateAddress,
       merchantPayTo: option.payTo,
-      amount: option.amount,
+      amount: x402AuthorizationAmount(option),
       asset: option.asset,
       network: option.network,
       description: paymentRequired.resource.description,
@@ -1317,7 +1419,7 @@ var HavenClient = class {
       );
     }
     const approvedAmount = status.amount ? normalizeDecimal(status.amount) : "";
-    const requestedAmount = normalizeDecimal(decimalFromUsdcAtomic(option.amount));
+    const requestedAmount = normalizeDecimal(decimalFromUsdcAtomic(x402AuthorizationAmount(option)));
     if (approvedAmount && approvedAmount !== requestedAmount) {
       throw new HavenApiError(
         "x402 resume request does not match the approved amount.",
@@ -1393,7 +1495,7 @@ var HavenClient = class {
     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 amount = execResult?.amount ?? raw.amount ?? decimalFromUsdcAtomic(x402AuthorizationAmount(option));
     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;
@@ -1426,7 +1528,7 @@ var HavenClient = class {
       paymentId: status.paymentId,
       txHash: status.txHash,
       token: status.token || "USDC",
-      amount: status.amount || decimalFromUsdcAtomic(option.amount),
+      amount: status.amount || decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
       to: this.delegateAddress ?? "",
       resourceUrl: paymentRequired.resource.url,
       explorerUrl: explorerUrlOrEmpty(status.chainId, status.txHash),
@@ -1462,7 +1564,7 @@ var HavenClient = class {
         payTo: input.merchantTo ?? input.accepted.payTo
       },
       x402: {
-        amount: input.accepted.amount,
+        amount: x402AuthorizationAmount(input.accepted),
         token: input.token,
         network: input.accepted.network,
         asset: input.accepted.asset,
@@ -1712,8 +1814,8 @@ var HavenClient = class {
       resourceUrl: paymentRequired.resource.url,
       description: paymentRequired.resource.description ?? option.description ?? null,
       mimeType: paymentRequired.resource.mimeType ?? option.mimeType ?? null,
-      amountAtomic: option.amount,
-      amount: decimalFromUsdcAtomic(option.amount),
+      amountAtomic: x402AuthorizationAmount(option),
+      amount: decimalFromUsdcAtomic(x402AuthorizationAmount(option)),
       token: token?.symbol ?? "USDC",
       asset: option.asset,
       network: option.network,
@@ -1734,8 +1836,8 @@ var HavenClient = class {
       request: input.request,
       resourceUrl: input.paymentRequired.resource.url,
       description: input.paymentRequired.resource.description ?? input.accepted.description ?? null,
-      amountAtomic: input.accepted.amount,
-      amount: decimalFromUsdcAtomic(input.accepted.amount),
+      amountAtomic: x402AuthorizationAmount(input.accepted),
+      amount: decimalFromUsdcAtomic(x402AuthorizationAmount(input.accepted)),
       token: token?.symbol ?? "USDC",
       asset: input.accepted.asset,
       network: input.accepted.network,
@@ -1930,6 +2032,9 @@ var HavenClient = class {
         message: result.message
       };
     }
+    if (toolName === "get_allowances") {
+      return { ...await this.getAllowances() };
+    }
     throw new Error(`Unknown tool: ${toolName}`);
   }
   toolX402PaymentRequired(input) {
@@ -2187,6 +2292,72 @@ async function responseSnippet(response) {
   }
 }
 
+// src/tool-descriptions.ts
+function composeDescription(d) {
+  return [d.summary, d.selectionGuidance, d.behavior, d.nextActionGuidance].filter(Boolean).join(" ");
+}
+var toolDescriptions = {
+  quoteX402: {
+    summary: "Inspect an HTTP 402 x402 paid resource without creating a Haven payment, signature, approval, or on-chain transaction.",
+    behavior: "Probes the merchant directly and parses the 402 response. Pure read-only client behavior \u2014 Haven is not contacted.",
+    nextActionGuidance: ""
+  },
+  payX402: {
+    summary: "Pay an inspected x402 quote. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
+    selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
+    behavior: "Signs the EIP-3009 payment from the delegate wallet, asks Haven for a Safe AllowanceModule top-up if needed, and returns the merchant response or a pending-approval state.",
+    nextActionGuidance: "If approval is needed, preserve the returned resume_state and wait for nextAction=retry_original_x402_request before resuming."
+  },
+  resumeX402: {
+    summary: "Resume an x402 payment after the Haven wallet owner approved the funding step.",
+    behavior: "Accepts either resume_state or payment_id, validates the original x402 details against the approved Haven funding, and retries the merchant request with the X-PAYMENT header. No new Haven approval is created.",
+    nextActionGuidance: "Only use when get_payment_status returns nextAction=retry_original_x402_request; do not start a new merchant session."
+  },
+  quoteMpp: {
+    summary: "Inspect a Haven MPP challenge or paid MPP URL without creating a Haven payment, signature, approval, or on-chain transaction.",
+    behavior: "Parses an MPP challenge envelope and returns a typed quote with rail tag, amount, asset, and merchant context. Pure read-only \u2014 Haven is not contacted.",
+    nextActionGuidance: ""
+  },
+  payMpp: {
+    summary: "Pay an inspected MPP challenge. The delegate key signs locally; Haven only validates and relays signed, on-chain-constrained payment transactions.",
+    selectionGuidance: "Do not use this for read-only allowance, budget, spend-limit, remaining-amount, reset-period, or what-can-I-spend questions; use the allowance lookup tool instead.",
+    behavior: "Authorizes the payment through Haven within the on-chain allowance, signs the challenge proof, and returns the proof header for retrying the original paid resource.",
+    nextActionGuidance: "If approval is needed, preserve resume_state or payment_id and wait for nextAction=retry_original_x402_request before resuming."
+  },
+  resumeMpp: {
+    summary: "Resume an MPP payment after the Haven wallet owner approved the funding step.",
+    behavior: "Accepts either resume_state or payment_id and retries the original paid resource with the MPP proof header. No new Haven approval is created.",
+    nextActionGuidance: ""
+  },
+  getPaymentStatus: {
+    summary: "Fetch structured Haven payment status, including phase and nextAction taxonomy for agent recovery.",
+    behavior: "Accepts a payment intent or approval request id and returns the full state taxonomy (phase, nextAction, rail, amount, merchant, resource url, idempotency key, message).",
+    nextActionGuidance: ""
+  },
+  getResumeState: {
+    summary: "Rehydrate stored x402 or MPP resume_state by payment_id.",
+    behavior: "Returns the context that the agent originally received in a pending-approval response, reconstructed from Haven's database. This is context only; signing still happens locally when a resume tool is called.",
+    nextActionGuidance: ""
+  },
+  getAgent: {
+    summary: "Return the authenticated agent identity, Haven wallet, delegate address, chain, and status.",
+    behavior: "Read-only identity lookup. Useful for verifying which on-chain Safe and delegate the credential is bound to.",
+    nextActionGuidance: ""
+  },
+  getAllowances: {
+    summary: "Return configured and on-chain allowance state for the authenticated agent. On-chain allowance is the real spend gate.",
+    selectionGuidance: "Use this when the user asks about allowance, budget, spend limit, remaining amount, remaining allowance, remaining budget, daily limit, reset period, what can I spend, or what the agent can still spend.",
+    behavior: "Reads the Safe AllowanceModule snapshot per token (allowance, spent, remaining, reset window). Configured amounts from Haven are returned alongside the on-chain truth.",
+    nextActionGuidance: ""
+  },
+  listReceipts: {
+    summary: "List recent machine-payment receipts and evidence for bookkeeping.",
+    selectionGuidance: "Use this for transaction history, receipts, payment evidence, or bookkeeping; use the allowance tool instead for remaining allowance, budget, spend-limit, or what-can-I-spend questions.",
+    behavior: "Returns the agent's recent machine-payment receipts ordered by recency. Proof header values are not returned.",
+    nextActionGuidance: ""
+  }
+};
+
 // src/tools.ts
 var makePaymentSchema = {
   type: "object",
@@ -2220,6 +2391,11 @@ var getPaymentStatusSchema = {
   },
   required: ["payment_id"]
 };
+var getAllowancesSchema = {
+  type: "object",
+  properties: {},
+  required: []
+};
 var authorizeX402Schema = {
   type: "object",
   properties: {
@@ -2302,11 +2478,12 @@ var authorizeMachinePaymentSchema = {
   },
   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, preserve the original merchant/MCP session and x402 details, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not start a new merchant session or 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 or merchant session.";
-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.";
+var MAKE_PAYMENT_DESCRIPTION = "Request and sign a payment from the user-controlled Safe within approved on-chain limits. For read-only allowance, budget, spend-limit, remaining-amount, or reset-period questions, use get_allowances instead of making a payment. 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 = toolDescriptions.getPaymentStatus.summary + " Accepts payment intent IDs and approval request IDs. Returns the current status, phase, next_action, transaction hash if available, and payment details.";
+var GET_ALLOWANCES_DESCRIPTION = composeDescription(toolDescriptions.getAllowances);
+var AUTHORIZE_X402_DESCRIPTION = composeDescription(toolDescriptions.payX402) + " In this SDK tool set, the allowance lookup tool is get_allowances. 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, preserve the original merchant/MCP session and x402 details, call get_payment_status later, and use resume_x402_payment only when next_action is retry_original_x402_request. Do not start a new merchant session or 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 = toolDescriptions.resumeX402.summary + " 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 or merchant session.";
+var AUTHORIZE_MACHINE_PAYMENT_DESCRIPTION = composeDescription(toolDescriptions.payMpp) + " In this SDK tool set, the allowance lookup tool is get_allowances. Currently scoped to 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 [
     {
@@ -2319,6 +2496,11 @@ function claudeTools() {
       description: GET_STATUS_DESCRIPTION,
       input_schema: getPaymentStatusSchema
     },
+    {
+      name: "get_allowances",
+      description: GET_ALLOWANCES_DESCRIPTION,
+      input_schema: getAllowancesSchema
+    },
     {
       name: "authorize_x402_payment",
       description: AUTHORIZE_X402_DESCRIPTION,
@@ -2354,6 +2536,14 @@ function openaiTools() {
         parameters: getPaymentStatusSchema
       }
     },
+    {
+      type: "function",
+      function: {
+        name: "get_allowances",
+        description: GET_ALLOWANCES_DESCRIPTION,
+        parameters: getAllowancesSchema
+      }
+    },
     {
       type: "function",
       function: {
@@ -2387,6 +2577,6 @@ var havenTools = {
   openai: openaiTools
 };
 
-export { AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, addressFromKey, buildMachinePaymentIdempotencyKey, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, signHash, verifySignature };
+export { AGENT_PAYMENT_NEXT_ACTION_VALUES, AGENT_PAYMENT_PHASE_VALUES, AGENT_PAYMENT_RAIL_VALUES, AgentPaymentNextAction, AgentPaymentNextActionDescriptions, AgentPaymentNextActionSchema, AgentPaymentPhase, AgentPaymentPhaseDescriptions, AgentPaymentPhaseSchema, AgentPaymentRail, AgentPaymentRailDescriptions, AgentPaymentRailSchema, HavenApiError, HavenClient, HavenError, HavenPaymentStateError, HavenSigningError, HavenTimeoutError, addressFromKey, buildMachinePaymentIdempotencyKey, buildX402ExpectedMessage, composeDescription, encodeMachinePaymentProof, encodePaymentProof, havenTools, parseMachinePaymentChallenge, parseMachinePaymentChallengeResponse, parsePaymentRequired, parsePaymentRequiredResponse, selectPaymentOption, selectStandardPaymentOption, signHash, toStandardPaymentRequirements, toolDescriptions, verifySignature, x402AuthorizationAmount };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map