@agentcash/router 1.2.2 → 1.2.4

package/.claude/skills/router-guide/SKILL.md

@@ -104,6 +104,7 @@ Response out
 | `src/server.ts` | x402 server initialization with retry |
 | `src/auth/siwx.ts` | SIWX verification |
 | `src/auth/api-key.ts` | API key verification |
+| `src/upstash-rest.ts` | Minimal fetch-only Upstash REST client for `useDefaultStore` |
 | `src/auth/nonce.ts` | `NonceStore` interface + `MemoryNonceStore` |
 | `src/discovery/well-known.ts` | `.well-known/x402` generation |
 | `src/discovery/openapi.ts` | OpenAPI 3.1 spec generation |
@@ -180,6 +181,7 @@ export const router = createRouter({
     currency: '0x20c0000000000000000000000000000000000000', // PathUSD on Tempo
     recipient: process.env.X402_PAYEE_ADDRESS!,
     rpcUrl: process.env.TEMPO_RPC_URL,  // falls back to TEMPO_RPC_URL env var
+    useDefaultStore: true,              // auto-configures Upstash from KV_REST_API_URL + KV_REST_API_TOKEN
   },
   siwx: { nonceStore },              // custom nonce store
 });
@@ -420,6 +422,48 @@ The type system (generic parameters `HasAuth`, `NeedsBody`, `HasBody`) prevents
 - `.siwx()` is mutually exclusive with `.paid()`
 - `.apiKey()` CAN compose with `.paid()`
 
+## MPP Persistent Store
+
+mppx uses a key-value store for transaction hash replay protection. Without a persistent store, `Store.memory()` is used — which is wiped on every cold start. This is unsafe on Vercel or any multi-instance deployment.
+
+### Vercel (zero config)
+
+Set `useDefaultStore: true` to auto-configure an Upstash-backed store from Vercel KV environment variables (`KV_REST_API_URL` + `KV_REST_API_TOKEN`). Uses raw `fetch` — no extra npm dependencies.
+
+```typescript
+createRouter({
+  mpp: {
+    secretKey: process.env.MPP_SECRET_KEY!,
+    currency: USDC,
+    useDefaultStore: true, // reads KV_REST_API_URL + KV_REST_API_TOKEN automatically
+  }
+})
+```
+
+### Cloudflare / custom
+
+Pass any `Store.Store` implementation directly via `mpp.store`:
+
+```typescript
+import { Store } from 'mppx'
+
+createRouter({
+  mpp: {
+    secretKey: process.env.MPP_SECRET_KEY!,
+    currency: USDC,
+    store: Store.cloudflare(env.MY_KV_NAMESPACE),
+  }
+})
+```
+
+Available adapters from `mppx`: `Store.upstash(redis)`, `Store.cloudflare(kv)`, `Store.redis(client)`, `Store.memory()`, `Store.from(custom)`.
+
+### Resolution order
+
+1. Explicit `store` wins if provided
+2. `useDefaultStore: true` creates an Upstash store from env vars
+3. Neither → mppx defaults to `Store.memory()`
+
 ## MPP Internals
 
 The router uses `mppx`'s high-level `Mppx.create()` API, which encapsulates the entire challenge-credential-receipt lifecycle.
@@ -509,6 +553,7 @@ Barrel validation catches mismatches: keys in `prices` but not registered → er
 | MPP 401 `unauthorized: authentication required` | Using default unauthenticated Tempo RPC | Set `TEMPO_RPC_URL` env var or `mpp.rpcUrl` config with authenticated URL |
 | `route 'X' in prices map but not registered` | Discovery endpoint hit before route module loaded | Add barrel import to discovery route files |
 | `mppx package is required` | mppx not installed | `pnpm add mppx` — it's an optional peer dep |
+| `useDefaultStore requires KV_REST_API_URL` | Vercel KV env vars not set | Add Vercel KV integration or set `KV_REST_API_URL` + `KV_REST_API_TOKEN` manually |
 
 ## Maintaining This Skill
 

