@agentcash/router 1.8.0 → 1.9.0

package/AGENTS.md

@@ -10,7 +10,7 @@ A protocol-agnostic route framework for Next.js App Router APIs. Provides x402 p
 
 1. Route definition is 3 to 6 lines.
 2. Single source of truth: the route registry drives discovery, OpenAPI, and pricing.
-3. Auth and pricing are orthogonal: `.paid()`, `.siwx()`, `.apiKey()`, `.unprotected()`.
+3. Pricing modes (`.paid()`, `.upTo()`, `.metered()`) and identity auth (`.siwx()`, `.apiKey()`) compose; `.unprotected()` opts out. Exactly one pricing mode per route.
 4. Observability is pluggable via `RouterPlugin`. No boilerplate.
 5. The package owns x402 and MPP server lifecycles (init, verify, settle).
 6. Compose, do not reimplement. Delegate to `@x402/*`, `@coinbase/x402`, and `mppx`.
@@ -20,36 +20,42 @@ A protocol-agnostic route framework for Next.js App Router APIs. Provides x402 p
 ```
 src/
   index.ts              public surface — createRouter / createRouterFromEnv
-  builder.ts            fluent RouteBuilder
+  builder.ts            fluent RouteBuilder (.paid / .upTo / .metered / .siwx / .apiKey / .unprotected)
   registry.ts           Map-backed route registry
   constants.ts          network ids, USDC asset/decimals, default facilitator
-  types.ts              core types (RouteEntry, HandlerContext, HttpError)
+  types.ts              core types (RouteEntry, HandlerContext, HttpError, PaidOptions, UpToOptions, MeteredOptions)
   plugin/               RouterPlugin types + lifecycle dispatch
-  init/                 protocol init (x402.ts, mpp.ts) + env reader (from-env.ts)
+  init/                 protocol init (x402.ts, x402-server.ts, mpp.ts, mppx.ts)
   protocols/            x402/ and mpp/ strategies, detect.ts, accepts
   auth/                 siwx.ts, api-key.ts, normalize-wallet.ts
   kv-store/             one KvStore backs siwx nonce, siwx entitlement, mpp replay
-  pricing/              fixed, tiered, dynamic, atomic conversion
-  pipeline/             flows (paid, siwx-only, api-key-only, unprotected)
+  pricing/              fixed, tiered, dynamic (args-derived), upto-charge, metered-charge, format (atomic conversion)
+  pipeline/             orchestrate.ts + steps/ + flows/ (paid → static-paid | dynamic-paid; siwx-only, api-key-only, unprotected)
   discovery/            well-known, openapi, llms-txt
-  config/               RouterConfig validation, RouterConfigError, issue codes
+  config/               RouterConfig + env schema (single source of truth), RouterConfigError, issue codes
 ```
 
 ## Pipeline
 
 `auth check -> body parse -> validate -> 402 challenge -> payment verify -> handler -> settle -> finalize`
 
+## Naming
+
+Constructor-style functions use `build<Noun>` — one verb, one domain noun. Name them after the domain concept, never after an HTTP status code or transport detail (the function that builds a payment challenge is `buildChallengeResponse`, not `build402`). The challenge family shares the `Challenge` backbone: `buildChallengeResponse`, `buildChallengeExtensions`, `buildSiwxChallenge`, `buildSessionChallenge`, `buildX402Challenge`.
+
 ## Critical rules
 
 - **Error handling.** Respect `.status` on any thrown error, not just `HttpError`. Pattern: `throw Object.assign(new Error('msg'), { status: 409 })`.
-- **SIWX challenge.** Must return an x402v2 challenge with `PAYMENT-REQUIRED` header and a JSON body whose `extensions['sign-in-with-x']` has `domain`, `uri`, `version`, `chainId`, `type`, `nonce`, `issuedAt`.
-- **Discovery visibility.** `authMode !== 'unprotected'` determines well-known visibility, not the protocol list. SIWX routes are discoverable.
+- **SIWX challenge.** Must return an x402v2 challenge with a `PAYMENT-REQUIRED` header and a JSON body whose `extensions['sign-in-with-x']` carries `info` (an object with `domain`, `uri`, `version`, `chainId`, `type`, `nonce`, `issuedAt`, `expirationTime`, `statement`), `supportedChains`, and an optional `schema`. The header-encoded challenge and the JSON body must stay identical.
+- **Discovery visibility.** `authMode !== 'unprotected'` determines well-known visibility, not the protocol list. SIWX routes are discoverable. All three pricing modes set `authMode = 'paid'`; the `billing` field (`'exact' | 'upto' | 'metered'`) distinguishes them downstream.
 - **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 load order is non-deterministic, so stub + real handler may register either order.
