@agentcash/router 0.4.0 → 0.4.2

package/.claude/CLAUDE.md

@@ -46,6 +46,16 @@ The router uses the default facilitator from `@coinbase/x402`, which requires CD
 
 **Critical for Next.js apps with env validation (T3 stack, `@t3-oss/env-nextjs`):** These variables must be explicitly declared in your env schema. Next.js does not automatically expose all env vars to `process.env` — undeclared vars are invisible at runtime.
 
+### MPP (Tempo) Environment Variables
+
+MPP payment verification requires an **authenticated** Tempo RPC endpoint. The public `https://rpc.tempo.xyz/` returns `401 Unauthorized`.
+
+- `TEMPO_RPC_URL` — Authenticated Tempo RPC URL (e.g. `https://user:pass@rpc.mainnet.tempo.xyz`)
+
+Alternatively, pass `rpcUrl` in the `mpp` config object to `createRouter()`. Without either, MPP on-chain verification fails with "unauthorized: authentication required".
+
+### CDP Environment Variables
+
 Without these keys, the default facilitator cannot authenticate with CDP:
 - x402 server `initialize()` fails with "Failed to fetch supported kinds from facilitator: TypeError: fetch failed" or "Facilitator getSupported failed (401): Unauthorized"
 - All payment routes return empty 402 responses (no `PAYMENT-REQUIRED` header, no body)