package/dist/index.cjs

@@ -307,6 +307,47 @@ var init_server = __esm({
   }
 });
 
+// src/upstash-rest.ts
+var upstash_rest_exports = {};
+__export(upstash_rest_exports, {
+  createUpstashRest: () => createUpstashRest
+});
+function createUpstashRest(url, token) {
+  const base = url.replace(/\/+$/, "");
+  const headers = { Authorization: `Bearer ${token}` };
+  return {
+    async get(key) {
+      const res = await fetch(`${base}/get/${key}`, { headers });
+      if (!res.ok) throw new Error(`[upstash-rest] GET ${key}: ${res.status}`);
+      const { result } = await res.json();
+      return result ?? null;
+    },
+    async set(key, value) {
+      const res = await fetch(`${base}`, {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify(["SET", key, JSON.stringify(value)])
+      });
+      if (!res.ok) throw new Error(`[upstash-rest] SET ${key}: ${res.status}`);
+      return await res.json();
+    },
+    async del(key) {
+      const res = await fetch(`${base}`, {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify(["DEL", key])
+      });
+      if (!res.ok) throw new Error(`[upstash-rest] DEL ${key}: ${res.status}`);
+      return await res.json();
+    }
+  };
+}
+var init_upstash_rest = __esm({
+  "src/upstash-rest.ts"() {
+    "use strict";
+  }
+});
+
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
@@ -2229,6 +2270,7 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
         title: discovery.title,
         description: discovery.description,
         version: discovery.version,
+        ...guidance !== void 0 && { "x-guidance": guidance },
         guidance,
         ...discovery.contact && { contact: discovery.contact }
       },