-- **Args-driven pricing.** Body is parsed before the 402 challenge via `request.clone()` when pricing is a function. `maxPrice` is optional and acts as a cap and a fallback on pricing function errors.
+- **Args-derived pricing.** Body is parsed before the 402 challenge via `request.clone()` when `.paid(fn)` is used. `maxPrice` is optional: it caps the computed amount and acts as a fallback on non-`HttpError` exceptions; `HttpError` is always rethrown so a pricing function can reject the request with its intended status before any payment is taken.
+- **`.upTo()` is x402-only.** Builder throws if `protocols` overrides it to anything else. Requires an `'upto'` accept on at least one configured x402 network — `createRouterFromEnv` auto-adds one on Base; programmatic `createRouter` users must add `{ scheme: 'upto', network, asset }` to `x402.accepts` themselves.
+- **`.metered()` is MPP-only.** Builder throws if `protocols` overrides it to anything else. Requires `RouterConfig.mpp.session` and `mpp.operatorKey`. `createRouterFromEnv` enables both automatically when `MPP_OPERATOR_KEY` is set.
 - **MPP operator vs fee-payer.** `mpp.operatorKey` and `mpp.feePayerKey` MUST resolve to different addresses. Tempo rejects fee-delegated txs where `sender === feePayer`. `createRouter` validates this at construction and throws `mpp_operator_equals_fee_payer`.
 - **MPP operator address.** Must equal `recipient` / payee. mppx's close handler asserts `sender === payee` on settle.
-- **Streaming requires MPP.** `.stream()` only works on MPP. x402 has no streaming primitive.
+- **Streaming requires `.metered()`.** `.stream()` on a `.paid()` / `.upTo()` / `.unprotected()` route throws at registration. x402 has no streaming primitive, so `.stream()` is MPP-only by construction.
 
 ## Two entry points
 

package/README.md

@@ -24,7 +24,7 @@
 
 ```bash
 pnpm add @agentcash/router
-pnpm add next zod @x402/core @x402/evm @x402/extensions @coinbase/x402 zod-openapi # peer dependencies
+pnpm add next zod @x402/core @x402/evm @x402/extensions @x402/svm @coinbase/x402 zod-openapi # peer dependencies
 pnpm add mppx  # optional, for MPP support
 ```
 
@@ -37,13 +37,13 @@ The recommended entry point reads its config from `process.env`. A copy-paste `.
 | Var | Required | Purpose |
 |-----|----------|---------|
 | `EVM_PAYEE_ADDRESS` | yes | EVM address that receives x402 and MPP payments (`0x…`, 20 bytes). Canonicalized to lowercase. The zero address is rejected. |
-| `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET` | yes (production) | Coinbase Developer Platform credentials for the default EVM facilitator. T3 / `@t3-oss/env-nextjs` users must declare these in their env schema. |
+| `CDP_API_KEY_ID`, `CDP_API_KEY_SECRET` | yes (EVM) | Coinbase Developer Platform credentials for the default EVM facilitator. Create an API key at https://portal.cdp.coinbase.com. T3 / `@t3-oss/env-nextjs` users must declare these in their env schema. |
 
 ### Solana
 
 | Var | Required | Purpose |
 |-----|----------|---------|
-| `SOLANA_PAYEE_ADDRESS` | no | When set, adds a Solana `exact` accept so the router takes Solana payments. **Dynamic pricing (`upto`) is Base-only** — Solana clients can only pay static-priced routes. |
+| `SOLANA_PAYEE_ADDRESS` | no | When set, adds a Solana `exact` accept so the router takes Solana payments. **`.upTo()` is Base-only and `.metered()` is MPP-only**. Solana clients can only pay static-priced `.paid()` routes. |
 | `SOLANA_FACILITATOR_URL` | no | Override the Solana x402 facilitator. Defaults to `DEFAULT_SOLANA_FACILITATOR_URL`. |
 
 ### MPP (auto-enabled when `MPP_SECRET_KEY` is set)
@@ -53,14 +53,14 @@ The recommended entry point reads its config from `process.env`. A copy-paste `.
 | `MPP_SECRET_KEY` | when MPP is enabled | Server-side MPP secret. Presence toggles MPP on. |
 | `MPP_CURRENCY` | when MPP is enabled | Tempo currency address. Use `TEMPO_USDC_ADDRESS` for Tempo USDC. |
 | `TEMPO_RPC_URL` | when MPP is enabled | Authenticated Tempo JSON-RPC endpoint. Public `rpc.tempo.xyz` returns 401. |
