@haven_ai/mcp 0.0.0-dev.202609061037.7cf43bb → 0.0.0-dev.202609061923.f3d53db

package/README.md

@@ -110,6 +110,22 @@ Environment variable form:
 - `haven_submit_catalog_entry`
 - `haven_list_receipts`
 
+### `idempotencyKey` is deprecated — send `idempotency_key`
+
+The tools that take an idempotency key (`haven_send`, `haven_pay_mcp_tool`,
+`haven_quote_x402`, `haven_pay_x402_quote`, `haven_pay_x402`) now accept
+**`idempotency_key`**, the spelling the hosted Haven MCP surface and every other
+Haven wire contract use. `idempotencyKey` still works and returns a deprecation
+warning; it will be removed in a future release.
+
+Send **one** of them. Sending both with different values is refused
+(`AMBIGUOUS_IDEMPOTENCY_KEY`) with nothing contacted or spent — the key decides
+whether a retry is the same payment or a second one, so Haven will not guess
+which scope you meant. Sending both with the same value is fine.
+
+The warning arrives in an optional `warnings` array on the success result. It is
+additive: a caller that ignores it sees the response it always saw.
+
 ## First-launch consent
 
 The first time the MCP server runs against a credential file it refuses to

package/dist/cli.cjs

@@ -222,12 +222,16 @@ var toolSchemas = {
     asset: v3.z.enum(["ETH", "USDC"]),
     recipient: v3.z.string().min(1),
     amount: v3.z.string().min(1),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_pay_mcp_tool: {
     merchant_url: v3.z.string().url(),
     tool_name: v3.z.string().min(1),
     arguments: v3.z.record(v3.z.string(), v3.z.unknown()).optional(),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_quote_x402: {
@@ -235,10 +239,14 @@ var toolSchemas = {
     method: v3.z.string().optional(),
     headers: headersSchema,
     body: v3.z.string().optional(),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_pay_x402_quote: {
     quote: v3.z.unknown(),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_pay_x402: {
@@ -246,6 +254,8 @@ var toolSchemas = {
     method: v3.z.string().optional(),
     headers: headersSchema,
     body: v3.z.string().optional(),
+    idempotency_key: v3.z.string().optional(),
+    /** Legacy spelling, accepted during the #2366 window. Warns; do not use. */
     idempotencyKey: v3.z.string().optional()
   },
   haven_resume_x402_payment: {
@@ -298,8 +308,10 @@ var toolDescriptions = {
 function createToolHandlers(haven) {
   return {
     haven_send: async (input) => {
+      const pf = preflight("haven_send", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       return runTool(async () => {
-        const args = objectInput("haven_send", input);
         try {
           const result = await haven.pay({
             token: args.asset,
@@ -307,7 +319,7 @@ function createToolHandlers(haven) {
             to: args.recipient,
             // #1207: was accepted by the schema but silently dropped — now
             // carried to the backend's replay contract.
-            idempotencyKey: typeof args.idempotencyKey === "string" ? args.idempotencyKey : void 0
+            idempotencyKey: args.idempotencyKey
           });
           return {
             payment_id: result.paymentId,
@@ -331,11 +343,13 @@ function createToolHandlers(haven) {
           }
           throw err;
         }
-      });
+      }, warnings);
     },
     haven_pay_mcp_tool: async (input) => {
+      const pf = preflight("haven_pay_mcp_tool", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       return runTool(async () => {
-        const args = objectInput("haven_pay_mcp_tool", input);
         const envelope = buildMcpToolsCallEnvelope(args.tool_name, args.arguments);
         const init = {
           method: "POST",
@@ -366,18 +380,23 @@ function createToolHandlers(haven) {
           merchant_url: merchantUrl,
           ...merchantUrl !== args.merchant_url ? { merchant_url_discovered_from: args.merchant_url } : {}
         };
-      });
+      }, warnings);
     },
     haven_quote_x402: async (input) => {
-      const args = objectInput("haven_quote_x402", input);
+      const pf = preflight("haven_quote_x402", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       try {
-        return { success: true, data: await haven.quoteX402(args.url, requestInit(args), { idempotencyKey: args.idempotencyKey }) };
+        const data = await haven.quoteX402(args.url, requestInit(args), { idempotencyKey: args.idempotencyKey });
+        return warnings.length > 0 ? { success: true, data, warnings } : { success: true, data };
       } catch (err) {
         return normalizeError(err);
       }
     },
     haven_pay_x402_quote: async (input) => {
-      const args = objectInput("haven_pay_x402_quote", input);
+      const pf = preflight("haven_pay_x402_quote", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       const quote = args.quote;
       if (!quote || typeof quote !== "object") {
         return wrongTool(
@@ -396,14 +415,16 @@ function createToolHandlers(haven) {
       return runTool(async () => {
         const response = await haven.payX402Quote(args.quote, { idempotencyKey: args.idempotencyKey });
         return responsePayload(response);
-      });
+      }, warnings);
     },
     haven_pay_x402: async (input) => {
-      const args = objectInput("haven_pay_x402", input);
+      const pf = preflight("haven_pay_x402", input);
+      if ("success" in pf) return pf;
+      const { args, warnings } = pf;
       return runTool(async () => {
         const response = await haven.fetch(args.url, requestInit(args), { idempotencyKey: args.idempotencyKey });
         return responsePayload(response);
-      });
+      }, warnings);
     },
     haven_resume_x402_payment: async (input) => {
       const args = objectInput("haven_resume_x402_payment", input);
@@ -501,6 +522,39 @@ function isPendingApproval(status) {
 function wrongTool(code, message, suggested_tool) {
   return { success: false, code, message, suggested_tool };
 }
+function preflight(name, input) {
+  let args;
+  try {
+    args = objectInput(name, input);
+  } catch (err) {
+    return normalizeError(err);
+  }
+  const idem = resolveIdempotencyKey(args);
+  if ("success" in idem) return idem;
+  if (idem.key !== void 0) args = { ...args, idempotencyKey: idem.key };
+  return { args, warnings: idem.warnings };
+}
+function resolveIdempotencyKey(args) {
+  const modern = typeof args.idempotency_key === "string" ? args.idempotency_key : void 0;
+  const legacy = typeof args.idempotencyKey === "string" ? args.idempotencyKey : void 0;
+  if (modern !== void 0 && legacy !== void 0 && modern !== legacy) {
+    return {
+      success: false,
+      code: "AMBIGUOUS_IDEMPOTENCY_KEY",
+      message: "Both idempotency_key and idempotencyKey were sent with different values. Nothing was contacted or spent. Send exactly one \u2014 idempotency_key is the current spelling; idempotencyKey is deprecated and will be removed."
+    };
+  }
+  if (modern !== void 0) return { key: modern, warnings: [] };
+  if (legacy !== void 0) {
+    return {
+      key: legacy,
+      warnings: [
+        "idempotencyKey is deprecated and will be removed in a future release of @haven_ai/mcp. Send idempotency_key instead \u2014 it is the spelling the hosted Haven MCP surface and every other Haven wire contract use."
+      ]
+    };
+  }
+  return { warnings: [] };
+}
 function buildMcpToolsCallEnvelope(toolName, args) {
   return {
     jsonrpc: "2.0",
@@ -523,9 +577,10 @@ function requestInit(input) {
     body: input.body
   };
 }
-async function runTool(fn) {
+async function runTool(fn, warnings = []) {
   try {
-    return { success: true, data: await fn() };
+    const data = await fn();
+    return warnings.length > 0 ? { success: true, data, warnings } : { success: true, data };
   } catch (err) {
     return normalizeError(err);
   }
@@ -796,7 +851,7 @@ async function resolveHavenClient(options = {}) {
   return { client, credentials };
 }
 var MCP_NAME = "@haven_ai/mcp";
-var MCP_VERSION = "0.0.0-dev.202609061037.7cf43bb";
+var MCP_VERSION = "0.0.0-dev.202609061923.f3d53db";
 var MCP_INSTRUCTIONS = [
   "Haven local MCP server: signs in-process with the delegate key it holds on",
   "this machine \u2014 the key never leaves this process. Call haven_get_agent",