@agentcash/router 0.2.2 → 0.3.1

package/README.md

@@ -18,6 +18,36 @@ pnpm add next zod @x402/core @x402/evm @x402/extensions @coinbase/x402 zod-opena
 pnpm add mpay
 ```
 
+## Environment Setup
+
+The router uses the default facilitator from `@coinbase/x402` for x402 payments, which requires CDP API keys:
+
+```bash
+CDP_API_KEY_ID=your-key-id
+CDP_API_KEY_SECRET=your-key-secret
+```
+
+**For Next.js apps with env validation** (T3 stack, `@t3-oss/env-nextjs`): Add these to your env schema — Next.js doesn't expose undeclared env vars to `process.env`.
+
+```typescript
+// src/env.js
+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(),
+  },
+  runtimeEnv: {
+    CDP_API_KEY_ID: process.env.CDP_API_KEY_ID,
+    CDP_API_KEY_SECRET: process.env.CDP_API_KEY_SECRET,
+  },
+});
+```
+
+Without these keys, x402 routes will fail to initialize (empty 402 responses, no payment header).
+
 ## Quick Start
 
 ### 1. Create the router (once per service)
@@ -111,11 +141,28 @@ The fluent builder ensures compile-time safety:
 
 ### Pricing Modes
 
-**Static**: `router.route('search').paid('0.02')`
+**Static** - Fixed price for all requests:
+```typescript
+router.route('search').paid('0.02')
+```
 
-**Dynamic**: `router.route('gen').paid((body) => calculateCost(body), { maxPrice: '5.00' }).body(schema)`
+**Dynamic** - Calculate price based on request body:
+```typescript
+router.route('gen')
+  .paid((body) => calculateCost(body.imageSize, body.quality))
+  .body(imageGenSchema)
+  .handler(async ({ body }) => generate(body));
+```
 
-**Tiered**:
+**Dynamic with safety net** - Cap at maxPrice if calculation exceeds, fallback to maxPrice on errors:
+```typescript
+router.route('compute')
+  .paid((body) => calculateExpensiveOperation(body), { maxPrice: '10.00' })
+  .body(computeSchema)
+  .handler(async ({ body }) => compute(body));
+```
+
+**Tiered** - Price based on a specific field value:
 ```typescript
 router.route('upload').paid({
   field: 'tier',
@@ -123,7 +170,38 @@ router.route('upload').paid({
     '10mb': { price: '0.02', label: '10 MB' },
     '100mb': { price: '0.20', label: '100 MB' },
   },
-}).body(schema)
+}).body(uploadSchema)
+```
+
+#### maxPrice Semantics (v0.3.1+)
+
+`maxPrice` is **optional** for dynamic pricing and acts as a safety net:
+
+1. **Capping**: If `calculateCost(body)` returns `"15.00"` but `maxPrice: "10.00"`, the client is charged `$10.00` (capped) and a warning alert fires.
+
+2. **Fallback**: If `calculateCost(body)` throws an error and `maxPrice` is set, the route falls back to `maxPrice` (degraded mode) and an alert fires. Without `maxPrice`, the route returns 500.
+
+3. **Trust mode**: No `maxPrice` means full trust in your pricing function (no cap, no fallback).
+
+**Best practices:**
+- ✅ Always set `maxPrice` for production routes (safety net)
+- ✅ Use `maxPrice` for routes with external dependencies (pricing APIs)
+- ✅ Monitor alerts for capping events (indicates pricing bug)
+- ⚠️ Skip `maxPrice` only for well-tested, unbounded pricing (e.g., per-GB storage)
+
+**Example with safety net:**
+```typescript
+router.route('ai-gen')
+  .paid(async (body) => {
+    // External pricing API (can fail)
+    const res = await fetch('https://pricing.example.com/calculate', {
+      method: 'POST',
+      body: JSON.stringify(body),
+    });
+    return res.json().price;
+  }, { maxPrice: '5.00' })  // Fallback if API is down
+  .body(genSchema)
+  .handler(async ({ body }) => generate(body));
 ```
 
 ### Dual Protocol (x402 + MPP)

package/dist/index.cjs

@@ -523,7 +523,7 @@ function createRequestHandler(routeEntry, handler, deps) {
     if (routeEntry.authMode === "unprotected") {
       return handleAuth(null, void 0);
     }
-    let account = void 0;
+    let account;
     if (routeEntry.authMode === "apiKey" || routeEntry.apiKeyResolver) {
       if (!routeEntry.apiKeyResolver) {
         return fail(401, "API key resolver not configured", meta, pluginCtx);
@@ -538,6 +538,16 @@ function createRequestHandler(routeEntry, handler, deps) {
       }
     }
     const protocol = detectProtocol(request);
+    let earlyBodyData;
+    if (!protocol && typeof routeEntry.pricing === "function" && routeEntry.bodySchema) {
+      const requestForPricing = request.clone();
+      const earlyBodyResult = await parseBody(requestForPricing, routeEntry);
+      if (!earlyBodyResult.ok) {
+        firePluginResponse(deps, pluginCtx, meta, earlyBodyResult.response);
+        return earlyBodyResult.response;
+      }
+      earlyBodyData = earlyBodyResult.data;
+    }
     if (routeEntry.authMode === "siwx") {
       if (!request.headers.get("SIGN-IN-WITH-X")) {
         const url = new URL(request.url);
@@ -606,7 +616,7 @@ function createRequestHandler(routeEntry, handler, deps) {
       return handleAuth(siwx.wallet, void 0);
     }
     if (!protocol || protocol === "siwx") {
-      return await build402(request, routeEntry, deps, meta, pluginCtx);
+      return await build402(request, routeEntry, deps, meta, pluginCtx, earlyBodyData);
     }
     const body = await parseBody(request, routeEntry);
     if (!body.ok) {
@@ -744,10 +754,55 @@ function parseQuery(request, routeEntry) {
   const result = routeEntry.querySchema.safeParse(params);
   return result.success ? result.data : params;
 }
-async function build402(request, routeEntry, deps, meta, pluginCtx) {
+async function resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta) {
+  try {
+    let price = await resolvePrice(routeEntry.pricing, bodyData);
+    if (routeEntry.maxPrice) {
+      const calculated = parseFloat(price);
+      const max = parseFloat(routeEntry.maxPrice);
+      if (calculated > max) {
+        firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+          level: "warn",
+          message: `Price ${price} exceeds maxPrice ${routeEntry.maxPrice}, capping`,
+          route: routeEntry.key,
+          meta: { calculated: price, maxPrice: routeEntry.maxPrice, body: bodyData }
+        });
+        price = routeEntry.maxPrice;
+      }
+    }
+    return { price };
+  } catch (err) {
+    firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+      level: "error",
+      message: `Pricing function failed: ${err instanceof Error ? err.message : String(err)}`,
+      route: routeEntry.key,
+      meta: { error: err instanceof Error ? err.stack : String(err), body: bodyData }
+    });
+    if (routeEntry.maxPrice) {
+      firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+        level: "warn",
+        message: `Using maxPrice ${routeEntry.maxPrice} as fallback after pricing error`,
+        route: routeEntry.key
+      });
+      return { price: routeEntry.maxPrice };
+    } else {
+      const errorResponse = import_server2.NextResponse.json(
+        { success: false, error: "Price calculation failed" },
+        { status: 500 }
+      );
+      firePluginResponse(deps, pluginCtx, meta, errorResponse);
+      return { error: errorResponse };
+    }
+  }
+}
+async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
   const response = new import_server2.NextResponse(null, { status: 402 });
   let challengePrice;
-  if (routeEntry.maxPrice) {
+  if (bodyData !== void 0 && typeof routeEntry.pricing === "function") {
+    const result = await resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta);
+    if ("error" in result) return result.error;
+    challengePrice = result.price;
+  } else if (routeEntry.maxPrice) {
     challengePrice = routeEntry.maxPrice;
   } else if (routeEntry.pricing) {
     try {
@@ -908,9 +963,6 @@ var RouteBuilder = class {
     next._pricing = pricing;
     if (options?.protocols) next._protocols = options.protocols;
     if (options?.maxPrice) next._maxPrice = options.maxPrice;
-    if (typeof pricing === "function" && !options?.maxPrice) {
-      throw new Error(`route '${this._key}': dynamic pricing requires maxPrice option`);
-    }
     if (typeof pricing === "object" && "tiers" in pricing) {
       for (const [tierKey, tierConfig] of Object.entries(pricing.tiers)) {
         if (!tierKey) {
@@ -1178,6 +1230,23 @@ function createRouter(config) {
   const nonceStore = config.siwx?.nonceStore ?? new MemoryNonceStore();
   const network = config.network ?? "eip155:8453";
   const baseUrl = typeof globalThis.process !== "undefined" ? process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000" : "http://localhost:3000";
+  if (config.protocols) {
+    if (config.protocols.length === 0) {
+      throw new Error(
+        "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
+      );
+    }
+    if (config.protocols.includes("mpp") && !config.mpp) {
+      throw new Error(
+        'RouterConfig.protocols includes "mpp" but RouterConfig.mpp is not configured. Add mpp: { secretKey, currency, recipient } to your router config.'
+      );
+    }
+    if (config.protocols.includes("x402") && !config.payeeAddress) {
+      throw new Error(
+        'RouterConfig.protocols includes "x402" but RouterConfig.payeeAddress is not configured.'
+      );
+    }
+  }
   if (config.plugin?.init) {
     try {
       const result = config.plugin.init({ origin: baseUrl });
@@ -1213,7 +1282,8 @@ function createRouter(config) {
     route(key) {
       const builder = new RouteBuilder(key, registry, deps);
       if (config.prices && key in config.prices) {
-        return builder.paid(config.prices[key]);
+        const options = config.protocols ? { protocols: config.protocols } : void 0;
+        return builder.paid(config.prices[key], options);
       }
       return builder;
     },

package/dist/index.d.cts

@@ -184,6 +184,20 @@ interface RouterConfig {
         currency: string;
         recipient?: string;
     };
+    /**
+     * Payment protocols to accept on auto-priced routes (those using the `prices` config).
+     *
+     * @default ['x402']
+     *
+     * @example
+     * // Accept both x402 and MPP payments
+     * createRouter({
+     *   protocols: ['x402', 'mpp'],
+     *   mpp: { secretKey, currency, recipient },
+     *   prices: { 'exa/search': '0.01' }
+     * })
+     */
+    protocols?: ProtocolType[];
 }
 
 declare class RouteRegistry {
@@ -251,7 +265,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     private fork;
     paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     paid<TBodyIn>(pricing: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions & {
-        maxPrice: string;
+        maxPrice?: string;
     }): RouteBuilder<TBody, TQuery, True, True, HasBody>;
     paid(pricing: {
         field: string;

package/dist/index.d.ts

@@ -184,6 +184,20 @@ interface RouterConfig {
         currency: string;
         recipient?: string;
     };
+    /**
+     * Payment protocols to accept on auto-priced routes (those using the `prices` config).
+     *
+     * @default ['x402']
+     *
+     * @example
+     * // Accept both x402 and MPP payments
+     * createRouter({
+     *   protocols: ['x402', 'mpp'],
+     *   mpp: { secretKey, currency, recipient },
+     *   prices: { 'exa/search': '0.01' }
+     * })
+     */
+    protocols?: ProtocolType[];
 }
 
 declare class RouteRegistry {
@@ -251,7 +265,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, HasAuth extend
     private fork;
     paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, True, False, HasBody>;
     paid<TBodyIn>(pricing: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions & {
-        maxPrice: string;
+        maxPrice?: string;
     }): RouteBuilder<TBody, TQuery, True, True, HasBody>;
     paid(pricing: {
         field: string;

package/dist/index.js

@@ -489,7 +489,7 @@ function createRequestHandler(routeEntry, handler, deps) {
     if (routeEntry.authMode === "unprotected") {
       return handleAuth(null, void 0);
     }
-    let account = void 0;
+    let account;
     if (routeEntry.authMode === "apiKey" || routeEntry.apiKeyResolver) {
       if (!routeEntry.apiKeyResolver) {
         return fail(401, "API key resolver not configured", meta, pluginCtx);
@@ -504,6 +504,16 @@ function createRequestHandler(routeEntry, handler, deps) {
       }
     }
     const protocol = detectProtocol(request);
+    let earlyBodyData;
+    if (!protocol && typeof routeEntry.pricing === "function" && routeEntry.bodySchema) {
+      const requestForPricing = request.clone();
+      const earlyBodyResult = await parseBody(requestForPricing, routeEntry);
+      if (!earlyBodyResult.ok) {
+        firePluginResponse(deps, pluginCtx, meta, earlyBodyResult.response);
+        return earlyBodyResult.response;
+      }
+      earlyBodyData = earlyBodyResult.data;
+    }
     if (routeEntry.authMode === "siwx") {
       if (!request.headers.get("SIGN-IN-WITH-X")) {
         const url = new URL(request.url);
@@ -572,7 +582,7 @@ function createRequestHandler(routeEntry, handler, deps) {
       return handleAuth(siwx.wallet, void 0);
     }
     if (!protocol || protocol === "siwx") {
-      return await build402(request, routeEntry, deps, meta, pluginCtx);
+      return await build402(request, routeEntry, deps, meta, pluginCtx, earlyBodyData);
     }
     const body = await parseBody(request, routeEntry);
     if (!body.ok) {
@@ -710,10 +720,55 @@ function parseQuery(request, routeEntry) {
   const result = routeEntry.querySchema.safeParse(params);
   return result.success ? result.data : params;
 }
-async function build402(request, routeEntry, deps, meta, pluginCtx) {
+async function resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta) {
+  try {
+    let price = await resolvePrice(routeEntry.pricing, bodyData);
+    if (routeEntry.maxPrice) {
+      const calculated = parseFloat(price);
+      const max = parseFloat(routeEntry.maxPrice);
+      if (calculated > max) {
+        firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+          level: "warn",
+          message: `Price ${price} exceeds maxPrice ${routeEntry.maxPrice}, capping`,
+          route: routeEntry.key,
+          meta: { calculated: price, maxPrice: routeEntry.maxPrice, body: bodyData }
+        });
+        price = routeEntry.maxPrice;
+      }
+    }
+    return { price };
+  } catch (err) {
+    firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+      level: "error",
+      message: `Pricing function failed: ${err instanceof Error ? err.message : String(err)}`,
+      route: routeEntry.key,
+      meta: { error: err instanceof Error ? err.stack : String(err), body: bodyData }
+    });
+    if (routeEntry.maxPrice) {
+      firePluginHook(deps.plugin, "onAlert", pluginCtx, {
+        level: "warn",
+        message: `Using maxPrice ${routeEntry.maxPrice} as fallback after pricing error`,
+        route: routeEntry.key
+      });
+      return { price: routeEntry.maxPrice };
+    } else {
+      const errorResponse = NextResponse2.json(
+        { success: false, error: "Price calculation failed" },
+        { status: 500 }
+      );
+      firePluginResponse(deps, pluginCtx, meta, errorResponse);
+      return { error: errorResponse };
+    }
+  }
+}
+async function build402(request, routeEntry, deps, meta, pluginCtx, bodyData) {
   const response = new NextResponse2(null, { status: 402 });
   let challengePrice;
-  if (routeEntry.maxPrice) {
+  if (bodyData !== void 0 && typeof routeEntry.pricing === "function") {
+    const result = await resolveDynamicPrice(bodyData, routeEntry, deps, pluginCtx, meta);
+    if ("error" in result) return result.error;
+    challengePrice = result.price;
+  } else if (routeEntry.maxPrice) {
     challengePrice = routeEntry.maxPrice;
   } else if (routeEntry.pricing) {
     try {
@@ -874,9 +929,6 @@ var RouteBuilder = class {
     next._pricing = pricing;
     if (options?.protocols) next._protocols = options.protocols;
     if (options?.maxPrice) next._maxPrice = options.maxPrice;
-    if (typeof pricing === "function" && !options?.maxPrice) {
-      throw new Error(`route '${this._key}': dynamic pricing requires maxPrice option`);
-    }
     if (typeof pricing === "object" && "tiers" in pricing) {
       for (const [tierKey, tierConfig] of Object.entries(pricing.tiers)) {
         if (!tierKey) {
@@ -1144,6 +1196,23 @@ function createRouter(config) {
   const nonceStore = config.siwx?.nonceStore ?? new MemoryNonceStore();
   const network = config.network ?? "eip155:8453";
   const baseUrl = typeof globalThis.process !== "undefined" ? process.env.NEXT_PUBLIC_BASE_URL ?? "http://localhost:3000" : "http://localhost:3000";
+  if (config.protocols) {
+    if (config.protocols.length === 0) {
+      throw new Error(
+        "RouterConfig.protocols cannot be empty. Omit the field to use default ['x402'] or specify protocols explicitly."
+      );
+    }
+    if (config.protocols.includes("mpp") && !config.mpp) {
+      throw new Error(
+        'RouterConfig.protocols includes "mpp" but RouterConfig.mpp is not configured. Add mpp: { secretKey, currency, recipient } to your router config.'
+      );
+    }
+    if (config.protocols.includes("x402") && !config.payeeAddress) {
+      throw new Error(
+        'RouterConfig.protocols includes "x402" but RouterConfig.payeeAddress is not configured.'
+      );
+    }
+  }
   if (config.plugin?.init) {
     try {
       const result = config.plugin.init({ origin: baseUrl });
@@ -1179,7 +1248,8 @@ function createRouter(config) {
     route(key) {
       const builder = new RouteBuilder(key, registry, deps);
       if (config.prices && key in config.prices) {
-        return builder.paid(config.prices[key]);
+        const options = config.protocols ? { protocols: config.protocols } : void 0;
+        return builder.paid(config.prices[key], options);
       }
       return builder;
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {
@@ -21,17 +21,6 @@
   "files": [
     "dist"
   ],
-  "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",
@@ -66,10 +55,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"
   }
-}
+}