@agentcash/router 1.6.0 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -20,8 +20,8 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
-    ".claude/CLAUDE.md",
-    ".claude/skills"
+    "AGENTS.md",
+    "README.md"
   ],
   "peerDependencies": {
     "@coinbase/x402": "^2.1.0",
@@ -42,25 +42,16 @@
   "devDependencies": {
     "@changesets/cli": "^2.29.8",
     "@coinbase/x402": "^2.1.0",
-    "@crossmint/lobster-cli": "^0.1.6",
     "@eslint/js": "^10.0.1",
-    "@faremeter/facilitator": "0.17.1",
-    "@faremeter/fetch": "^0.17.1",
-    "@faremeter/info": "^0.17.1",
-    "@faremeter/payment-solana": "^0.17.1",
-    "@faremeter/types": "^0.17.1",
-    "@faremeter/wallet-solana": "^0.17.1",
-    "@faremeter/x-solana-settlement": "^0.4.0",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@solana/kit": "^5.1.0",
-    "@solana/spl-token": "^0.4.14",
-    "@solana/web3.js": "^1.98.4",
     "@types/node": "^22.0.0",
     "@x402/core": "^2.11.0",
     "@x402/evm": "^2.11.0",
     "@x402/extensions": "^2.11.0",
     "@x402/svm": "^2.11.0",
     "eslint": "^10.0.0",
+    "knip": "^6.13.1",
     "mppx": "^0.6.16",
     "next": "^15.0.0",
     "prettier": "^3.8.1",
@@ -87,6 +78,7 @@
     "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"
+    "knip": "knip",
+    "check": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm knip && pnpm build && pnpm test"
   }
 }

package/.claude/CLAUDE.md