@@ -84,3 +94,29 @@ pnpm test       # vitest
 pnpm typecheck  # tsc --noEmit
 pnpm check      # format + lint + typecheck + build + test
 ```
+
+## Development Record
+
+The `.claude/` directory contains design docs, decision records, and bug analyses that document the reasoning behind the router's architecture. See `.claude/INDEX.md` for a table of contents.
+
+**Convention:** Every doc has a `Status` header. When you resolve work described in a doc, update its Status to `Resolved in vX.Y.Z` and update INDEX.md.
+
+## Releasing
+
+This repo uses [changesets](https://github.com/changesets/changesets) for versioning and npm publishing.
+
+### When doing work that should be released:
+
+1. **Create a changeset** — Run `pnpm changeset` and describe the changes (patch/minor/major)
+2. **Include the changeset file** in your PR (committed to `.changeset/`)
+3. **Merge PR to main**
+
+### What happens automatically:
+
+1. When PRs with changesets merge to `main`, the `changesets/action` creates a **"chore: version packages"** PR that bumps `package.json` version and updates `CHANGELOG.md`
+2. When that version PR is merged, the action **publishes to npm** automatically
+
+### Troubleshooting
+
+- **Publish fails**: Check `NPM_TOKEN` secret is set and has write access to `@agentcash` scope
+- **No version PR created**: Ensure your PR included a `.changeset/*.md` file

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

@@ -31,7 +31,7 @@ Every paid API route in a Merit Systems service shared the same ~80-150 lines of
 
 7. **Self-registering routes + validated barrel (Approach B).** Routes self-register via `.handler()` at import time. A barrel file imports all route modules. Discovery endpoints (`.wellKnown()`, `.openapi()`) validate that the barrel is complete by comparing registered routes against the `prices` map. For routes in separate handler files (e.g., Next.js `route.ts` files), use **discovery stubs** — lightweight registrations that provide metadata for discovery without the real handler. Guard stubs with `registry.has()` to avoid unnecessary overwrites.
 
-8. **Both x402 and MPP ship from day one.** Dual-protocol support is not an afterthought. Routes declare `protocols: ['x402', 'mpp']` and the orchestration layer routes to the correct handler based on the request header. MPP uses low-level `mpay` primitives (`Challenge`, `Credential`, `tempo.charge`) — not the high-level `Mpay.create()` wrapper — because the router owns orchestration.
+8. **Both x402 and MPP ship from day one.** Dual-protocol support is not an afterthought. Routes declare `protocols: ['x402', 'mpp']` and the orchestration layer routes to the correct handler based on the request header. MPP uses low-level `mppx` primitives (`Challenge`, `Credential`, `tempo.charge`) — not the high-level `Mppx.create()` wrapper — because the router owns orchestration.
 
 9. **`zod-openapi` for OpenAPI 3.1.** Zod schemas are the single source of truth for request/response types. OpenAPI docs are auto-generated from them. No manual spec maintenance.
 
@@ -101,7 +101,7 @@ Response out
 | `src/registry.ts` | `RouteRegistry` with barrel validation |
 | `src/protocols/detect.ts` | Header-based protocol detection |
 | `src/protocols/x402.ts` | x402 challenge/verify/settle wrappers |
-| `src/protocols/mpp.ts` | MPP challenge/verify/receipt wrappers (uses mpay low-level primitives) |
+| `src/protocols/mpp.ts` | MPP challenge/verify/receipt wrappers (uses mppx low-level primitives) |
 | `src/server.ts` | x402 server initialization with retry |
 | `src/auth/siwx.ts` | SIWX verification |
 | `src/auth/api-key.ts` | API key verification |
@@ -159,7 +159,7 @@ TEMPO_RPC_URL=https://user:pass@rpc.mainnet.tempo.xyz  # Authenticated Tempo RPC
 
 **Tempo RPC requires authentication.** The default `rpc.tempo.xyz` returns 401. Get credentials from the Tempo team. The `rpcUrl` can be set in config or via `TEMPO_RPC_URL` env var (config takes precedence).
 
-**Peer dependencies for MPP:** `mpay` is an optional peer dep. When installed, it brings `viem` as a transitive dependency. Both are required for MPP support.
+**Peer dependencies for MPP:** `mppx` is an optional peer dep. It has `viem` as a peer dependency. Both are required for MPP support.
 
 ## Creating Routes
 
@@ -176,7 +176,7 @@ export const router = createRouter({
   protocols: ['x402', 'mpp'],        // protocols for auto-priced routes (default: ['x402'])
   plugin: myPlugin,                   // observability
   prices: { 'search': '0.02' },      // central pricing map
-  mpp: {                              // MPP support (requires mpay peer dep)
+  mpp: {                              // MPP support (requires mppx peer dep)
     secretKey: process.env.MPP_SECRET_KEY!,
     currency: '0x20c0000000000000000000000000000000000000', // PathUSD on Tempo
     recipient: process.env.X402_PAYEE_ADDRESS!,
@@ -417,7 +417,7 @@ The type system (generic parameters `HasAuth`, `NeedsBody`, `HasBody`) prevents
 
 ## MPP Internals (Critical Pitfalls)
 
-The router uses mpay's **low-level primitives**, not the high-level `Mpay.create()` API. This matters because mpay's internals have subtle conventions:
+The router uses mppx's **low-level primitives**, not the high-level `Mppx.create()` API. This matters because mppx's internals have subtle conventions:
 
 1. **NextRequest vs Request.** `Credential.fromRequest()` breaks with Next.js `NextRequest` due to subtle header handling differences. The router converts via `toStandardRequest()` — creating a new standard `Request` with the same URL, method, headers, and body.
 
@@ -425,11 +425,11 @@ The router uses mpay's **low-level primitives**, not the high-level `Mpay.create
 
 3. **`tempo.charge().verify()` returns a receipt, not `{ valid, payer }`.** On success it returns `{ method, status, reference, timestamp }`. On failure it throws. Check `receipt.status === 'success'`, not `receipt.valid`.
 
-4. **`getClient` must be synchronous.** mpay's `Client.getResolver()` checks `if (getClient) return getClient` — it does NOT await. An async `getClient` will silently fall through to the default RPC URL.
+4. **`tempo.charge()` constructor takes operational config only.** In mppx, `currency` and `recipient` are NOT passed to `tempo.charge()`. They are passed in the `request` object to `Challenge.fromIntent()` and `verify()`. Only `getClient`, `decimals`, `feePayer`, `testnet`, etc. go in the constructor.
 
 5. **Tempo RPC requires authentication.** The default `rpc.tempo.xyz` returns 401. Always provide `rpcUrl` or set `TEMPO_RPC_URL` env var with authenticated credentials.
 
-6. **viem is loaded eagerly in `ensureMpay()`.** Since `getClient` must be synchronous, viem's `createClient` and `http` are loaded once when mpay initializes, not per-call. viem is a transitive dep of mpay and is always available when mpay is installed.
+6. **viem is a peer dep of mppx.** The router uses viem directly for `createClient` and `http` in `buildGetClient()`. viem is always available when mppx is installed as a peer dep.
 
 ## Registration-Time Validation
 
@@ -501,7 +501,7 @@ Barrel validation catches mismatches: keys in `prices` but not registered → er
 | MPP verify returns `status: 'success'` but route returns 402 | Code checking `.valid` instead of `.status` | Verify returns a receipt `{ status, reference }`, not `{ valid, payer }` |
 | MPP using wrong RPC URL after rebuild | Next.js webpack cache or stale pnpm link | Delete `.next/`, run `pnpm install` in the app to pick up new router dist |
 | `route 'X' in prices map but not registered` | Discovery endpoint hit before route module loaded | Add barrel import to discovery route files |
-| `mpay package is required` | mpay not installed | `pnpm add mpay` — it's an optional peer dep |
+| `mppx package is required` | mppx not installed | `pnpm add mppx` — it's an optional peer dep |
 
 ## Maintaining This Skill
 

package/README.md

@@ -15,7 +15,7 @@ Peer dependencies:
 ```bash
 pnpm add next zod @x402/core @x402/evm @x402/extensions @coinbase/x402 zod-openapi
 # Optional: for MPP support
-pnpm add mpay
+pnpm add mppx
 ```
 
 ## Environment Setup

package/dist/index.cjs

@@ -354,8 +354,8 @@ async function settleX402Payment(server, payload, requirements) {
 }
 
 // src/protocols/mpp.ts
-var import_mpay = require("mpay");
-var import_server2 = require("mpay/server");
+var import_mppx = require("mppx");
+var import_server2 = require("mppx/server");
 var import_viem = require("viem");
 var import_chains = require("viem/chains");
 function buildGetClient(rpcUrl) {
@@ -371,10 +371,7 @@ function toStandardRequest(request) {
   }
   return new Request(request.url, {
     method: request.method,
-    headers: request.headers,
-    body: request.body,
-    // @ts-expect-error - Request.duplex is required for streaming bodies but not in types yet
-    duplex: "half"
+    headers: request.headers
   });
 }
 var DEFAULT_DECIMALS = 6;
@@ -382,11 +379,8 @@ async function buildMPPChallenge(routeEntry, request, mppConfig, price) {
   const standardRequest = toStandardRequest(request);
   const currency = mppConfig.currency;
   const recipient = mppConfig.recipient ?? "";
-  const methodIntent = import_server2.tempo.charge({
-    currency,
-    recipient
-  });
-  const challenge = import_mpay.Challenge.fromIntent(methodIntent, {
+  const methodIntent = import_server2.tempo.charge();
+  const challenge = import_mppx.Challenge.fromIntent(methodIntent, {
     secretKey: mppConfig.secretKey,
     realm: new URL(standardRequest.url).origin,
     request: {
@@ -396,7 +390,7 @@ async function buildMPPChallenge(routeEntry, request, mppConfig, price) {
       decimals: DEFAULT_DECIMALS
     }
   });
-  return import_mpay.Challenge.serialize(challenge);
+  return import_mppx.Challenge.serialize(challenge);
 }
 async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
   const standardRequest = toStandardRequest(request);
@@ -408,19 +402,17 @@ async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
       console.error("[MPP] No Authorization header found");
       return null;
     }
-    const credential = import_mpay.Credential.fromRequest(standardRequest);
+    const credential = import_mppx.Credential.fromRequest(standardRequest);
     if (!credential?.challenge) {
       console.error("[MPP] Invalid credential structure");
       return null;
     }
-    const isValid = import_mpay.Challenge.verify(credential.challenge, { secretKey: mppConfig.secretKey });
+    const isValid = import_mppx.Challenge.verify(credential.challenge, { secretKey: mppConfig.secretKey });
     if (!isValid) {
       console.error("[MPP] Challenge HMAC verification failed");
       return { valid: false, payer: null };
     }
     const methodIntent = import_server2.tempo.charge({
-      currency,
-      recipient,
       ...buildGetClient(mppConfig.rpcUrl)
     });
     const paymentRequest = {
@@ -429,10 +421,9 @@ async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
       recipient,
       decimals: DEFAULT_DECIMALS
     };
-    const resolvedRequest = methodIntent.request ? await methodIntent.request({ credential, request: paymentRequest }) : paymentRequest;
     const receipt = await methodIntent.verify({
       credential,
-      request: resolvedRequest
+      request: paymentRequest
     });
     if (!receipt || receipt.status !== "success") {
       console.error("[MPP] Tempo verification failed:", receipt);
@@ -454,13 +445,13 @@ async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
   }
 }
 function buildMPPReceipt(reference) {
-  const receipt = import_mpay.Receipt.from({
+  const receipt = import_mppx.Receipt.from({
     method: "tempo",
     status: "success",
     reference,
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   });
-  return import_mpay.Receipt.serialize(receipt);
+  return import_mppx.Receipt.serialize(receipt);
 }
 
 // src/auth/siwx.ts

package/dist/index.js

@@ -320,8 +320,8 @@ async function settleX402Payment(server, payload, requirements) {
 }
 
 // src/protocols/mpp.ts
-import { Challenge, Credential, Receipt } from "mpay";
-import { tempo } from "mpay/server";
+import { Challenge, Credential, Receipt } from "mppx";
+import { tempo } from "mppx/server";
 import { createClient, http } from "viem";
 import { tempo as tempoChain } from "viem/chains";
 function buildGetClient(rpcUrl) {
@@ -337,10 +337,7 @@ function toStandardRequest(request) {
   }
   return new Request(request.url, {
     method: request.method,
-    headers: request.headers,
-    body: request.body,
-    // @ts-expect-error - Request.duplex is required for streaming bodies but not in types yet
-    duplex: "half"
+    headers: request.headers
   });
 }
 var DEFAULT_DECIMALS = 6;
@@ -348,10 +345,7 @@ async function buildMPPChallenge(routeEntry, request, mppConfig, price) {
   const standardRequest = toStandardRequest(request);
   const currency = mppConfig.currency;
   const recipient = mppConfig.recipient ?? "";
-  const methodIntent = tempo.charge({
-    currency,
-    recipient
-  });
+  const methodIntent = tempo.charge();
   const challenge = Challenge.fromIntent(methodIntent, {
     secretKey: mppConfig.secretKey,
     realm: new URL(standardRequest.url).origin,
@@ -385,8 +379,6 @@ async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
       return { valid: false, payer: null };
     }
     const methodIntent = tempo.charge({
-      currency,
-      recipient,
       ...buildGetClient(mppConfig.rpcUrl)
     });
     const paymentRequest = {
@@ -395,10 +387,9 @@ async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
       recipient,
       decimals: DEFAULT_DECIMALS
     };
-    const resolvedRequest = methodIntent.request ? await methodIntent.request({ credential, request: paymentRequest }) : paymentRequest;
     const receipt = await methodIntent.verify({
       credential,
-      request: resolvedRequest
+      request: paymentRequest
     });
     if (!receipt || receipt.status !== "success") {
       console.error("[MPP] Tempo verification failed:", receipt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -23,28 +23,23 @@
     ".claude/CLAUDE.md",
     ".claude/skills"
   ],
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src/",
-    "lint:fix": "eslint src/ --fix",
-    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts' '*.json' '*.mjs'",
-    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts' '*.json' '*.mjs'",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm build && pnpm test"
-  },
   "peerDependencies": {
     "@coinbase/x402": "^2.1.0",
     "@x402/core": "^2.3.0",
     "@x402/evm": "^2.3.0",
     "@x402/extensions": "^2.3.0",
-    "mpay": "^0.2.4",
+    "mppx": "^0.1.1",
     "next": ">=15.0.0",
     "zod": "^4.0.0",
     "zod-openapi": "^5.0.0"
   },
+  "peerDependenciesMeta": {
+    "mppx": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@changesets/cli": "^2.29.8",
     "@coinbase/x402": "^2.1.0",
     "@eslint/js": "^10.0.1",
     "@types/node": "^22.0.0",
@@ -52,7 +47,7 @@
     "@x402/evm": "^2.3.0",
     "@x402/extensions": "^2.3.0",
     "eslint": "^10.0.0",
-    "mpay": "^0.2.4",
+    "mppx": "^0.1.1",
     "next": "^15.0.0",
     "prettier": "^3.8.1",
     "react": "^19.0.0",
@@ -64,10 +59,20 @@
     "zod": "^4.0.0",
     "zod-openapi": "^5.0.0"
   },
-  "packageManager": "pnpm@10.28.0",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/merit-systems/agentcash-router.git"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write 'src/**/*.ts' 'tests/**/*.ts' '*.json' '*.mjs'",
+    "format:check": "prettier --check 'src/**/*.ts' 'tests/**/*.ts' '*.json' '*.mjs'",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm build && pnpm test"
   }
-}
+}