@agentcash/router 1.10.5 → 1.10.6

package/README.md

@@ -150,6 +150,21 @@ The barrel forces every route module to load before the discovery handler walks
 
 The `openapi.json` should be hosted at `GET <origin>/openapi.json`. 
 
+### 4. Unmatched route fallback
+
+```typescript
+// app/api/[[...path]]/route.ts
+import { router } from '@/lib/router';
+
+export const GET = router.notFound();
+export const POST = router.notFound();
+export const DELETE = router.notFound();
+export const PUT = router.notFound();
+export const PATCH = router.notFound();
+```
+
+This catches stale agent calls to API paths that no longer exist and returns a JSON 404 telling the client to rediscover the origin.
+
 ## Auth modes
 
 | Method | Purpose |

package/dist/index.cjs

@@ -1207,7 +1207,7 @@ async function trySiwxFastPath(ctx, account) {
 function shouldParseBodyEarly(incomingStrategy, routeEntry, pricing) {
   if (incomingStrategy) return false;
   if (!routeEntry.bodySchema) return false;
-  return (pricing?.needsBody ?? false) || !!routeEntry.validateFn;
+  return (pricing?.needsBody ?? false) || !!routeEntry.validateFn || !!routeEntry.checkoutSession;
 }
 
 // src/pipeline/steps/resolve-early-body.ts
@@ -2549,30 +2549,37 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
     return errorResponse;
   }
   const extensions = await buildChallengeExtensions(ctx);
-  const responseBody = failure ? JSON.stringify({ error: failure.message ?? null, reason: failure.reason }) : null;
-  const response = new import_server5.NextResponse(responseBody, {
-    status: 402,
-    headers: {
-      "Content-Type": "application/json",
-      "Cache-Control": "no-store"
-    }
-  });
-  for (const strategy of getAllowedStrategies(ctx.routeEntry.protocols)) {
+  let checkoutSession;
+  if (ctx.routeEntry.checkoutSession) {
     try {
-      const contribution = await strategy.buildChallenge({
+      checkoutSession = await ctx.routeEntry.checkoutSession({
         request: ctx.request,
-        routeEntry: ctx.routeEntry,
+        route: ctx.routeEntry.key,
         body,
-        price: challengePrice,
-        extensions,
-        deps: ctx.deps,
-        report: ctx.report
+        price: challengePrice
       });
-      if (contribution.headers) {
-        for (const [name, value] of Object.entries(contribution.headers)) {
-          response.headers.set(name, value);
-        }
-      }
+    } catch (err) {
+      const message = errorMessage(err, "Checkout session build failed");
+      const responseBody2 = { success: false, error: message };
+      const errorResponse = import_server5.NextResponse.json(responseBody2, { status: errorStatus(err, 500) });
+      firePluginResponse(ctx, errorResponse, body, responseBody2, { message, cause: err });
+      return errorResponse;
+    }
+  }
+  const contributions = [];
+  for (const strategy of getAllowedStrategies(ctx.routeEntry.protocols)) {
+    try {
+      contributions.push(
+        await strategy.buildChallenge({
+          request: ctx.request,
+          routeEntry: ctx.routeEntry,
+          body,
+          price: challengePrice,
+          extensions,
+          deps: ctx.deps,
+          report: ctx.report
+        })
+      );
     } catch (err) {
       const message = `${strategy.protocol} challenge build failed: ${errorMessage(err, String(err))}`;
       ctx.report("critical", message);
@@ -2584,6 +2591,26 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
       }
     }
   }
+  const responsePayload = {
+    ...Object.assign({}, ...contributions.map((contribution) => contribution.body ?? {})),
+    ...failure && { error: failure.message ?? null, reason: failure.reason },
+    ...checkoutSession && { checkout_session: checkoutSession }
+  };
+  const responseBody = Object.keys(responsePayload).length ? JSON.stringify(responsePayload) : null;
+  const response = new import_server5.NextResponse(responseBody, {
+    status: 402,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store"
+    }
+  });
+  for (const contribution of contributions) {
+    if (contribution.headers) {
+      for (const [name, value] of Object.entries(contribution.headers)) {
+        response.headers.set(name, value);
+      }
+    }
+  }
   firePluginResponse(ctx, response);
   return response;
 }