@@ -2473,8 +2515,21 @@ function createRouter(config) {
         const getClient = async () => deps.tempoClient;
         let feePayerAccount;
         if (config.mpp.feePayerKey) {
-          const { Account } = await import("viem/tempo");
-          feePayerAccount = Account.fromSecp256k1(config.mpp.feePayerKey);
+          const { privateKeyToAccount } = await import("viem/accounts");
+          feePayerAccount = privateKeyToAccount(config.mpp.feePayerKey);
+        }
+        let resolvedStore = config.mpp.store;
+        if (!resolvedStore && config.mpp.useDefaultStore) {
+          const kvUrl = process.env.KV_REST_API_URL;
+          const kvToken = process.env.KV_REST_API_TOKEN;
+          if (!kvUrl || !kvToken) {
+            throw new Error(
+              "mpp.useDefaultStore requires KV_REST_API_URL and KV_REST_API_TOKEN environment variables. These are automatically set by Vercel KV."
+            );
+          }
+          const { Store } = await import("mppx");
+          const { createUpstashRest: createUpstashRest2 } = await Promise.resolve().then(() => (init_upstash_rest(), upstash_rest_exports));
+          resolvedStore = Store.upstash(createUpstashRest2(kvUrl, kvToken));
         }
         deps.mppx = Mppx.create({
           methods: [
@@ -2482,7 +2537,8 @@ function createRouter(config) {
               currency: config.mpp.currency,
               recipient: config.mpp.recipient ?? config.payeeAddress,
               getClient,
-              ...feePayerAccount ? { feePayer: feePayerAccount } : {}
+              ...feePayerAccount ? { feePayer: feePayerAccount } : {},
+              ...resolvedStore ? { store: resolvedStore } : {}
             })
           ],
           secretKey: config.mpp.secretKey,

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { FacilitatorConfig } from '@x402/core/http';
 import { NextRequest, NextResponse } from 'next/server';
 import { ZodType } from 'zod';
+import { Store } from 'mppx';
 import { PaymentRequirements, PaymentRequired, SettleResponse, Network } from '@x402/core/types';
 import * as viem from 'viem';
 export { S as SIWX_ERROR_MESSAGES, a as SiwxErrorCode } from './siwx-BMlja_nt.cjs';
@@ -354,6 +355,36 @@ interface RouterConfig {
          * Must be a hex-encoded private key (e.g. `0xabc123...`).
          */
         feePayerKey?: string;
+        /**
+         * Persistent store for transaction hash replay protection.
+         *
+         * Without this, mppx defaults to `Store.memory()` which is wiped on every cold start —
+         * unsafe on Vercel or any multi-instance deployment. Pass `Store.upstash(redis)` or
+         * `Store.cloudflare(kv)` for a shared persistent store.
+         *
+         * @example
+         * import { Store } from 'mppx'
+         * store: Store.upstash({ get, set, del })
+         * store: Store.cloudflare(env.MY_KV_NAMESPACE)
+         */
+        store?: Store.Store;
+        /**
+         * When `true`, auto-configures an Upstash-backed persistent store from Vercel KV
+         * environment variables (`KV_REST_API_URL` + `KV_REST_API_TOKEN`).
+         *
+         * Uses raw `fetch` against the Upstash REST API — no extra npm dependencies.
+         * Ignored when `store` is explicitly provided.
+         *
+         * @example
+         * createRouter({
+         *   mpp: {
+         *     secretKey: process.env.MPP_SECRET_KEY!,
+         *     currency: USDC,
+         *     useDefaultStore: true,
+         *   }
+         * })
+         */
+        useDefaultStore?: boolean;
     };
     /**
      * Payment protocols to accept on auto-priced routes (those using the `prices` config).

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { FacilitatorConfig } from '@x402/core/http';
 import { NextRequest, NextResponse } from 'next/server';
 import { ZodType } from 'zod';
+import { Store } from 'mppx';
 import { PaymentRequirements, PaymentRequired, SettleResponse, Network } from '@x402/core/types';
 import * as viem from 'viem';
 export { S as SIWX_ERROR_MESSAGES, a as SiwxErrorCode } from './siwx-BMlja_nt.js';
@@ -354,6 +355,36 @@ interface RouterConfig {
          * Must be a hex-encoded private key (e.g. `0xabc123...`).
          */
         feePayerKey?: string;
+        /**
+         * Persistent store for transaction hash replay protection.
+         *
+         * Without this, mppx defaults to `Store.memory()` which is wiped on every cold start —
+         * unsafe on Vercel or any multi-instance deployment. Pass `Store.upstash(redis)` or
+         * `Store.cloudflare(kv)` for a shared persistent store.
+         *
+         * @example
+         * import { Store } from 'mppx'
+         * store: Store.upstash({ get, set, del })
+         * store: Store.cloudflare(env.MY_KV_NAMESPACE)
+         */
+        store?: Store.Store;
+        /**
+         * When `true`, auto-configures an Upstash-backed persistent store from Vercel KV
+         * environment variables (`KV_REST_API_URL` + `KV_REST_API_TOKEN`).
+         *
+         * Uses raw `fetch` against the Upstash REST API — no extra npm dependencies.
+         * Ignored when `store` is explicitly provided.
+         *
+         * @example
+         * createRouter({
+         *   mpp: {
+         *     secretKey: process.env.MPP_SECRET_KEY!,
+         *     currency: USDC,
+         *     useDefaultStore: true,
+         *   }
+         * })
+         */
+        useDefaultStore?: boolean;
     };
     /**
      * Payment protocols to accept on auto-priced routes (those using the `prices` config).

package/dist/index.js

@@ -285,6 +285,47 @@ var init_server = __esm({
   }
 });
 
+// src/upstash-rest.ts
+var upstash_rest_exports = {};
+__export(upstash_rest_exports, {
+  createUpstashRest: () => createUpstashRest
+});
+function createUpstashRest(url, token) {
+  const base = url.replace(/\/+$/, "");
+  const headers = { Authorization: `Bearer ${token}` };
+  return {
+    async get(key) {
+      const res = await fetch(`${base}/get/${key}`, { headers });
+      if (!res.ok) throw new Error(`[upstash-rest] GET ${key}: ${res.status}`);
+      const { result } = await res.json();
+      return result ?? null;
+    },
+    async set(key, value) {
+      const res = await fetch(`${base}`, {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify(["SET", key, JSON.stringify(value)])
+      });
+      if (!res.ok) throw new Error(`[upstash-rest] SET ${key}: ${res.status}`);
+      return await res.json();
+    },
+    async del(key) {
+      const res = await fetch(`${base}`, {
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify(["DEL", key])
+      });
+      if (!res.ok) throw new Error(`[upstash-rest] DEL ${key}: ${res.status}`);
+      return await res.json();
+    }
+  };
+}
+var init_upstash_rest = __esm({
+  "src/upstash-rest.ts"() {
+    "use strict";
+  }
+});
+
 // src/registry.ts
 var RouteRegistry = class {
   routes = /* @__PURE__ */ new Map();
@@ -2190,6 +2231,7 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, discovery) {
         title: discovery.title,
         description: discovery.description,
         version: discovery.version,
+        ...guidance !== void 0 && { "x-guidance": guidance },
         guidance,
         ...discovery.contact && { contact: discovery.contact }
       },
