@agentcash/router 0.3.0 → 0.4.0

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

@@ -120,7 +120,7 @@ var RouteRegistry = class {
 };
 
 // src/orchestrate.ts
-var import_server2 = require("next/server");
+var import_server3 = require("next/server");
 
 // src/plugin.ts
 function createDefaultContext(meta) {
@@ -354,70 +354,113 @@ async function settleX402Payment(server, payload, requirements) {
 }
 
 // src/protocols/mpp.ts
-var mpayLoaded = false;
-var Challenge;
-var Credential;
-var Receipt;
-var tempo;
-async function ensureMpay() {
-  if (mpayLoaded) return;
-  try {
-    const mpay = await import("mpay");
-    Challenge = mpay.Challenge;
-    Credential = mpay.Credential;
-    Receipt = mpay.Receipt;
-    const mpayServer = await import("mpay/server");
-    tempo = mpayServer.tempo;
-    mpayLoaded = true;
-  } catch {
-    throw new Error("mpay package is required for MPP protocol support. Install it: pnpm add mpay");
+var import_mpay = require("mpay");
+var import_server2 = require("mpay/server");
+var import_viem = require("viem");
+var import_chains = require("viem/chains");
+function buildGetClient(rpcUrl) {
+  const url = rpcUrl ?? process.env.TEMPO_RPC_URL;
+  if (!url) return {};
+  return {
+    getClient: () => (0, import_viem.createClient)({ chain: import_chains.tempo, transport: (0, import_viem.http)(url) })
+  };
+}
+function toStandardRequest(request) {
+  if (request.constructor.name === "Request") {
+    return 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"
+  });
 }
+var DEFAULT_DECIMALS = 6;
 async function buildMPPChallenge(routeEntry, request, mppConfig, price) {
-  await ensureMpay();
-  const methodIntent = tempo.charge({
-    amount: price,
-    currency: mppConfig.currency,
-    recipient: mppConfig.recipient ?? ""
+  const standardRequest = toStandardRequest(request);
+  const currency = mppConfig.currency;
+  const recipient = mppConfig.recipient ?? "";
+  const methodIntent = import_server2.tempo.charge({
+    currency,
+    recipient
   });
-  const challenge = Challenge.fromIntent(methodIntent, {
+  const challenge = import_mpay.Challenge.fromIntent(methodIntent, {
     secretKey: mppConfig.secretKey,
-    realm: new URL(request.url).origin,
-    request
+    realm: new URL(standardRequest.url).origin,
+    request: {
+      amount: price,
+      currency,
+      recipient,
+      decimals: DEFAULT_DECIMALS
+    }
   });
-  return Challenge.serialize(challenge);
+  return import_mpay.Challenge.serialize(challenge);
 }
 async function verifyMPPCredential(request, _routeEntry, mppConfig, price) {
-  await ensureMpay();
-  const credential = Credential.fromRequest(request);
-  if (!credential) return null;
-  const isValid = Challenge.verify(credential.challenge, { secretKey: mppConfig.secretKey });
-  if (!isValid) {
-    return { valid: false, payer: null };
-  }
-  const chargeConfig = {
-    amount: price,
-    currency: mppConfig.currency,
-    recipient: mppConfig.recipient ?? ""
-  };
-  const verifyResult = await tempo.charge(chargeConfig).verify(credential);
-  if (!verifyResult?.valid) {
-    return { valid: false, payer: null };
+  const standardRequest = toStandardRequest(request);
+  const currency = mppConfig.currency;
+  const recipient = mppConfig.recipient ?? "";
+  try {
+    const authHeader = standardRequest.headers.get("Authorization");
+    if (!authHeader) {
+      console.error("[MPP] No Authorization header found");
+      return null;
+    }
+    const credential = import_mpay.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 });
+    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 = {
+      amount: price,
+      currency,
+      recipient,
+      decimals: DEFAULT_DECIMALS
+    };
+    const resolvedRequest = methodIntent.request ? await methodIntent.request({ credential, request: paymentRequest }) : paymentRequest;
+    const receipt = await methodIntent.verify({
+      credential,
+      request: resolvedRequest
+    });
+    if (!receipt || receipt.status !== "success") {
+      console.error("[MPP] Tempo verification failed:", receipt);
+      return { valid: false, payer: null };
+    }
+    const payer = receipt.reference ?? "";
+    return {
+      valid: true,
+      payer,
+      txHash: receipt.reference
+    };
+  } catch (error) {
+    console.error("[MPP] Credential verification error:", {
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : void 0,
+      errorType: error?.constructor?.name
+    });
+    return null;
   }
-  return {
-    valid: true,
-    payer: verifyResult.payer
-  };
 }
-async function buildMPPReceipt(reference) {
-  await ensureMpay();
-  const receipt = Receipt.from({
+function buildMPPReceipt(reference) {
+  const receipt = import_mpay.Receipt.from({
     method: "tempo",
     status: "success",
     reference,
     timestamp: (/* @__PURE__ */ new Date()).toISOString()
   });
-  return Receipt.serialize(receipt);
+  return import_mpay.Receipt.serialize(receipt);
 }
 
 // src/auth/siwx.ts
@@ -495,7 +538,7 @@ function createRequestHandler(routeEntry, handler, deps) {
     firePluginResponse(deps, pluginCtx, meta, response);
   }
   function fail(status, message, meta, pluginCtx) {
-    const response = import_server2.NextResponse.json({ success: false, error: message }, { status });
+    const response = import_server3.NextResponse.json({ success: false, error: message }, { status });
     firePluginResponse(deps, pluginCtx, meta, response);
     return response;
   }
@@ -523,7 +566,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 +581,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);
@@ -585,7 +638,7 @@ function createRequestHandler(routeEntry, handler, deps) {
             route: routeEntry.key
           });
         }
-        const response = new import_server2.NextResponse(JSON.stringify(paymentRequired), {
+        const response = new import_server3.NextResponse(JSON.stringify(paymentRequired), {
           status: 402,
           headers: { "Content-Type": "application/json" }
         });
@@ -606,7 +659,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) {
@@ -717,7 +770,7 @@ async function parseBody(request, routeEntry) {
   if (result.success) return { ok: true, data: result.data };
   return {
     ok: false,
-    response: import_server2.NextResponse.json(
+    response: import_server3.NextResponse.json(
       { success: false, error: result.error, issues: result.issues },
       { status: 400 }
     )
@@ -744,10 +797,60 @@ function parseQuery(request, routeEntry) {
   const result = routeEntry.querySchema.safeParse(params);
   return result.success ? result.data : params;
 }
-async function build402(request, routeEntry, deps, meta, pluginCtx) {
-  const response = new import_server2.NextResponse(null, { status: 402 });
+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_server3.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_server3.NextResponse(null, {
+    status: 402,
+    headers: {
+      "Content-Type": "application/json"
+    }
+  });
   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 +1011,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) {
@@ -1035,7 +1135,7 @@ var MemoryNonceStore = class {
 };
 
 // src/discovery/well-known.ts
-var import_server3 = require("next/server");
+var import_server4 = require("next/server");
 function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
   let validated = false;
   return async (_request) => {
@@ -1073,7 +1173,7 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
     if (instructions) {
       body.instructions = instructions;
     }
-    return import_server3.NextResponse.json(body, {
+    return import_server4.NextResponse.json(body, {
       headers: {
         "Access-Control-Allow-Origin": "*",
         "Access-Control-Allow-Methods": "GET",
@@ -1084,12 +1184,12 @@ function createWellKnownHandler(registry, baseUrl, pricesKeys, options = {}) {
 }
 
 // src/discovery/openapi.ts
-var import_server4 = require("next/server");
+var import_server5 = require("next/server");
 function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
   let cached = null;
   let validated = false;
   return async (_request) => {
-    if (cached) return import_server4.NextResponse.json(cached);
+    if (cached) return import_server5.NextResponse.json(cached);
     if (!validated && pricesKeys) {
       registry.validate(pricesKeys);
       validated = true;
@@ -1116,7 +1216,7 @@ function createOpenAPIHandler(registry, baseUrl, pricesKeys, options) {
       tags: Array.from(tagSet).sort().map((name) => ({ name })),
       paths
     });
-    return import_server4.NextResponse.json(cached);
+    return import_server5.NextResponse.json(cached);
   };
 }
 function deriveTag(routeKey) {

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { ZodType } from 'zod';
+import { PaymentRequirements, PaymentRequired, SettleResponse } from '@x402/core/types';
 
 interface NonceStore {
     check(nonce: string): Promise<boolean>;
@@ -82,6 +83,7 @@ interface AlertEvent {
     meta?: Record<string, unknown>;
 }
 type AlertFn = (level: AlertLevel, message: string, meta?: Record<string, unknown>) => void;
+
 interface X402Server {
     initialize(): Promise<void>;
     buildPaymentRequirementsFromOptions(options: Array<{
@@ -91,18 +93,18 @@ interface X402Server {
         payTo: string;
     }>, context: {
         request: Request;
-    }): Promise<unknown[]>;
-    createPaymentRequiredResponse(requirements: unknown[], resource: {
+    }): Promise<PaymentRequirements[]>;
+    createPaymentRequiredResponse(requirements: PaymentRequirements[], resource: {
         url: string;
         method: string;
         description?: string;
-    }, error: string | null, extensions?: Record<string, unknown>): Promise<unknown>;
-    findMatchingRequirements(requirements: unknown[], payload: unknown): unknown;
-    verifyPayment(payload: unknown, requirements: unknown): Promise<{
+    }, error: string | null, extensions?: Record<string, unknown>): Promise<PaymentRequired>;
+    findMatchingRequirements(requirements: PaymentRequirements[], payload: unknown): PaymentRequirements;
+    verifyPayment(payload: unknown, requirements: PaymentRequirements): Promise<{
         isValid: boolean;
         payer?: string;
     }>;
-    settlePayment(payload: unknown, requirements: unknown): Promise<unknown>;
+    settlePayment(payload: unknown, requirements: PaymentRequirements): Promise<SettleResponse>;
 }
 type ProtocolType = 'x402' | 'mpp';
 type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
@@ -183,6 +185,8 @@ interface RouterConfig {
         secretKey: string;
         currency: string;
         recipient?: string;
+        /** Tempo RPC URL for on-chain verification. Falls back to TEMPO_RPC_URL env var. */
+        rpcUrl?: string;
     };
     /**
      * Payment protocols to accept on auto-priced routes (those using the `prices` config).
@@ -239,6 +243,7 @@ interface OrchestrateDeps {
         secretKey: string;
         currency: string;
         recipient?: string;
+        rpcUrl?: string;
     };
 }
 
@@ -265,7 +270,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

@@ -1,5 +1,6 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { ZodType } from 'zod';
+import { PaymentRequirements, PaymentRequired, SettleResponse } from '@x402/core/types';
 
 interface NonceStore {
     check(nonce: string): Promise<boolean>;
@@ -82,6 +83,7 @@ interface AlertEvent {
     meta?: Record<string, unknown>;
 }
 type AlertFn = (level: AlertLevel, message: string, meta?: Record<string, unknown>) => void;
+
 interface X402Server {
     initialize(): Promise<void>;
     buildPaymentRequirementsFromOptions(options: Array<{
@@ -91,18 +93,18 @@ interface X402Server {
         payTo: string;
     }>, context: {
         request: Request;
-    }): Promise<unknown[]>;
-    createPaymentRequiredResponse(requirements: unknown[], resource: {
+    }): Promise<PaymentRequirements[]>;
+    createPaymentRequiredResponse(requirements: PaymentRequirements[], resource: {
         url: string;
         method: string;
         description?: string;
-    }, error: string | null, extensions?: Record<string, unknown>): Promise<unknown>;
-    findMatchingRequirements(requirements: unknown[], payload: unknown): unknown;
-    verifyPayment(payload: unknown, requirements: unknown): Promise<{
+    }, error: string | null, extensions?: Record<string, unknown>): Promise<PaymentRequired>;
+    findMatchingRequirements(requirements: PaymentRequirements[], payload: unknown): PaymentRequirements;
+    verifyPayment(payload: unknown, requirements: PaymentRequirements): Promise<{
         isValid: boolean;
         payer?: string;
     }>;
-    settlePayment(payload: unknown, requirements: unknown): Promise<unknown>;
+    settlePayment(payload: unknown, requirements: PaymentRequirements): Promise<SettleResponse>;
 }
 type ProtocolType = 'x402' | 'mpp';
 type AuthMode = 'paid' | 'siwx' | 'apiKey' | 'unprotected';
@@ -183,6 +185,8 @@ interface RouterConfig {
         secretKey: string;
         currency: string;
         recipient?: string;
+        /** Tempo RPC URL for on-chain verification. Falls back to TEMPO_RPC_URL env var. */
+        rpcUrl?: string;
     };
     /**
      * Payment protocols to accept on auto-priced routes (those using the `prices` config).
@@ -239,6 +243,7 @@ interface OrchestrateDeps {
         secretKey: string;
         currency: string;
         recipient?: string;
+        rpcUrl?: string;
     };
 }
 
@@ -265,7 +270,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;