@keeperhub/wallet 0.1.7 → 0.1.9

package/dist/index.d.ts

@@ -33,6 +33,9 @@ declare class KeeperHubError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+/** Protocol preference for a single pay() or fetch() call. "auto" preserves
+ *  the x402-first default when both challenges are offered. */
+type PaymentHint = "x402" | "mpp" | "auto";
 declare class WalletConfigMissingError extends Error {
     constructor();
 }
@@ -259,6 +262,25 @@ type MppChallenge = {
 };
 declare function parseMppChallenge(response: Response): MppChallenge | null;
 
+type X402Challenge = {
+    x402Version: 2;
+    accepts: Array<{
+        scheme: "exact";
+        network: string;
+        asset: string;
+        amount: string;
+        payTo: string;
+        maxTimeoutSeconds: number;
+        extra: Record<string, unknown>;
+    }>;
+    resource: {
+        url: string;
+        description: string;
+        mimeType: string;
+    };
+};
+declare function parseX402Challenge(response: Response): Promise<X402Challenge | null>;
+
 type PaySignerOptions = {
     /** Override wallet loader (primarily for tests). */
     walletLoader?: () => Promise<WalletConfig>;
@@ -296,6 +318,18 @@ type PayRetryOptions = {
     headers?: RequestInit["headers"];
     /** HTTP method for the retry. Defaults to "POST". */
     method?: string;
+    /**
+     * Per-call protocol preference. "x402" forces Base USDC; "mpp" forces Tempo
+     * USDC.e; "auto" (default, also the behaviour when omitted) uses x402 when
+     * offered, MPP otherwise. Throws KeeperHubError("X402_NOT_OFFERED") or
+     * KeeperHubError("MPP_NOT_OFFERED") when the requested protocol is absent
+     * from the challenge (KEEP-361).
+     */
+    paymentHint?: PaymentHint;
+};
+/** RequestInit extended with paymentHint for per-call protocol selection. */
+type FetchInit = RequestInit & {
+    paymentHint?: PaymentHint;
 };
 type PaymentSigner = {
     /**
@@ -315,12 +349,36 @@ type PaymentSigner = {
      * `pay()` with `init.body` + `init.headers` so the retry carries the
      * original payload. Returns whatever the retry (or first response, if not
      * 402) returns. No-op for non-402 responses.
+     *
+     * Pass `init.paymentHint` to force a specific payment protocol for this
+     * call. Omitting it is equivalent to `paymentHint: "auto"` (x402-first).
      */
-    fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+    fetch: (input: string | URL, init?: FetchInit) => Promise<Response>;
 };
+/**
+ * Pure function that decides which payment protocol to use given challenge
+ * availability and caller's hint. Exported for unit testing.
+ *
+ * Returns "x402" or "mpp" to direct the caller to the appropriate path,
+ * or null when hint is "auto" and no challenge is present (pay() then
+ * returns the original 402 response unchanged). Throws KeeperHubError with
+ * a specific code when the requested protocol is unavailable (KEEP-361).
+ */
+declare function selectProtocol(x402: X402Challenge | null, mpp: MppChallenge | null, hint: PaymentHint | undefined): "x402" | "mpp" | null;
 declare function createPaymentSigner(opts?: PaySignerOptions): PaymentSigner;
 declare const paymentSigner: PaymentSigner;
 
+/**
+ * Pick the hook command to write into settings.json.
+ *
+ * Returns the bare bin name if it resolves on PATH (global install or a
+ * dev-time `npm link`), otherwise a version-pinned `npx` invocation that
+ * pulls the installer's own version of `@keeperhub/wallet` on demand.
+ * Override-able via the env var `KEEPERHUB_WALLET_HOOK_COMMAND` for
+ * test fixtures and unusual deployments (env input is trusted — it is
+ * written verbatim into settings.json and executed by the user's shell).
+ */
+declare function resolveHookCommand(): string;
 type InstallResult = {
     skillWrites: Array<{
         agent: string;
@@ -337,31 +395,26 @@ type InstallOptions = {
     homeOverride?: string;
     skillSourcePath?: string;
     onNotice?: (msg: string) => void;
+    /**
+     * Hook command to write into settings.json (and reference in stderr
+     * notices for non-Claude agents). Defaults to {@link resolveHookCommand}.
+     * Override for tests, monorepo setups, or unusual deployments.
+     */
+    hookCommand?: string;
+};
+type RegisterClaudeCodeHookOptions = {
+    /**
+     * Hook command to write. Defaults to {@link resolveHookCommand}. Tests
+     * pass a deterministic value to keep assertions stable across host
+     * environments (CI may or may not have the bin on PATH).
+     */
+    hookCommand?: string;
 };
-declare function registerClaudeCodeHook(settingsPath: string): Promise<void>;
+declare function registerClaudeCodeHook(settingsPath: string, options?: RegisterClaudeCodeHookOptions): Promise<void>;
 declare function installSkill(options?: InstallOptions): Promise<InstallResult>;
 
 declare function readWalletConfig(): Promise<WalletConfig>;
 declare function writeWalletConfig(config: WalletConfig): Promise<void>;
 declare function getWalletConfigPath(): string;
 
-type X402Challenge = {
-    x402Version: 2;
-    accepts: Array<{
-        scheme: "exact";
-        network: string;
-        asset: string;
-        amount: string;
-        payTo: string;
-        maxTimeoutSeconds: number;
-        extra: Record<string, unknown>;
-    }>;
-    resource: {
-        url: string;
-        description: string;
-        mimeType: string;
-    };
-};
-declare function parseX402Challenge(response: Response): Promise<X402Challenge | null>;
-
-export { type AgentTarget, type AskTierResponse, BASE_USDC, type BalanceSnapshot, type CheckBalanceOptions, type ClientOptions, type CreateHookOptions, DEFAULT_SAFETY_CONFIG, type FundInstructions, type HmacHeaders, type HookDecision, type InstallOptions, type InstallResult, KeeperHubClient, KeeperHubError, type MppChallenge, type PaymentSigner, type SafetyConfig, TEMPO_USDC_E, type WalletConfig, WalletConfigMissingError, type X402Challenge, buildHmacHeaders, checkBalance, computeSignature, createPaymentSigner, createPreToolUseHook, detectAgents, fund, getSafetyConfigPath, getWalletConfigPath, installSkill, loadSafetyConfig, parseMppChallenge, parseX402Challenge, paymentSigner, readWalletConfig, registerClaudeCodeHook, tempo, validateAndMerge, writeWalletConfig };
+export { type AgentTarget, type AskTierResponse, BASE_USDC, type BalanceSnapshot, type CheckBalanceOptions, type ClientOptions, type CreateHookOptions, DEFAULT_SAFETY_CONFIG, type FetchInit, type FundInstructions, type HmacHeaders, type HookDecision, type InstallOptions, type InstallResult, KeeperHubClient, KeeperHubError, type MppChallenge, type PayRetryOptions, type PaymentHint, type PaymentSigner, type RegisterClaudeCodeHookOptions, type SafetyConfig, TEMPO_USDC_E, type WalletConfig, WalletConfigMissingError, type X402Challenge, buildHmacHeaders, checkBalance, computeSignature, createPaymentSigner, createPreToolUseHook, detectAgents, fund, getSafetyConfigPath, getWalletConfigPath, installSkill, loadSafetyConfig, parseMppChallenge, parseX402Challenge, paymentSigner, readWalletConfig, registerClaudeCodeHook, resolveHookCommand, selectProtocol, tempo, validateAndMerge, writeWalletConfig };

package/dist/index.js

@@ -147,15 +147,69 @@ function fund(walletAddress) {
 }
 
 // src/skill-install.ts
+import { execFileSync } from "child_process";
 import { chmod, copyFile, mkdir, readFile, writeFile } from "fs/promises";
+import { readFileSync } from "fs";
 import { dirname as dirname2, join as join2 } from "path";
 import { fileURLToPath } from "url";
-var HOOK_COMMAND = "keeperhub-wallet-hook";
-var KEEPERHUB_HOOK_MARKER = "keeperhub-wallet-hook";
-function buildKeeperhubEntry() {
+var HOOK_BIN = "keeperhub-wallet-hook";
+var HOOK_COMMAND_BARE = HOOK_BIN;
+var PACKAGE_NAME = "@keeperhub/wallet";
+function readPackageVersion() {
+  try {
+    const here = dirname2(fileURLToPath(import.meta.url));
+    const pkgPath = join2(here, "..", "package.json");
+    const raw = readFileSync(pkgPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.version === "string" && parsed.version.length > 0) {
+      return parsed.version;
+    }
+  } catch {
+  }
+  return "latest";
+}
+function buildNpxCommand(version) {
+  return `npx -y -p ${PACKAGE_NAME}@${version} ${HOOK_BIN}`;
+}
+var KEEPERHUB_HOOK_MARKER = HOOK_BIN;
+function filterKeeperhubHooksFromEntry(entry) {
+  if (typeof entry !== "object" || entry === null) {
+    return entry;
+  }
+  const candidate = entry;
+  if (!Array.isArray(candidate.hooks)) {
+    return entry;
+  }
+  const survivors = candidate.hooks.filter((h) => {
+    const cmd = h?.command;
+    return !(typeof cmd === "string" && cmd.includes(KEEPERHUB_HOOK_MARKER));
+  });
+  if (survivors.length === candidate.hooks.length) {
+    return entry;
+  }
+  if (survivors.length === 0) {
+    return null;
+  }
+  return { ...candidate, hooks: survivors };
+}
+function resolveHookCommand() {
+  const envOverride = process.env.KEEPERHUB_WALLET_HOOK_COMMAND;
+  if (envOverride && envOverride.length > 0) {
+    return envOverride;
+  }
+  try {
+    execFileSync("/bin/sh", ["-c", `command -v ${HOOK_BIN}`], {
+      stdio: "ignore"
+    });
+    return HOOK_COMMAND_BARE;
+  } catch {
+    return buildNpxCommand(readPackageVersion());
+  }
+}
+function buildKeeperhubEntry(command) {
   return {
     matcher: "*",
-    hooks: [{ type: "command", command: HOOK_COMMAND }]
+    hooks: [{ type: "command", command }]
   };
 }
 function resolveDefaultSkillSource() {
@@ -166,7 +220,8 @@ function defaultNotice(msg) {
   process.stderr.write(`${msg}
 `);
 }
-async function registerClaudeCodeHook(settingsPath) {
+async function registerClaudeCodeHook(settingsPath, options = {}) {
+  const command = options.hookCommand ?? resolveHookCommand();
   let raw = null;
   try {
     raw = await readFile(settingsPath, "utf-8");
@@ -189,12 +244,12 @@ async function registerClaudeCodeHook(settingsPath) {
   const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
   const filtered = [];
   for (const entry of existingPreToolUse) {
-    const serialised = JSON.stringify(entry);
-    if (!serialised.includes(KEEPERHUB_HOOK_MARKER)) {
-      filtered.push(entry);
+    const survivor = filterKeeperhubHooksFromEntry(entry);
+    if (survivor !== null) {
+      filtered.push(survivor);
     }
   }
-  filtered.push(buildKeeperhubEntry());
+  filtered.push(buildKeeperhubEntry(command));
   hooks.PreToolUse = filtered;
   config.hooks = hooks;
   await mkdir(dirname2(settingsPath), { recursive: true, mode: 448 });
@@ -210,26 +265,27 @@ async function writeSkillToAgent(agent, skillSource) {
   await chmod(target, 420);
   return { agent: agent.agent, path: target, status: "written" };
 }
-function buildNoticeMessage(agent) {
-  return `${agent.agent} does not support auto-registered PreToolUse hooks; run \`${HOOK_COMMAND}\` on every tool use via ${agent.agent}'s settings file at ${agent.settingsFile}`;
+function buildNoticeMessage(agent, command) {
+  return `${agent.agent} does not support auto-registered PreToolUse hooks; run \`${command}\` on every tool use via ${agent.agent}'s settings file at ${agent.settingsFile}`;
 }
 async function installSkill(options = {}) {
   const agents = detectAgents(options.homeOverride);
   const skillSource = options.skillSourcePath ?? resolveDefaultSkillSource();
   const onNotice = options.onNotice ?? defaultNotice;
+  const hookCommand = options.hookCommand ?? resolveHookCommand();
   const skillWrites = [];
   const hookRegistrations = [];
   for (const agent of agents) {
     const write = await writeSkillToAgent(agent, skillSource);
     skillWrites.push(write);
     if (agent.hookSupport === "claude-code") {
-      await registerClaudeCodeHook(agent.settingsFile);
+      await registerClaudeCodeHook(agent.settingsFile, { hookCommand });
       hookRegistrations.push({
         agent: agent.agent,
         status: "registered"
       });
     } else {
-      const message = buildNoticeMessage(agent);
+      const message = buildNoticeMessage(agent, hookCommand);
       hookRegistrations.push({
         agent: agent.agent,
         status: "notice",
@@ -637,6 +693,26 @@ var DEFAULT_TOOL_RE = /keeperhub|wallet|sign/i;
 function defaultToolMatcher(name) {
   return DEFAULT_TOOL_RE.test(name);
 }
+function hasPaymentShape(input) {
+  const ti = input.tool_input ?? {};
+  const challenge = ti.paymentChallenge;
+  if (challenge !== void 0 && challenge !== null) {
+    return true;
+  }
+  if (ti.amount !== void 0 && ti.amount !== null) {
+    return true;
+  }
+  if (ti.unit !== void 0 && ti.unit !== null) {
+    return true;
+  }
+  for (const field of ["to", "contract", "assetAddress"]) {
+    const v = ti[field];
+    if (typeof v === "string" && ADDRESS_RE.test(v)) {
+      return true;
+    }
+  }
+  return false;
+}
 function extractAmountMicroUsdc(input) {
   const ti = input.tool_input ?? {};
   const challenge = ti.paymentChallenge ?? {};
@@ -686,6 +762,9 @@ async function createPreToolUseHook(options = {}) {
     if (!(typeof hookInput.tool_name === "string" && toolMatcher(hookInput.tool_name))) {
       return { decision: "allow" };
     }
+    if (!hasPaymentShape(hookInput)) {
+      return { decision: "allow" };
+    }
     const contractAddr = extractContractAddress(hookInput);
     const amountMicro = extractAmountMicroUsdc(hookInput);
     if (contractAddr && !safety.allowlisted_contracts.includes(contractAddr)) {
@@ -818,6 +897,30 @@ var NONCE_BYTES = 32;
 async function sleep(ms) {
   await new Promise((resolve) => setTimeout(resolve, ms));
 }
+function selectProtocol(x402, mpp, hint) {
+  const h = hint ?? "auto";
+  if (h === "x402") {
+    if (!x402) {
+      throw new KeeperHubError(
+        "X402_NOT_OFFERED",
+        "x402 is not offered by this endpoint"
+      );
+    }
+    return "x402";
+  }
+  if (h === "mpp") {
+    if (!mpp) {
+      throw new KeeperHubError(
+        "MPP_NOT_OFFERED",
+        "mpp is not offered by this endpoint"
+      );
+    }
+    return "mpp";
+  }
+  if (x402) return "x402";
+  if (mpp) return "mpp";
+  return null;
+}
 function createPaymentSigner(opts = {}) {
   const fetchImpl = opts.fetchImpl ?? globalThis.fetch;
   const walletLoader = opts.walletLoader ?? readWalletConfig;
@@ -960,12 +1063,13 @@ function createPaymentSigner(opts = {}) {
       return response;
     }
     const wallet = await walletLoader();
-    if (mpp) {
-      return payViaMpp(response, mpp, wallet, options);
-    }
-    if (x402) {
+    const protocol = selectProtocol(x402, mpp, options?.paymentHint);
+    if (protocol === "x402") {
       return payViaX402(response, x402, wallet, options);
     }
+    if (protocol === "mpp") {
+      return payViaMpp(response, mpp, wallet, options);
+    }
     return response;
   }
   return {
@@ -978,7 +1082,8 @@ function createPaymentSigner(opts = {}) {
       return pay(first, {
         body: init?.body ?? void 0,
         headers: init?.headers,
-        method: init?.method
+        method: init?.method,
+        paymentHint: init?.paymentHint
       });
     }
   };
@@ -1008,8 +1113,10 @@ export {
   paymentSigner,
   readWalletConfig,
   registerClaudeCodeHook,
+  resolveHookCommand,
   runCli,
   runHookCli,
+  selectProtocol,
   tempo,
   validateAndMerge,
   writeWalletConfig