-| `MPP_OPERATOR_KEY` | no | Signs server-side close/settle. When set, MPP session mode is enabled automatically (required for streaming + `.paid({ dynamic: true })` on MPP). Address must equal the payee. |
+| `MPP_OPERATOR_KEY` | no | Signs server-side close/settle. When set, MPP session mode is enabled automatically (required for `.metered()`: both streaming and request-mode per-tick billing). Address must equal the payee. |
 | `MPP_FEE_PAYER_KEY` | no | Sponsors client gas for channel open/topUp. Must resolve to a different address than `MPP_OPERATOR_KEY` (Tempo rejects fee-delegated txs where `sender === feePayer`). |
 
 ### Other
 
 | Var | Required | Purpose |
 |-----|----------|---------|
-| `BASE_URL` | yes | Origin URL (`https://api.example.com`). Load-bearing — used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Must match the public domain. |
+| `BASE_URL` | yes | Origin URL (`https://api.example.com`). Load-bearing: used as the 402 realm, OpenAPI server URL, and MPP memo prefix. Must match the public domain. |
 | `KV_REST_API_URL`, `KV_REST_API_TOKEN` | no | Upstash / Vercel KV. Backs SIWX nonce, SIWX entitlement, and MPP replay. In-memory fallback is unsafe in serverless production. Providing a Kv Store is highly recommended. |
 
 ## Quick start
@@ -69,7 +69,7 @@ The recommended entry point reads its config from `process.env`. A copy-paste `.
 
 There are two ways to initialize. Pick one.
 
-**Option A — `createRouterFromEnv` (recommended).** Reads `process.env`, validates every value up front, and throws a single `RouterConfigError` with every problem at once. Auto-enables MPP when `MPP_SECRET_KEY` is set, auto-adds a Solana accept when `SOLANA_PAYEE_ADDRESS` is set, auto-enables MPP session mode when `MPP_OPERATOR_KEY` is set.
+**Option A: `createRouterFromEnv` (recommended).** Reads `process.env`, validates every value up front, and throws a single `RouterConfigError` with every problem at once. Auto-enables MPP when `MPP_SECRET_KEY` is set, auto-adds a Solana accept when `SOLANA_PAYEE_ADDRESS` is set, auto-enables MPP session mode when `MPP_OPERATOR_KEY` is set.
 
 ```typescript
 // lib/router.ts
@@ -82,7 +82,7 @@ export const router = createRouterFromEnv({
 });
 ```
 
-**Option B — build a `RouterConfig` and pass it to `createRouter`.** Use this when you need custom networks, multiple payees, non-standard assets, or any setting `createRouterFromEnv` doesn't expose. `createRouter` runs the same validation against the `RouterConfig` shape.
+**Option B: build a `RouterConfig` and pass it to `createRouter`.** Use this when you need custom networks, multiple payees, non-standard assets, or any setting `createRouterFromEnv` doesn't expose. `createRouter` runs the same validation against the `RouterConfig` shape.
 
 ```typescript
 // lib/router.ts
@@ -139,7 +139,7 @@ import '@/lib/routes-barrel';  // imports every route module so the registry is
 export const GET = router.openapi();
 ```
 
-The barrel forces every route module to load before the discovery handler walks the registry — Next.js otherwise lazy-loads route files on first hit, and unloaded routes don't appear in the spec.
+The barrel forces every route module to load before the discovery handler walks the registry. Next.js otherwise lazy-loads route files on first hit, and unloaded routes don't appear in the spec.
 
 The `openapi.json` should be hosted at `GET <origin>/openapi.json`. 
 
@@ -147,9 +147,11 @@ The `openapi.json` should be hosted at `GET <origin>/openapi.json`.
 
 | Method | Purpose |
 |--------|---------|
-| `.paid(price)` | Payment required (x402, MPP, or both). |
+| `.paid(price)` | Fixed, args-derived, or tiered payment up front (x402, MPP, or both). |
+| `.upTo(maxPrice)` | Handler-computed billing; handler calls `charge(amount)` and the request settles once for the running total. **x402 only.** |
+| `.metered({ tickCost, maxPrice })` | Per-tick billing over an MPP payment channel. `.handler()` bills exactly `tickCost`; `.stream()` calls `charge()` per yield. **MPP only.** Streaming requires this. |
 | `.siwx()` | Wallet identity, no payment. Returns 402 with a SIWX challenge. |
-| `.apiKey(resolver)` | `X-API-Key` or `Authorization: Bearer <key>`. Composes with `.paid()`. |
+| `.apiKey(resolver)` | `X-API-Key` or `Authorization: Bearer <key>`. Composes with `.paid()` / `.upTo()` / `.metered()`. |
 | `.unprotected()` | No auth. |
 
 ```typescript