@@ -3602,7 +3629,8 @@ var RouteBuilder = class _RouteBuilder {
       validateFn: void 0,
       settlement: void 0,
       mppInfo: void 0,
-      hasCheckout: false
+      hasCheckout: false,
+      checkoutSession: void 0
     };
   }
   fork() {
@@ -3693,7 +3721,8 @@ var RouteBuilder = class _RouteBuilder {
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
     if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
-    if (resolvedOptions.checkout) next.#s.hasCheckout = true;
+    if (resolvedOptions.checkout || resolvedOptions.checkoutSession) next.#s.hasCheckout = true;
+    if (resolvedOptions.checkoutSession) next.#s.checkoutSession = resolvedOptions.checkoutSession;
     next.#s.billing = billing;
     if (tickCost) next.#s.tickCost = tickCost;
     if (unitType) next.#s.unitType = unitType;
@@ -4128,6 +4157,7 @@ var RouteBuilder = class _RouteBuilder {
       settlement: this.#s.settlement,
       mppInfo: this.#s.mppInfo,
       hasCheckout: this.#s.hasCheckout ? true : void 0,
+      checkoutSession: this.#s.checkoutSession,
       tickCost: this.#s.tickCost,
       unitType: this.#s.unitType
     };
@@ -4475,6 +4505,33 @@ function createLlmsTxtHandler(discovery) {
   };
 }
 
+// src/discovery/not-found.ts
+var import_server12 = require("next/server");
+function createNotFoundHandler(baseUrl) {
+  const normalizedBase = baseUrl.replace(/\/+$/, "");
+  return async (request) => import_server12.NextResponse.json(
+    {
+      success: false,
+      code: "route_not_found",
+      error: "Route not found. Rediscover this origin and retry with the current discovery document.",
+      requestedUrl: request.url,
+      discovery: {
+        openapi: `${normalizedBase}/openapi.json`,
+        wellKnown: `${normalizedBase}/.well-known/x402`,
+        llmsTxt: `${normalizedBase}/llms.txt`
+      }
+    },
+    {
+      status: 404,
+      headers: {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, DELETE, PUT, PATCH, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-API-Key, SIGN-IN-WITH-X"
+      }
+    }
+  );
+}
+
 // src/index.ts
 init_accepts();
 init_constants();
@@ -5178,6 +5235,9 @@ function createRouter(config) {
     llmsTxt() {
       return createLlmsTxtHandler(config.discovery);
     },
+    notFound() {
+      return createNotFoundHandler(resolvedBaseUrl);
+    },
     monitors() {
       const result = [];
       for (const [, entry] of registry.entries()) {

package/dist/index.d.cts

@@ -219,6 +219,15 @@ interface MppProtocolInfo {
     intent?: string;
     currency?: string;
 }
+type CheckoutSessionResponse = Record<string, unknown>;
+interface CheckoutSessionContext<TBody = unknown> {
+    request: NextRequest;
+    route: string;
+    body: TBody | undefined;
+    /** Decimal-dollar price quoted for this 402 challenge. */
+    price: string;
+}
+type CheckoutSessionFn<TBody = unknown> = (ctx: CheckoutSessionContext<TBody>) => CheckoutSessionResponse | null | undefined | Promise<CheckoutSessionResponse | null | undefined>;
 interface PaidOptions {
     protocols?: ProtocolType[];
     maxPrice?: string;
@@ -229,6 +238,14 @@ interface PaidOptions {
     mpp?: MppProtocolInfo;
     /** Signal in discovery that clients should use an explicit checkout flow before payment. */
     checkout?: boolean;
+    /**
+     * Build dynamic checkout review metadata for the router-owned 402 response body.
+     *
+     * The returned object is emitted as `{ "checkout_session": ... }` on the unpaid
+     * payment challenge response. Payment terms remain authoritative in the x402/MPP
+     * challenge headers.
+     */
+    checkoutSession?: CheckoutSessionFn;
 }
 type PaidArg = (PaidOptions & {
     price: string;
@@ -374,6 +391,7 @@ interface RouteEntry {
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
     hasCheckout?: boolean;
+    checkoutSession?: CheckoutSessionFn;
     /** Per-tick cost (decimal-dollar). Required when `metered` is true. */
     tickCost?: string;
     /** Cosmetic unit label for 402 challenges and client UIs. */
@@ -557,8 +575,8 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ price }` — fixed price (object form of the string sugar).
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
-     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`) live
-     * alongside the pricing shape. For handler-computed billing use `.upTo()`;
+     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`,
+     * `checkoutSession`) live alongside the pricing shape. For handler-computed billing use `.upTo()`;
      * for per-tick billing use `.metered()`.
      *
      * @example
@@ -900,6 +918,7 @@ interface ServiceRouter<TPriceKeys extends string = never> {
     wellKnown(): (request: NextRequest) => Promise<NextResponse>;
     openapi(): (request: NextRequest) => Promise<NextResponse>;
     llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
+    notFound(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -928,4 +947,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
  */
 declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CheckoutSessionContext, type CheckoutSessionFn, type CheckoutSessionResponse, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };

package/dist/index.d.ts

@@ -219,6 +219,15 @@ interface MppProtocolInfo {
     intent?: string;
     currency?: string;
 }
+type CheckoutSessionResponse = Record<string, unknown>;
+interface CheckoutSessionContext<TBody = unknown> {
+    request: NextRequest;
+    route: string;
+    body: TBody | undefined;
+    /** Decimal-dollar price quoted for this 402 challenge. */
+    price: string;
+}
+type CheckoutSessionFn<TBody = unknown> = (ctx: CheckoutSessionContext<TBody>) => CheckoutSessionResponse | null | undefined | Promise<CheckoutSessionResponse | null | undefined>;
 interface PaidOptions {
     protocols?: ProtocolType[];
     maxPrice?: string;
@@ -229,6 +238,14 @@ interface PaidOptions {
     mpp?: MppProtocolInfo;
     /** Signal in discovery that clients should use an explicit checkout flow before payment. */
     checkout?: boolean;
+    /**
+     * Build dynamic checkout review metadata for the router-owned 402 response body.
+     *
+     * The returned object is emitted as `{ "checkout_session": ... }` on the unpaid
+     * payment challenge response. Payment terms remain authoritative in the x402/MPP
+     * challenge headers.
+     */
+    checkoutSession?: CheckoutSessionFn;
 }
 type PaidArg = (PaidOptions & {
     price: string;
@@ -374,6 +391,7 @@ interface RouteEntry {
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
     hasCheckout?: boolean;
+    checkoutSession?: CheckoutSessionFn;
     /** Per-tick cost (decimal-dollar). Required when `metered` is true. */
     tickCost?: string;
     /** Cosmetic unit label for 402 challenges and client UIs. */
@@ -557,8 +575,8 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * - `{ price }` — fixed price (object form of the string sugar).
      * - `{ field, tiers, default? }` — pick a tier from `body[field]`.
      *
-     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`) live
-     * alongside the pricing shape. For handler-computed billing use `.upTo()`;
+     * Common knobs (`protocols`, `maxPrice`, `minPrice`, `payTo`, `mpp`, `checkout`,
+     * `checkoutSession`) live alongside the pricing shape. For handler-computed billing use `.upTo()`;
      * for per-tick billing use `.metered()`.
      *
      * @example
@@ -900,6 +918,7 @@ interface ServiceRouter<TPriceKeys extends string = never> {
     wellKnown(): (request: NextRequest) => Promise<NextResponse>;
     openapi(): (request: NextRequest) => Promise<NextResponse>;
     llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
+    notFound(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
 }
@@ -928,4 +947,4 @@ declare function createRouter<const P extends Record<string, string> = Record<ne
  */
 declare function createRouterFromEnv<const P extends Record<string, string> = Record<never, string>>(options: CreateRouterFromEnvOptions<P>): ServiceRouter<Extract<keyof P, string>>;
 
-export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };
+export { BASE_MAINNET_NETWORK, BASE_USDC_ADDRESS, BASE_USDC_DECIMALS, type CheckoutSessionContext, type CheckoutSessionFn, type CheckoutSessionResponse, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type PaidOptions, type ProtocolType, type RouterConfig, RouterConfigError, type RouterConfigIssue, type RouterConfigIssueCode, type RouterConfigIssueSeverity, type RouterPlugin, SOLANA_MAINNET_NETWORK, type ServiceRouter, type SettlementErrorContext, type SettlementLifecycleContext, type SettlementSettledContext, TEMPO_USDC_ADDRESS, TEMPO_USDC_DECIMALS, type X402FacilitatorsConfig, ZERO_EVM_ADDRESS, createRouter, createRouterFromEnv, routerConfigFromEnv };

package/dist/index.js

@@ -1165,7 +1165,7 @@ async function trySiwxFastPath(ctx, account) {
 function shouldParseBodyEarly(incomingStrategy, routeEntry, pricing) {
   if (incomingStrategy) return false;
   if (!routeEntry.bodySchema) return false;
-  return (pricing?.needsBody ?? false) || !!routeEntry.validateFn;
+  return (pricing?.needsBody ?? false) || !!routeEntry.validateFn || !!routeEntry.checkoutSession;
 }
 
 // src/pipeline/steps/resolve-early-body.ts
@@ -2507,30 +2507,37 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
     return errorResponse;
   }
   const extensions = await buildChallengeExtensions(ctx);
-  const responseBody = failure ? JSON.stringify({ error: failure.message ?? null, reason: failure.reason }) : null;
-  const response = new NextResponse5(responseBody, {
-    status: 402,
-    headers: {
-      "Content-Type": "application/json",
-      "Cache-Control": "no-store"
-    }
-  });
-  for (const strategy of getAllowedStrategies(ctx.routeEntry.protocols)) {
+  let checkoutSession;
+  if (ctx.routeEntry.checkoutSession) {
     try {
-      const contribution = await strategy.buildChallenge({
+      checkoutSession = await ctx.routeEntry.checkoutSession({
         request: ctx.request,
-        routeEntry: ctx.routeEntry,
+        route: ctx.routeEntry.key,
         body,
-        price: challengePrice,
-        extensions,
-        deps: ctx.deps,
-        report: ctx.report
+        price: challengePrice
       });
-      if (contribution.headers) {
-        for (const [name, value] of Object.entries(contribution.headers)) {
-          response.headers.set(name, value);
-        }
-      }
+    } catch (err) {
+      const message = errorMessage(err, "Checkout session build failed");
+      const responseBody2 = { success: false, error: message };
+      const errorResponse = NextResponse5.json(responseBody2, { status: errorStatus(err, 500) });
+      firePluginResponse(ctx, errorResponse, body, responseBody2, { message, cause: err });
+      return errorResponse;
+    }
+  }
+  const contributions = [];
+  for (const strategy of getAllowedStrategies(ctx.routeEntry.protocols)) {
+    try {
+      contributions.push(
+        await strategy.buildChallenge({
+          request: ctx.request,
+          routeEntry: ctx.routeEntry,
+          body,
+          price: challengePrice,
+          extensions,
+          deps: ctx.deps,
+          report: ctx.report
+        })
+      );
     } catch (err) {
       const message = `${strategy.protocol} challenge build failed: ${errorMessage(err, String(err))}`;
       ctx.report("critical", message);
@@ -2542,6 +2549,26 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
       }
     }
   }
+  const responsePayload = {
+    ...Object.assign({}, ...contributions.map((contribution) => contribution.body ?? {})),
+    ...failure && { error: failure.message ?? null, reason: failure.reason },
+    ...checkoutSession && { checkout_session: checkoutSession }
+  };
+  const responseBody = Object.keys(responsePayload).length ? JSON.stringify(responsePayload) : null;
+  const response = new NextResponse5(responseBody, {
+    status: 402,
+    headers: {
+      "Content-Type": "application/json",
+      "Cache-Control": "no-store"
+    }
+  });
+  for (const contribution of contributions) {
+    if (contribution.headers) {
+      for (const [name, value] of Object.entries(contribution.headers)) {
+        response.headers.set(name, value);
+      }
+    }
+  }
   firePluginResponse(ctx, response);
   return response;
 }
@@ -3560,7 +3587,8 @@ var RouteBuilder = class _RouteBuilder {
       validateFn: void 0,
       settlement: void 0,
       mppInfo: void 0,
-      hasCheckout: false
+      hasCheckout: false,
+      checkoutSession: void 0
     };
   }
   fork() {
@@ -3651,7 +3679,8 @@ var RouteBuilder = class _RouteBuilder {
     if (resolvedOptions.minPrice) next.#s.minPrice = resolvedOptions.minPrice;
     if (resolvedOptions.payTo) next.#s.payTo = resolvedOptions.payTo;
     if (resolvedOptions.mpp) next.#s.mppInfo = resolvedOptions.mpp;
-    if (resolvedOptions.checkout) next.#s.hasCheckout = true;
+    if (resolvedOptions.checkout || resolvedOptions.checkoutSession) next.#s.hasCheckout = true;
+    if (resolvedOptions.checkoutSession) next.#s.checkoutSession = resolvedOptions.checkoutSession;
     next.#s.billing = billing;
     if (tickCost) next.#s.tickCost = tickCost;
     if (unitType) next.#s.unitType = unitType;
@@ -4086,6 +4115,7 @@ var RouteBuilder = class _RouteBuilder {
       settlement: this.#s.settlement,
       mppInfo: this.#s.mppInfo,
       hasCheckout: this.#s.hasCheckout ? true : void 0,
+      checkoutSession: this.#s.checkoutSession,
       tickCost: this.#s.tickCost,
       unitType: this.#s.unitType
     };
@@ -4433,6 +4463,33 @@ function createLlmsTxtHandler(discovery) {
   };
 }
 
+// src/discovery/not-found.ts
+import { NextResponse as NextResponse12 } from "next/server";
+function createNotFoundHandler(baseUrl) {
+  const normalizedBase = baseUrl.replace(/\/+$/, "");
+  return async (request) => NextResponse12.json(
+    {
+      success: false,
+      code: "route_not_found",
+      error: "Route not found. Rediscover this origin and retry with the current discovery document.",
+      requestedUrl: request.url,
+      discovery: {
+        openapi: `${normalizedBase}/openapi.json`,
+        wellKnown: `${normalizedBase}/.well-known/x402`,
+        llmsTxt: `${normalizedBase}/llms.txt`
+      }
+    },
+    {
+      status: 404,
+      headers: {
+        "Access-Control-Allow-Origin": "*",
+        "Access-Control-Allow-Methods": "GET, POST, DELETE, PUT, PATCH, OPTIONS",
+        "Access-Control-Allow-Headers": "Content-Type, Authorization, X-API-Key, SIGN-IN-WITH-X"
+      }
+    }
+  );
+}
+
 // src/index.ts
 init_accepts();
 init_constants();
@@ -5136,6 +5193,9 @@ function createRouter(config) {
     llmsTxt() {
       return createLlmsTxtHandler(config.discovery);
     },
+    notFound() {
+      return createNotFoundHandler(resolvedBaseUrl);
+    },
     monitors() {
       const result = [];
       for (const [, entry] of registry.entries()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentcash/router",
-  "version": "1.10.5",
+  "version": "1.10.6",
   "description": "Unified route builder for Next.js App Router APIs with x402, MPP, SIWX, and API key auth",
   "type": "module",
   "exports": {