@@ -2434,8 +2476,21 @@ function createRouter(config) {
         const getClient = async () => deps.tempoClient;
         let feePayerAccount;
         if (config.mpp.feePayerKey) {
-          const { Account } = await import("viem/tempo");
-          feePayerAccount = Account.fromSecp256k1(config.mpp.feePayerKey);
+          const { privateKeyToAccount } = await import("viem/accounts");
+          feePayerAccount = privateKeyToAccount(config.mpp.feePayerKey);
+        }
+        let resolvedStore = config.mpp.store;
+        if (!resolvedStore && config.mpp.useDefaultStore) {
+          const kvUrl = process.env.KV_REST_API_URL;
+          const kvToken = process.env.KV_REST_API_TOKEN;
+          if (!kvUrl || !kvToken) {
+            throw new Error(
+              "mpp.useDefaultStore requires KV_REST_API_URL and KV_REST_API_TOKEN environment variables. These are automatically set by Vercel KV."
+            );
+          }
+          const { Store } = await import("mppx");
+          const { createUpstashRest: createUpstashRest2 } = await Promise.resolve().then(() => (init_upstash_rest(), upstash_rest_exports));
+          resolvedStore = Store.upstash(createUpstashRest2(kvUrl, kvToken));
         }
         deps.mppx = Mppx.create({
           methods: [
@@ -2443,7 +2498,8 @@ function createRouter(config) {
               currency: config.mpp.currency,
               recipient: config.mpp.recipient ?? config.payeeAddress,
               getClient,
-              ...feePayerAccount ? { feePayer: feePayerAccount } : {}
+              ...feePayerAccount ? { feePayer: feePayerAccount } : {},
+              ...resolvedStore ? { store: resolvedStore } : {}
             })
           ],
           secretKey: config.mpp.secretKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -29,7 +29,7 @@
     "@x402/evm": "^2.3.0",
     "@x402/extensions": "^2.3.0",
     "@x402/svm": "2.3.0",
-    "mppx": "^0.4.2",
+    "mppx": "^0.4.10",
     "next": ">=15.0.0",
     "zod": "^4.0.0",
     "zod-openapi": "^5.0.0"
@@ -61,14 +61,14 @@
     "@x402/extensions": "^2.3.0",
     "@x402/svm": "2.3.0",
     "eslint": "^10.0.0",
-    "mppx": "^0.4.8",
+    "mppx": "^0.4.10",
     "next": "^15.0.0",
     "prettier": "^3.8.1",
     "react": "^19.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.8.0",
     "typescript-eslint": "^8.55.0",
-    "viem": "^2.47.2",
+    "viem": "^2.47.6",
     "vitest": "^3.0.0",
     "zod": "^4.0.0",
     "zod-openapi": "^5.0.0"