@agentcash/router 0.3.0 → 0.3.1

package/README.md

@@ -141,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** - Calculate price based on request body:
+```typescript
+router.route('gen')
+  .paid((body) => calculateCost(body.imageSize, body.quality))
+  .body(imageGenSchema)
+  .handler(async ({ body }) => generate(body));
+```
 
-**Dynamic**: `router.route('gen').paid((body) => calculateCost(body), { maxPrice: '5.00' }).body(schema)`
+**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**:
+**Tiered** - Price based on a specific field value:
 ```typescript
 router.route('upload').paid({
   field: 'tier',
@@ -153,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) {

package/dist/index.d.cts

@@ -265,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

@@ -265,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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "0.3.0",
+  "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"
   }
-}
+}