@keeperhub/wallet 0.1.4 → 0.1.6

package/dist/index.d.cts

@@ -272,8 +272,51 @@ type PaySignerOptions = {
         maxAttempts: number;
     };
 };
+/**
+ * Retry options threaded through `pay()` and `fetch()` into the post-sign
+ * retry. Lets callers forward the original request body and headers so the
+ * paid workflow receives the same payload on the retry as on the 402 attempt
+ * -- otherwise a workflow whose input schema requires a body (e.g.
+ * `{address}` on `/api/mcp/workflows/<slug>/call`) rejects the retry with
+ * 400 "Invalid JSON body".
+ */
+type PayRetryOptions = {
+    /**
+     * Body to re-send on the retry. Must be a type that can be sent twice --
+     * string, ArrayBuffer, Uint8Array, FormData, URLSearchParams, or Blob.
+     * ReadableStream bodies are NOT supported because the first fetch() already
+     * consumed the stream; pass a string/Buffer instead.
+     */
+    body?: RequestInit["body"];
+    /**
+     * Additional request headers to merge onto the retry (e.g. Content-Type).
+     * The payment auth header (PAYMENT-SIGNATURE or Authorization) is set by
+     * the signer and overrides any same-named header in this map.
+     */
+    headers?: RequestInit["headers"];
+    /** HTTP method for the retry. Defaults to "POST". */
+    method?: string;
+};
 type PaymentSigner = {
-    pay: (response: Response) => Promise<Response>;
+    /**
+     * Pays a 402 response and returns the post-payment retry Response.
+     * Non-402 responses are returned unchanged.
+     *
+     * Pass `options.body` (and usually `options.headers`) if the paid
+     * workflow's input schema requires a body -- `pay()` does not have access
+     * to the original request otherwise.
+     *
+     * For most agent code, prefer `signer.fetch(url, init)` which threads the
+     * body/headers automatically.
+     */
+    pay: (response: Response, options?: PayRetryOptions) => Promise<Response>;
+    /**
+     * `fetch(url, init)` wrapper: does the initial fetch, and on 402 calls
+     * `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.
+     */
+    fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
 };
 declare function createPaymentSigner(opts?: PaySignerOptions): PaymentSigner;
 declare const paymentSigner: PaymentSigner;

package/dist/index.d.ts

@@ -272,8 +272,51 @@ type PaySignerOptions = {
         maxAttempts: number;
     };
 };
+/**
+ * Retry options threaded through `pay()` and `fetch()` into the post-sign
+ * retry. Lets callers forward the original request body and headers so the
+ * paid workflow receives the same payload on the retry as on the 402 attempt
+ * -- otherwise a workflow whose input schema requires a body (e.g.
+ * `{address}` on `/api/mcp/workflows/<slug>/call`) rejects the retry with
+ * 400 "Invalid JSON body".
+ */
+type PayRetryOptions = {
+    /**
+     * Body to re-send on the retry. Must be a type that can be sent twice --
+     * string, ArrayBuffer, Uint8Array, FormData, URLSearchParams, or Blob.
+     * ReadableStream bodies are NOT supported because the first fetch() already
+     * consumed the stream; pass a string/Buffer instead.
+     */
+    body?: RequestInit["body"];
+    /**
+     * Additional request headers to merge onto the retry (e.g. Content-Type).
+     * The payment auth header (PAYMENT-SIGNATURE or Authorization) is set by
+     * the signer and overrides any same-named header in this map.
+     */
+    headers?: RequestInit["headers"];
+    /** HTTP method for the retry. Defaults to "POST". */
+    method?: string;
+};
 type PaymentSigner = {
-    pay: (response: Response) => Promise<Response>;
+    /**
+     * Pays a 402 response and returns the post-payment retry Response.
+     * Non-402 responses are returned unchanged.
+     *
+     * Pass `options.body` (and usually `options.headers`) if the paid
+     * workflow's input schema requires a body -- `pay()` does not have access
+     * to the original request otherwise.
+     *
+     * For most agent code, prefer `signer.fetch(url, init)` which threads the
+     * body/headers automatically.
+     */
+    pay: (response: Response, options?: PayRetryOptions) => Promise<Response>;
+    /**
+     * `fetch(url, init)` wrapper: does the initial fetch, and on 402 calls
+     * `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.
+     */
+    fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
 };
 declare function createPaymentSigner(opts?: PaySignerOptions): PaymentSigner;
 declare const paymentSigner: PaymentSigner;

package/dist/index.js