@@ -164,18 +166,22 @@ router.route({ path: 'gated' })
 
 ## Pricing
 
+`.paid()`, `.upTo()`, and `.metered()` are mutually exclusive pricing modes: pick one per route.
+
+### `.paid()`: fixed, args-derived, or tiered
+
 **Static.**
 ```typescript
 .paid('0.02')
 ```
 
-**Args-driven.**
+**Args-derived.** Compute the price from the parsed body. Throw `HttpError` to reject before the 402 challenge.
 ```typescript
 .paid((body) => calculateCost(body), { maxPrice: '5.00' })
 .body(genSchema)
 ```
 
-`maxPrice` caps the computed amount and acts as a fallback if the pricing function throws. Without `maxPrice`, the route trusts your function fully (no cap, no fallback) and returns 500 on errors.
+`maxPrice` caps the computed amount and acts as a fallback on non-`HttpError` exceptions thrown by the pricing function (`HttpError` is always rethrown). Without `maxPrice`, the route trusts your function fully (no cap, no fallback) and returns 500 on errors.
 
 **Tiered.**
 ```typescript
@@ -189,15 +195,34 @@ router.route({ path: 'gated' })
 .body(uploadSchema)
 ```
 
-**Handler-driven (request-mode).** Bills exactly `tickCost` per request:
+### `.upTo()`: handler-computed, x402 only
+
+Handler calls `charge(amount)` one or more times; the request settles once for the accumulated total, capped at `maxPrice`. Requires an `'upto'` accept on at least one configured x402 network (`createRouterFromEnv` auto-adds one on Base).
+
+```typescript
+.upTo('0.05')
+.body(schema)
+.handler(async ({ body, charge }) => {
+  await charge('0.001');
+  // ... more work ...
+  await charge('0.002');
+  return result;
+});
+```
+
+### `.metered()`: per-tick, MPP only
+
+Per-tick billing over an MPP payment channel. Requires `MPP_OPERATOR_KEY` (`createRouterFromEnv` auto-enables session mode when it's set).
+
+**Request-mode.** `.handler()` bills exactly `tickCost` on each request:
 ```typescript
-.paid({ dynamic: true, tickCost: '0.01', unitType: 'request', maxPrice: '0.01' })
+.metered({ tickCost: '0.01', maxPrice: '0.05', unitType: 'request' })
 .handler(async ({ body }) => { ... });
 ```
 
-**Streaming (MPP only).** One `charge()` call bills one tick:
+**Streaming.** Each `charge()` call bills one tick, up to `maxPrice`:
 ```typescript
-.paid({ dynamic: true, tickCost: '0.0001', unitType: 'token', maxPrice: '0.05', protocols: ['mpp'] })
+.metered({ tickCost: '0.0001', maxPrice: '0.05', unitType: 'token' })
 .stream(async function* ({ body, charge }) {
   for await (const token of streamLLM(body.prompt)) {
     await charge();
@@ -206,6 +231,8 @@ router.route({ path: 'gated' })
 });
 ```
 
+Streaming is MPP-only. `.stream()` on a `.paid()` / `.upTo()` / `.unprotected()` route throws at registration.
+
 ## Pre-payment validation
 
 For checks that need a DB lookup before quoting a price:
@@ -248,3 +275,21 @@ export const router = createRouterFromEnv({
 
 All hooks are optional and fire-and-forget; they never delay the response. Use hooks to add additional telemetry or flexibility to your resource's lifecycle.
 
+### Debugging with `onAlert`
+
+The router reports internal warnings and errors (failed payment verification, simulation failures, misconfiguration) through `onAlert`: with no plugin registered these messages are silently dropped, so wiring up a logging plugin is the fastest way to see why a request failed. Forward `onAlert` (and `onError`) to your logs:
+
+```typescript
+const loggingPlugin: RouterPlugin = {
+  onAlert(_ctx, alert) {
+    (alert.level === 'error' ? console.error : console.warn)(
+      `[router:${alert.route}] ${alert.message}`,
+      alert.meta ?? '',
+    );
+  },
+  onError(_ctx, error) {
+    console.error(`[router] ${error.status} ${error.message} (settled=${error.settled})`);
+  },
+};
+```
+