@@ -1,343 +0,0 @@
-# CLAUDE.md — @agentcash/router
-
-Protocol-agnostic route framework for Next.js App Router APIs with x402 payment, MPP payment, SIWX identity auth, and API key auth. Used by stablestudio, enrichx402, x402email, agentfacilitator, agentupload.
-
-## Guiding Principles
-
-1. **Route definition is 3-6 lines.** Everything else is derived.
-2. **Single source of truth.** Route registry drives discovery, OpenAPI, pricing, Bazaar schemas.
-3. **Auth and pricing are orthogonal and composable.** `.paid()`, `.siwx()`, `.apiKey()`, `.unprotected()`.
-4. **Observability is pluggable via RouterPlugin.** Zero boilerplate.
-5. **The package owns the x402 server lifecycle.** Init, verify, settle.
-6. **Convention over configuration.** Sane defaults for Base, USDC, exact scheme.
-7. **Compose, don't reimplement.** Zero payment/auth protocol logic — delegates to `@x402/*`, `@coinbase/x402`, and `mppx`.
-
-## Architecture
-
-**Orchestrate pipeline:** auth check -> body parse -> price resolve -> payment verify -> handler invoke -> settle -> finalize
-
-- `src/orchestrate.ts` — Full request lifecycle orchestration
-- `src/builder.ts` — Fluent RouteBuilder API
-- `src/handler.ts` — Safe handler invocation with error mapping
-- `src/types.ts` — Core types (RouteEntry, HandlerContext, HttpError)
-- `src/registry.ts` — Route registry (Map-backed, silent overwrite on duplicate keys)
-- `src/pricing.ts` — Price resolution (static, tiered, dynamic)
-- `src/plugin.ts` — Plugin hook system
-- `src/server.ts` — x402 server initialization
-- `src/auth/` — Auth modules (siwx.ts, api-key.ts)
-- `src/kv-store/` — Single KV cache layer (`client.ts` is the only file that talks to Redis; `nonce.ts`/`entitlement.ts`/`mpp.ts` are namespaced adapters on top)
-- `src/protocols/` — Protocol handlers (x402.ts, detect.ts). MPP is handled via `mppx` high-level API (`Mppx.create` in index.ts)
-- `src/discovery/` — Auto-generated endpoints (well-known.ts, openapi.ts)
-
-## Auth Modes
-
-Four auth modes, mutually exclusive (except `.apiKey()` composes with `.paid()`):
-
-### `.paid(pricing)` — Payment required
-```typescript
-.paid('0.01')                    // Static price
-.paid((body) => calcPrice(body)) // Dynamic pricing (body-driven, pre-handler)
-.paid({ field: 'tier', tiers: { basic: { price: '0.01' } } }) // Tiered
-
-// Handler-driven dynamic pricing — `.handler()` request-mode bills exactly
-// tickCost per request; `.stream()` streaming bills per `charge()` call.
-.paid({ dynamic: true, tickCost: '0.0005', unitType: 'token', maxPrice: '0.10' })
-```
-
-#### Handler-driven dynamic (`.paid({ dynamic: true })`)
-
-The handler shape determines the billing model and wire transport:
-
-**Request-mode** — `async (ctx) => value`. Bills exactly `tickCost` per
-request. No `charge()` on the context — the wire commitment is fixed at
-credential verification (mppx's non-SSE auto-charge for MPP, or x402 `upto`
-settled for `tickCost`). This is the spec-aligned "discrete paid unit" mode
-per `paymentauth.org/draft-tempo-session-00`.
-
-```typescript
-router
-  .route('llm/summarize')
-  .paid({ dynamic: true, tickCost: '0.01', unitType: 'request', maxPrice: '0.01' })
-  .body(z.object({ prompt: z.string() }))
-  .handler(async ({ body }) => {
-    const summary = await callLLM(body.prompt);
-    return { summary }; // always bills $0.01
-  });
-```
-
-For variable-cost-per-request billing, use the streaming shape below —
-splitting work into yields lets `charge()` meter per unit.
-
-**Streaming mode** — `.stream(async function* (ctx) { ... })`. Receives a
-`charge()` callback on `ctx`; one call adds one tick. The invariant:
-
-> **one `charge()` call === one tick === `tickCost` USDC === one route-defined unit**
-
-The route picks `tickCost` to match its billing unit (one token at $0.0005,
-one byte at $0.0000001, one frame at $0.001) and labels it via `unitType`.
-Total billed is `tickCost × call_count`, capped at `maxPrice`. (Internally:
-mppx auto-charges one prepaid tick at credential verify and marks it; the
-first `charge()` consumes the prepaid without an extra debit, then subsequent
-calls bill fresh ticks live.)
-
-```typescript
-router
-  .route('llm/stream')
-  .paid({ dynamic: true, tickCost: '0.0001', unitType: 'token', maxPrice: '0.05', protocols: ['mpp'] })
-  .body(z.object({ prompt: z.string() }))
-  .stream(async function* ({ body, charge }) {
-    for await (const token of streamLLM(body.prompt)) {
-      await charge();        // one tick = one token; blocks on need-voucher
-      yield token;
-    }
-    yield '[DONE]';            // free trailing event — no charge before it
-  });
-```
-
-**Type safety**: TypeScript discriminates by which terminal method you call.
-`.handler()` receives a `HandlerContext` with no `charge` — calling it is a
-compile-time error. `.stream()` receives a `StreamingHandlerContext` with
-`charge` and is only callable after `.paid({ dynamic: true, ... })`.
-
-`tickCost` is required per-route on `.paid({ dynamic: true })` — the builder
-throws at registration if it's missing. `unitType` is optional (cosmetic
-label, defaults to undefined which mppx surfaces as plain ticks).
-
-**Transport selection**: the router picks the wire format from the terminal
-method. `.handler()` request-mode goes through plain HTTP with a
-`Payment-Receipt` header (mppx's `tempo.session({ sse: false })`). `.stream()`
-goes through SSE with inline per-tick voucher events
-(`tempo.session({ sse: true })`). Two mppx instances run side-by-side
-sharing the same store, secretKey, and realm so channel state and challenge
-HMACs are interchangeable.
-
-Both terminal methods work on x402 `upto` (settles cumulative atomic amount;
-Permit2Proxy enforces ≤ maxPrice) and MPP. `.stream()` requires MPP — x402
-has no streaming primitive.
-
-**`suggestedDeposit` on MPP session 402 challenges**: defaults to
-`tickCost × RouterConfig.mpp.session.depositMultiplier` (default `10`), or
-the route's `maxPrice` when set. Raise the multiplier at deployment level to
-cover more requests per channel, or set `maxPrice` per-route when a single
-request can exceed the default budget.
-
-### `.siwx()` — Wallet identity required (no payment)
-```typescript
-.siwx().handler(async ({ wallet }) => { /* wallet is verified */ })
-```
-
-### `.apiKey(resolver)` — API key / Bearer token auth
-For admin routes, cron jobs, internal services. Checks `X-API-Key` header OR `Authorization: Bearer <token>`.
-
-```typescript
-// Admin route with API key
-export const GET = router
-  .route('admin/users')
-  .apiKey(async (key) => {
-    const admin = await db.admin.findByKey(key);
-    return admin ?? null; // null = 401, truthy = ctx.account
-  })
-  .handler(async ({ account }) => {
-    // account is whatever resolver returned
-    return db.user.findMany();
-  });
-
-// Cron job with static secret
-export const POST = router
-  .route('cron/cleanup')
-  .apiKey((key) => key === process.env.CRON_SECRET ? { cron: true } : null)
-  .handler(async () => { /* ... */ });
-```
-
-**Headers accepted:** `X-API-Key: <key>` or `Authorization: Bearer <key>`
-
-**Composing with payment:** `.apiKey()` can layer on `.paid()` — auth runs first, payment second:
-```typescript
-.apiKey(resolver).paid('0.01') // Must pass API key AND pay
-```
-
-### `.unprotected()` — No auth
-```typescript
-.unprotected().handler(async () => { /* public endpoint */ })
-```
-
-## Pre-Payment Validation
-
-### `.validate(fn)` — Async business validation before 402 challenge
-
-For checks that need DB lookups or external APIs before showing a price. Runs after body parsing, before the 402 challenge. Requires `.body()`.
-
-```typescript
-// Domain registration with availability check
-router
-  .route('domain/register')
-  .paid(calculatePrice, { maxPrice: '10.00' })
-  .body(RegisterSchema)  // .body() before .validate() for type inference
-  .validate(async (body) => {
-    if (await isDomainTaken(body.domain)) {
-      throw Object.assign(new Error('Domain already taken'), { status: 409 });
-    }
-  })
-  .handler(async ({ body, wallet }) => {
-    return registerDomain(body.domain, wallet);
-  });
-
-// Rate limiting before payment
-router
-  .route('api/expensive')
-  .paid('1.00')
-  .body(RequestSchema)
-  .validate(async (body) => {
-    const usage = await getUserUsage(body.userId);
-    if (usage >= DAILY_LIMIT) {
-      throw Object.assign(new Error('Daily limit reached'), { status: 429 });
-    }
-  })
-  .handler(async ({ body }) => { ... });
-```
-
-**Pipeline order:** `body parse → validate → 402 challenge → payment → handler`
-
-**Error handling:** Respects `.status` on thrown errors (default: 400). Use `Object.assign(new Error('msg'), { status: 409 })` for custom codes.
-
-**Works with all auth modes:** paid, siwx, apiKey, unprotected.
-
-## Critical Rules
-
-- **Error handling:** Respect `.status` on any thrown error, not just `HttpError`. The `Object.assign(new Error(), { status })` pattern is universal in Node.js.
-- **SIWX challenge:** Must return a proper x402v2 challenge with `PAYMENT-REQUIRED` header and JSON body containing `extensions['sign-in-with-x']` with `domain`, `uri`, `version`, `chainId`, `type`, `nonce`, `issuedAt`.
-- **Discovery:** `authMode !== 'unprotected'` determines well-known visibility, not the protocol list. SIWX routes return 402 challenges and must be discoverable.
-- **OpenAPI:** Merge paths for multi-method endpoints (GET + DELETE on same path). Never overwrite.
-- **Duplicate route keys:** Registry silently overwrites (last-write-wins) with a dev-only `console.warn`. This is intentional — Next.js module loading order is non-deterministic during `next build`, so discovery stubs and real handlers may register the same key in either order. Prior art: ElysiaJS uses the identical pattern. See stablestudio `.claude/13_route-registry-dedup.md` for full research.
-- **Dynamic pricing (v0.3.1+):** Early body parsing with `request.clone()` enables accurate dynamic pricing. `maxPrice` is optional and acts as a safety net (cap + fallback). Body is parsed before 402 challenge generation when pricing function exists. See `.claude/15_router-dynamic-pricing-solution.md` for full design and derisking.
-
-## Environment Variables
-
-### Base URL
-
-`baseUrl` is **required** in `RouterConfig`. No auto-detection, no fallbacks. The realm is load-bearing for payment matching (MPP memo indexing, 402 challenge realm), so it must be explicitly set.
-
-```typescript
-createRouter({
-  baseUrl: process.env.BASE_URL!,
-  // ...
-})
-```
-
-If `baseUrl` is missing, `createRouter` throws immediately — in dev and prod. This ensures devs discover the issue on first `pnpm dev` rather than deploying with a wrong realm.
-
-### CDP API Keys
-
-The router uses the default facilitator from `@coinbase/x402`, which requires CDP API keys in `process.env`:
-
-- `CDP_API_KEY_ID` — Coinbase Developer Platform API key ID
-- `CDP_API_KEY_SECRET` — CDP API key secret
-
-**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".
-
-### MPP Server Wallets: `operatorKey` and `feePayerKey`
-
-Two distinct roles, two distinct wallets:
-
-- **`mpp.operatorKey`** — signs server-side on-chain ops (channel close/settle). Required for sessions. Its derived address **must equal `recipient`/payee** because mppx's close handler asserts `sender === payee` on settle.
-- **`mpp.feePayerKey`** *(optional)* — sponsors gas for client-signed open/topUp txs. Omit to disable sponsorship; clients then pay their own gas.
-
-**The two MUST resolve to different addresses when both are set.** Tempo rejects fee-delegated txs where `sender === feePayer` with `-32000 "fee payer cannot resolve to sender"`. This bites the server-signed close/settle path. The router validates the addresses at `createRouter()` time and throws `mpp_operator_equals_fee_payer` if they collide — production `next build` fails fast; dev surfaces a logged error.
-
-### KV Store
-
-One KV cache backs all three persistent stores (SIWX nonce, SIWX entitlement, MPP tx-hash replay). Each consumer gets its own key prefix (`siwx:nonce:`, `siwx:ent:`, `mpp:`).
-
-Resolution order in `createRouter`:
-
-1. `kvStore: { url, token }` — build the REST client from those credentials.
-2. `kvStore: <KvStore>` — bring-your-own implementation (escape hatch for Cloudflare KV, ioredis, etc.).
-3. Omitted — auto-read `KV_REST_API_URL` + `KV_REST_API_TOKEN` from `process.env`.
-4. Env missing — fall back to in-memory stores (fine for local dev, unsafe in serverless production).
-
-```typescript
-createRouter({
-  kvStore: {
-    url: process.env.UPSTASH_REDIS_REST_URL!,
-    token: process.env.UPSTASH_REDIS_REST_TOKEN!,
-  },
-  // ...
-});
-```
-
-The only file that talks to Redis is `src/kv-store/client.ts`. It speaks the Upstash REST protocol with plain `fetch` (also what Vercel KV exposes). If you need a different backend, implement the `KvStore` interface and pass it as `kvStore`.
-
-### 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)
-
-**Example env schema (T3/`@t3-oss/env-nextjs`):**
-
-```typescript
-import { createEnv } from "@t3-oss/env-nextjs";
-import { z } from "zod";
-
-export const env = createEnv({
-  server: {
-    CDP_API_KEY_ID: z.string(),
-    CDP_API_KEY_SECRET: z.string(),
-    // ... other vars
-  },
-  runtimeEnv: {
-    CDP_API_KEY_ID: process.env.CDP_API_KEY_ID,
-    CDP_API_KEY_SECRET: process.env.CDP_API_KEY_SECRET,
-    // ... other vars
-  },
-});
-```
-
-**Alternative:** Pass a custom facilitator config to `createRouter()` if you want to use a different facilitator URL or auth mechanism. But for most apps, the default CDP facilitator is correct.
-
-## Version Stability
-
-The public API is **not stable**. Downstream consumers should pin exact versions (`"@agentcash/router": "0.2.0"`, not `"^0.2.0"`). Breaking changes will happen as we build out multi-protocol support and discover patterns across services. Semver will be respected once we hit 1.0.
-
-## Build & Test
-
-```bash
-pnpm build      # tsup
-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