@@ -755,6 +755,19 @@ function parseMppChallenge(response) {
 // src/payment-signer.ts
 import { randomBytes } from "crypto";
 
+// src/workflow-slug.ts
+var KEEPERHUB_WORKFLOW_RE = /\/api\/mcp\/workflows\/([a-zA-Z0-9_-]+)\/call(?:\/?)(?:\?|$|#)/;
+function extractKeeperHubWorkflowSlug(url) {
+  if (!url || url.length === 0) {
+    return { ok: false, reason: "EMPTY_URL" };
+  }
+  const match = KEEPERHUB_WORKFLOW_RE.exec(url);
+  if (!match || !match[1]) {
+    return { ok: false, reason: "URL_PATTERN_MISMATCH" };
+  }
+  return { ok: true, slug: match[1] };
+}
+
 // src/x402-detect.ts
 function isX402Shape(value) {
   if (typeof value !== "object" || value === null) {
@@ -852,22 +865,33 @@ function createPaymentSigner(opts = {}) {
     }
     return result.signature;
   }
-  async function payViaMpp(response, mpp, wallet) {
+  async function payViaMpp(response, mpp, wallet, retry) {
+    const slug = extractKeeperHubWorkflowSlug(response.url);
+    if (!slug.ok) {
+      throw new KeeperHubError(
+        "UNSUPPORTED_RECIPIENT",
+        `This wallet only signs payments for KeeperHub workflows. The 402 came from a URL that does not match /api/mcp/workflows/<slug>/call (reason: ${slug.reason}). See KEEP-311 for generic x402 support.`
+      );
+    }
     const client = clientFactory(wallet);
     const signature = await signOrPoll(client, {
       chain: "tempo",
+      workflowSlug: slug.slug,
       paymentChallenge: {
         kind: "mpp",
         serialized: mpp.serialized,
         chainId: TEMPO_CHAIN_ID
       }
     });
+    const headers = new Headers(retry?.headers);
+    headers.set("Authorization", `Payment ${signature}`);
     return fetchImpl(response.url, {
-      method: "POST",
-      headers: { Authorization: `Payment ${signature}` }
+      method: retry?.method ?? "POST",
+      headers,
+      body: retry?.body ?? void 0
     });
   }
-  async function payViaX402(response, x402, wallet) {
+  async function payViaX402(response, x402, wallet, retry) {
     const accept = x402.accepts[0];
     if (!accept) {
       throw new KeeperHubError(
@@ -875,6 +899,13 @@ function createPaymentSigner(opts = {}) {
         "x402 challenge has no accepts entries"
       );
     }
+    const slug = extractKeeperHubWorkflowSlug(x402.resource.url || response.url);
+    if (!slug.ok) {
+      throw new KeeperHubError(
+        "UNSUPPORTED_RECIPIENT",
+        `This wallet only signs payments for KeeperHub workflows. The 402 came from a URL that does not match /api/mcp/workflows/<slug>/call (reason: ${slug.reason}). See KEEP-311 for generic x402 support.`
+      );
+    }
     const now = Math.floor(Date.now() / 1e3);
     const validAfter = now - VALID_AFTER_PAST_SLACK_SECONDS;
     const validBefore = now + accept.maxTimeoutSeconds;
@@ -882,6 +913,7 @@ function createPaymentSigner(opts = {}) {
     const client = clientFactory(wallet);
     const signature = await signOrPoll(client, {
       chain: "base",
+      workflowSlug: slug.slug,
       paymentChallenge: {
         kind: "x402",
         payTo: accept.payTo,
@@ -908,29 +940,44 @@ function createPaymentSigner(opts = {}) {
       JSON.stringify(paymentSigPayload)
     ).toString("base64");
     const retryUrl = x402.resource.url || response.url;
+    const headers = new Headers(retry?.headers);
+    headers.set("PAYMENT-SIGNATURE", paymentSigHeader);
     return fetchImpl(retryUrl, {
-      method: "POST",
-      headers: { "PAYMENT-SIGNATURE": paymentSigHeader }
+      method: retry?.method ?? "POST",
+      headers,
+      body: retry?.body ?? void 0
     });
   }
+  async function pay(response, options) {
+    if (response.status !== 402) {
+      return response;
+    }
+    const x402 = await parseX402Challenge(response);
+    const mpp = parseMppChallenge(response);
+    if (!(x402 || mpp)) {
+      return response;
+    }
+    const wallet = await walletLoader();
+    if (mpp) {
+      return payViaMpp(response, mpp, wallet, options);
+    }
+    if (x402) {
+      return payViaX402(response, x402, wallet, options);
+    }
+    return response;
+  }
   return {
-    async pay(response) {
-      if (response.status !== 402) {
-        return response;
-      }
-      const x402 = await parseX402Challenge(response);
-      const mpp = parseMppChallenge(response);
-      if (!(x402 || mpp)) {
-        return response;
-      }
-      const wallet = await walletLoader();
-      if (mpp) {
-        return payViaMpp(response, mpp, wallet);
+    pay,
+    async fetch(input, init) {
+      const first = await fetchImpl(input, init);
+      if (first.status !== 402) {
+        return first;
       }
-      if (x402) {
-        return payViaX402(response, x402, wallet);
-      }
-      return response;
+      return pay(first, {
+        body: init?.body ?? void 0,
+        headers: init?.headers,
+        method: init?.method
+      });
     }
   };
 }