@agentcash/router 1.12.0 → 1.13.0

package/dist/index.cjs

@@ -473,6 +473,7 @@ __export(index_exports, {
   DEFAULT_SOLANA_FACILITATOR_URL: () => DEFAULT_SOLANA_FACILITATOR_URL,
   DEFAULT_TEMPO_RPC_URL: () => DEFAULT_TEMPO_RPC_URL,
   HttpError: () => HttpError,
+  RouteDefinitionError: () => RouteDefinitionError,
   RouterConfigError: () => RouterConfigError,
   SOLANA_MAINNET_NETWORK: () => SOLANA_MAINNET_NETWORK,
   TEMPO_USDC_ADDRESS: () => TEMPO_USDC_ADDRESS,
@@ -873,6 +874,13 @@ var HttpError = class extends Error {
     this.name = "HttpError";
   }
 };
+var RouteDefinitionError = class extends Error {
+  constructor(route, detail) {
+    super(`route '${route}': ${detail}`);
+    this.route = route;
+    this.name = "RouteDefinitionError";
+  }
+};
 
 // src/auth/agent-identity.ts
 var PROTOCOL_VERSION = 1;
@@ -1400,6 +1408,23 @@ function multiplyDecimal(decimal, factor) {
   return fracPart ? `${intPart}.${fracPart}` : intPart;
 }
 
+// src/protocols/detect.ts
+function hasX402Payment(request) {
+  return Boolean(
+    request.headers.get(HEADERS.X402_PAYMENT_SIGNATURE) ?? request.headers.get(HEADERS.X402_PAYMENT_LEGACY)
+  );
+}
+function hasMppPayment(request) {
+  const auth = request.headers.get(HEADERS.AUTHORIZATION);
+  return Boolean(auth && auth.startsWith(AUTH_SCHEME.MPP_PAYMENT));
+}
+function detectProtocol(request) {
+  if (hasX402Payment(request)) return "x402";
+  if (hasMppPayment(request)) return "mpp";
+  if (request.headers.get(HEADERS.SIWX)) return "siwx";
+  return null;
+}
+
 // src/protocols/mpp/credential.ts
 var import_mppx = require("mppx");
 var import_viem = require("viem");
@@ -1766,10 +1791,7 @@ function settleHashMode(args) {
 // src/protocols/mpp/strategy.ts
 var mppStrategy = {
   protocol: "mpp",
-  detects(request) {
-    const auth = request.headers.get(HEADERS.AUTHORIZATION);
-    return Boolean(auth && auth.startsWith(AUTH_SCHEME.MPP_PAYMENT));
-  },
+  detects: hasMppPayment,
   preflight(request, _routeEntry) {
     const info = readMppCredential(request);
     if (!info?.sessionAction) return null;
@@ -2204,11 +2226,7 @@ function formatVerifyFailureMessage(failure) {
 }
 var x402Strategy = {
   protocol: "x402",
-  detects(request) {
-    return Boolean(
-      request.headers.get(HEADERS.X402_PAYMENT_SIGNATURE) ?? request.headers.get(HEADERS.X402_PAYMENT_LEGACY)
-    );
-  },
+  detects: hasX402Payment,
   verify: (args) => verifyX402(args),
   settle: (args) => settleX402(args),
   buildChallenge: (args) => buildX402ChallengeContribution(args)
@@ -2355,21 +2373,6 @@ function getAllowedStrategies(allowed) {
   return allowed.map((name) => STRATEGIES[name]);
 }
 
-// src/protocols/detect.ts
-function detectProtocol(request) {
-  if (request.headers.get(HEADERS.X402_PAYMENT_SIGNATURE) ?? request.headers.get(HEADERS.X402_PAYMENT_LEGACY)) {
-    return "x402";
-  }
-  const auth = request.headers.get(HEADERS.AUTHORIZATION);
-  if (auth && auth.startsWith(AUTH_SCHEME.MPP_PAYMENT)) {
-    return "mpp";
-  }
-  if (request.headers.get(HEADERS.SIWX)) {
-    return "siwx";
-  }
-  return null;
-}
-
 // src/pipeline/flows/api-key-only.ts
 async function runApiKeyOnlyFlow(ctx) {
   if (!ctx.routeEntry.apiKeyResolver) {
@@ -2692,6 +2695,61 @@ async function buildChallengeResponse(ctx, pricing, body, failure) {
   return response;
 }
 
+// src/pipeline/flows/paid-preamble.ts
+async function runPaidPreamble(ctx) {
+  const { request, routeEntry, deps, report } = ctx;
+  const apiKeyGate = await runApiKeyGate(ctx);
+  if (!apiKeyGate.ok) return { done: true, response: apiKeyGate.response };
+  const { account } = apiKeyGate;
+  const pricing = selectPricing(routeEntry.pricing, {
+    alert: report,
+    maxPrice: routeEntry.maxPrice,
+    minPrice: routeEntry.minPrice,
+    route: routeEntry.key
+  });
+  const incomingStrategy = selectIncomingStrategy(request, routeEntry.protocols);
+  const earlyResolution = await resolveEarlyBody({ ctx, pricing, incomingStrategy });
+  if (!earlyResolution.ok) return { done: true, response: earlyResolution.response };
+  const { earlyBody } = earlyResolution;
+  const siwxFastPath = await trySiwxFastPath(ctx, account);
+  if (siwxFastPath) return { done: true, response: siwxFastPath };
+  if (!incomingStrategy) {
+    const initError = protocolInitError(routeEntry, deps);
+    if (initError) return { done: true, response: fail(ctx, 500, initError) };
+    return { done: true, response: await buildChallengeResponse(ctx, pricing, earlyBody) };
+  }
+  return { done: false, account, pricing, incomingStrategy, earlyBody };
+}
+async function runPaidVerify(args) {
+  const { ctx, strategy, pricing, parsedBody, price } = args;
+  const { request, routeEntry, deps, report } = ctx;
+  const verifyOutcome = await strategy.verify({
+    request,
+    body: parsedBody,
+    price,
+    routeEntry,
+    deps,
+    report
+  });
+  if (verifyOutcome.ok === false) {
+    if (verifyOutcome.kind === "config") {
+      return { ok: false, response: fail(ctx, 500, verifyOutcome.message, parsedBody) };
+    }
+    return {
+      ok: false,
+      response: await buildChallengeResponse(ctx, pricing, parsedBody, verifyOutcome.failure)
+    };
+  }
+  ctx.pluginCtx.setVerifiedWallet(verifyOutcome.wallet);
+  firePaymentVerified(ctx, {
+    protocol: strategy.protocol,
+    payer: verifyOutcome.wallet,
+    amount: price,
+    network: verifyOutcome.payment.network
+  });
+  return { ok: true, verifyOutcome };
+}
+
 // src/pipeline/flows/dynamic/dynamic-body-and-price.ts
 async function resolveDynamicBodyAndPrice(args) {
   const { ctx, pricing, skipBody } = args;
@@ -3058,27 +3116,10 @@ async function runDynamicStreamFlow(args) {
 
 // src/pipeline/flows/dynamic/dynamic-paid.ts
 async function runDynamicPaidFlow(ctx) {
-  const { request, routeEntry, deps, report } = ctx;
-  const apiKeyGate = await runApiKeyGate(ctx);
-  if (!apiKeyGate.ok) return apiKeyGate.response;
-  const { account } = apiKeyGate;
-  const pricing = selectPricing(routeEntry.pricing, {
-    alert: report,
-    maxPrice: routeEntry.maxPrice,
-    minPrice: routeEntry.minPrice,
-    route: routeEntry.key
-  });
-  const incomingStrategy = selectIncomingStrategy(request, routeEntry.protocols);
-  const earlyResolution = await resolveEarlyBody({ ctx, pricing, incomingStrategy });
-  if (!earlyResolution.ok) return earlyResolution.response;
-  const { earlyBody } = earlyResolution;
-  const siwxFastPath = await trySiwxFastPath(ctx, account);
-  if (siwxFastPath) return siwxFastPath;
-  if (!incomingStrategy) {
-    const initError = protocolInitError(routeEntry, deps);
-    if (initError) return fail(ctx, 500, initError);
-    return buildChallengeResponse(ctx, pricing, earlyBody);
-  }
+  const { request, routeEntry } = ctx;
+  const preamble = await runPaidPreamble(ctx);
+  if (preamble.done) return preamble.response;
+  const { account, pricing, incomingStrategy } = preamble;
   const { skipBody, skipHandler } = resolveDynamicPreflight(incomingStrategy, request, routeEntry);
   if (skipHandler) {
     return runDynamicChannelMgmtFlow({
@@ -3092,27 +3133,15 @@ async function runDynamicPaidFlow(ctx) {
   const bodyAndPrice = await resolveDynamicBodyAndPrice({ ctx, pricing, skipBody });
   if (!bodyAndPrice.ok) return bodyAndPrice.response;
   const { parsedBody, price } = bodyAndPrice;
-  const verifyOutcome = await incomingStrategy.verify({
-    request,
-    body: parsedBody,
-    price,
-    routeEntry,
-    deps,
-    report
-  });
-  if (verifyOutcome.ok === false) {
-    if (verifyOutcome.kind === "config") {
-      return fail(ctx, 500, verifyOutcome.message, parsedBody);
-    }
-    return buildChallengeResponse(ctx, pricing, parsedBody, verifyOutcome.failure);
-  }
-  ctx.pluginCtx.setVerifiedWallet(verifyOutcome.wallet);
-  firePaymentVerified(ctx, {
-    protocol: incomingStrategy.protocol,
-    payer: verifyOutcome.wallet,
-    amount: price,
-    network: verifyOutcome.payment.network
+  const verify = await runPaidVerify({
+    ctx,
+    strategy: incomingStrategy,
+    pricing,
+    parsedBody,
+    price
   });
+  if (!verify.ok) return verify.response;
+  const { verifyOutcome } = verify;
   const result = await invokeDynamic(ctx, verifyOutcome, account, parsedBody);
   switch (result.kind) {
     case "stream":
@@ -3244,51 +3273,21 @@ function failureFromCause2(cause) {
 
 // src/pipeline/flows/static/static-paid.ts
 async function runStaticPaidFlow(ctx) {
-  const { request, routeEntry, deps, report } = ctx;
-  const apiKeyGate = await runApiKeyGate(ctx);
-  if (!apiKeyGate.ok) return apiKeyGate.response;
-  const { account } = apiKeyGate;
-  const pricing = selectPricing(routeEntry.pricing, {
-    alert: report,
-    maxPrice: routeEntry.maxPrice,
-    minPrice: routeEntry.minPrice,
-    route: routeEntry.key
-  });
-  const incomingStrategy = selectIncomingStrategy(request, routeEntry.protocols);
-  const earlyResolution = await resolveEarlyBody({ ctx, pricing, incomingStrategy });
-  if (!earlyResolution.ok) return earlyResolution.response;
-  const { earlyBody } = earlyResolution;
-  const siwxFastPath = await trySiwxFastPath(ctx, account);
-  if (siwxFastPath) return siwxFastPath;
-  if (!incomingStrategy) {
-    const initError = protocolInitError(routeEntry, deps);
-    if (initError) return fail(ctx, 500, initError);
-    return buildChallengeResponse(ctx, pricing, earlyBody);
-  }
+  const preamble = await runPaidPreamble(ctx);
+  if (preamble.done) return preamble.response;
+  const { account, pricing, incomingStrategy } = preamble;
   const bodyAndPrice = await resolveStaticBodyAndPrice({ ctx, pricing });
   if (!bodyAndPrice.ok) return bodyAndPrice.response;
   const { parsedBody, price } = bodyAndPrice;
-  const verifyOutcome = await incomingStrategy.verify({
-    request,
-    body: parsedBody,
-    price,
-    routeEntry,
-    deps,
-    report
-  });
-  if (verifyOutcome.ok === false) {
-    if (verifyOutcome.kind === "config") {
-      return fail(ctx, 500, verifyOutcome.message, parsedBody);
-    }
-    return buildChallengeResponse(ctx, pricing, parsedBody, verifyOutcome.failure);
-  }
-  ctx.pluginCtx.setVerifiedWallet(verifyOutcome.wallet);
-  firePaymentVerified(ctx, {
-    protocol: incomingStrategy.protocol,
-    payer: verifyOutcome.wallet,
-    amount: price,
-    network: verifyOutcome.payment.network
+  const verify = await runPaidVerify({
+    ctx,
+    strategy: incomingStrategy,
+    pricing,
+    parsedBody,
+    price
   });
+  if (!verify.ok) return verify.response;
+  const { verifyOutcome } = verify;
   const result = await invokePaidStatic(
     ctx,
     verifyOutcome.wallet,
@@ -3780,55 +3779,35 @@ var RouteBuilder = class _RouteBuilder {
     return next;
   }
   paid(arg, options) {
-    return this.applyPaid(normalizePaidArg(this.#s.key, arg, options), "paid");
+    const self = this;
+    return self.applyPaid(normalizePaidArg(self.#s.key, arg, options), "paid");
   }
-  /**
-   * x402-only handler-computed billing. The handler receives `charge(amount)`
-   * and the request settles once for the accumulated total, capped at
-   * `maxPrice`. Requires an `'upto'` accept on at least one configured network.
-   * Pass a bare string as sugar for `{ maxPrice }`.
-   *
-   * @example
-   * ```ts
-   * router.route('llm')
-   *   .upTo('0.05')
-   *   .body(schema)
-   *   .handler(async ({ body, charge }) => { await charge('0.001'); ... });
-   * ```
-   */
   upTo(arg) {
-    return this.applyPaid(normalizeUpToArg(this.#s.key, arg), "upTo");
+    const self = this;
+    return self.applyPaid(normalizeUpToArg(self.#s.key, arg), "upTo");
   }
-  /**
-   * MPP-only per-tick billing. `.handler()` bills exactly `tickCost`;
-   * `.stream()` calls `charge()` (no-arg) per yield, settling per tick up to
-   * `maxPrice`. Requires `RouterConfig.mpp.session`.
-   *
-   * @example
-   * ```ts
-   * router.route('llm/stream')
-   *   .metered({ tickCost: '0.0001', maxPrice: '0.05', unitType: 'token' })
-   *   .stream(async function* ({ charge }) { await charge(); yield 'hi'; });
-   * ```
-   */
   metered(options) {
-    return this.applyPaid(normalizeMeteredArg(this.#s.key, options), "metered");
+    const self = this;
+    return self.applyPaid(normalizeMeteredArg(self.#s.key, options), "metered");
   }
   applyPaid(normalized, method) {
     const { pricing, resolvedOptions, billing, tickCost, unitType, maxPrice } = normalized;
     if (this.#s.authMode === "unprotected") {
-      throw new Error(
-        `route '${this.#s.key}': Cannot combine .unprotected() and .${method}() on the same route.`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `Cannot combine .unprotected() and .${method}() on the same route.`
       );
     }
     if (this.#s.pricing !== void 0) {
-      throw new Error(
-        `route '${this.#s.key}': Cannot combine .paid(), .upTo(), and .metered() \u2014 pick one pricing mode.`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `Cannot combine .paid(), .upTo(), and .metered() \u2014 pick one pricing mode.`
       );
     }
     if (this.#s.siwxEnabled && billing === "metered") {
-      throw new Error(
-        `route '${this.#s.key}': Cannot combine .siwx() and .metered() \u2014 per-tick MPP billing has no entitlement model. Use .paid() or .upTo() with .siwx(), or drop .siwx() for metered routes.`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `Cannot combine .siwx() and .metered() \u2014 per-tick MPP billing has no entitlement model. Use .paid() or .upTo() with .siwx(), or drop .siwx() for metered routes.`
       );
     }
     const next = this.fork();
@@ -3836,15 +3815,17 @@ var RouteBuilder = class _RouteBuilder {
     next.#s.pricing = pricing;
     if (billing === "upto") {
       if (resolvedOptions.protocols?.some((p) => p !== "x402")) {
-        throw new Error(
-          `route '${this.#s.key}': .upTo() is x402-only \u2014 remove the conflicting protocols override.`
+        throw new RouteDefinitionError(
+          this.#s.key,
+          `.upTo() is x402-only \u2014 remove the conflicting protocols override.`
         );
       }
       next.#s.protocols = ["x402"];
     } else if (billing === "metered") {
       if (resolvedOptions.protocols?.some((p) => p !== "mpp")) {
-        throw new Error(
-          `route '${this.#s.key}': .metered() is MPP-only \u2014 remove the conflicting protocols override.`
+        throw new RouteDefinitionError(
+          this.#s.key,
+          `.metered() is MPP-only \u2014 remove the conflicting protocols override.`
         );
       }
       next.#s.protocols = ["mpp"];
@@ -3868,73 +3849,69 @@ var RouteBuilder = class _RouteBuilder {
     if (typeof pricing === "object" && "tiers" in pricing) {
       for (const [tierKey, tierConfig] of Object.entries(pricing.tiers)) {
         if (!tierKey) {
-          throw new Error(`route '${this.#s.key}': tier key cannot be empty`);
+          throw new RouteDefinitionError(this.#s.key, `tier key cannot be empty`);
         }
         if (!isPositiveDecimal(tierConfig.price)) {
-          throw new Error(
-            `route '${this.#s.key}': tier '${tierKey}' price '${tierConfig.price}' must be a positive decimal string`
+          throw new RouteDefinitionError(
+            this.#s.key,
+            `tier '${tierKey}' price '${tierConfig.price}' must be a positive decimal string`
           );
         }
       }
     }
     if (billing === "exact" && typeof pricing === "string" && !isPositiveDecimal(pricing)) {
-      throw new Error(
-        `route '${this.#s.key}': price '${pricing}' must be a positive decimal string`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `price '${pricing}' must be a positive decimal string`
       );
     }
     if (typeof pricing === "function" && next.#s.maxPrice === void 0) {
-      throw new Error(
-        `route '${this.#s.key}': dynamic pricing requires maxPrice \u2014 without it, bare probes would advertise a $0 challenge`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `dynamic pricing requires maxPrice \u2014 without it, bare probes would advertise a $0 challenge`
       );
     }
     if (next.#s.maxPrice !== void 0 && !isPositiveDecimal(next.#s.maxPrice)) {
-      throw new Error(
-        `route '${this.#s.key}': maxPrice '${next.#s.maxPrice}' must be a positive decimal string`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `maxPrice '${next.#s.maxPrice}' must be a positive decimal string`
       );
     }
     if (next.#s.minPrice !== void 0 && !isPositiveDecimal(next.#s.minPrice)) {
-      throw new Error(
-        `route '${this.#s.key}': minPrice '${next.#s.minPrice}' must be a positive decimal string`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `minPrice '${next.#s.minPrice}' must be a positive decimal string`
       );
     }
     if (next.#s.tickCost !== void 0 && !isPositiveDecimal(next.#s.tickCost)) {
-      throw new Error(
-        `route '${this.#s.key}': tickCost '${next.#s.tickCost}' must be a positive decimal string`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `tickCost '${next.#s.tickCost}' must be a positive decimal string`
       );
     }
     return next;
   }
-  /**
-   * Require Sign-In-with-X wallet identity on this route — clients prove
-   * control of a wallet via a signed challenge. Composes with `.paid()` and
-   * `.upTo()` for pay-once-then-replay: the first request settles normally,
-   * subsequent requests with a valid SIWX signature for the same wallet skip
-   * payment (on `.upTo()`, `charge(amount)` becomes a no-op on the replay).
-   * Mutually exclusive with `.metered()`.
-   *
-   * @example
-   * ```ts
-   * router.route('profile').siwx().handler(async ({ wallet }) => getProfile(wallet));
-   * router.route('inbox').paid('0.01').siwx().handler(async ({ wallet }) => getInbox(wallet));
-   * ```
-   */
   siwx() {
-    if (this.#s.authMode === "unprotected") {
-      throw new Error(
-        `route '${this.#s.key}': Cannot combine .unprotected() and .siwx() on the same route.`
+    const self = this;
+    if (self.#s.authMode === "unprotected") {
+      throw new RouteDefinitionError(
+        self.#s.key,
+        `Cannot combine .unprotected() and .siwx() on the same route.`
       );
     }
-    if (this.#s.apiKeyResolver) {
-      throw new Error(
-        `route '${this.#s.key}': Combining .siwx() and .apiKey() is not supported on the same route.`
+    if (self.#s.apiKeyResolver) {
+      throw new RouteDefinitionError(
+        self.#s.key,
+        `Combining .siwx() and .apiKey() is not supported on the same route.`
       );
     }
-    if (this.#s.billing === "metered") {
-      throw new Error(
-        `route '${this.#s.key}': Cannot combine .metered() and .siwx() \u2014 per-tick MPP billing has no entitlement model. Use .paid() or .upTo() with .siwx(), or drop .siwx() for metered routes.`
+    if (self.#s.billing === "metered") {
+      throw new RouteDefinitionError(
+        self.#s.key,
+        `Cannot combine .metered() and .siwx() \u2014 per-tick MPP billing has no entitlement model. Use .paid() or .upTo() with .siwx(), or drop .siwx() for metered routes.`
       );
     }
-    const next = this.fork();
+    const next = self.fork();
     next.#s.siwxEnabled = true;
     if (next.#s.authMode === "paid" || next.#s.pricing) {
       next.#s.authMode = "paid";
@@ -3945,59 +3922,48 @@ var RouteBuilder = class _RouteBuilder {
     next.#s.protocols = [];
     return next;
   }
-  /**
-   * Require an `X-API-Key` header (or `Authorization: Bearer <key>`); the
-   * resolver returns the account record, or `null` for 401. Composes with
-   * `.paid()` — key is checked first, payment second.
-   *
-   * @example
-   * ```ts
-   * router
-   *   .route('admin/users')
-   *   .apiKey(async (key) => db.admin.findByKey(key))
-   *   .handler(async ({ account }) => db.user.list(account.orgId));
-   * ```
-   */
   apiKey(resolver) {
-    if (this.#s.siwxEnabled) {
-      throw new Error(
-        `route '${this.#s.key}': Combining .apiKey() and .siwx() is not supported on the same route.`
+    const self = this;
+    if (self.#s.authMode === "unprotected") {
+      throw new RouteDefinitionError(
+        self.#s.key,
+        `Cannot combine .unprotected() and .apiKey() on the same route.`
       );
     }
-    const next = this.fork();
+    if (self.#s.siwxEnabled) {
+      throw new RouteDefinitionError(
+        self.#s.key,
+        `Combining .apiKey() and .siwx() is not supported on the same route.`
+      );
+    }
+    const next = self.fork();
     next.#s.authMode = "apiKey";
     next.#s.apiKeyResolver = resolver;
     return next;
   }
-  /**
-   * Mark the route as public — no auth, no payment, no SIWX. The handler
-   * receives `null` for `wallet`, `payment`, and `account`.
-   *
-   * @example
-   * ```ts
-   * router.route('health').unprotected().handler(async () => ({ status: 'ok' }));
-   * ```
-   */
   unprotected() {
-    if (this.#s.authMode && this.#s.authMode !== "unprotected") {
-      throw new Error(
-        `route '${this.#s.key}': Cannot combine .unprotected() and .${this.#s.authMode}() on the same route.`
+    const self = this;
+    if (self.#s.authMode && self.#s.authMode !== "unprotected") {
+      throw new RouteDefinitionError(
+        self.#s.key,
+        `Cannot combine .unprotected() and .${self.#s.authMode}() on the same route.`
       );
     }
-    if (this.#s.pricing) {
-      throw new Error(
-        `route '${this.#s.key}': Cannot combine .unprotected() and .paid() on the same route.`
+    if (self.#s.pricing) {
+      throw new RouteDefinitionError(
+        self.#s.key,
+        `Cannot combine .unprotected() and .paid() on the same route.`
       );
     }
-    const next = this.fork();
+    const next = self.fork();
     next.#s.authMode = "unprotected";
     next.#s.protocols = [];
     return next;
   }
   /**
    * Tag the route with an upstream provider for discovery and provider-side
-   * monitoring. The provider name and config surface in `well-known` and
-   * OpenAPI output.
+   * monitoring. The provider name and config surface in OpenAPI discovery
+   * output.
    *
    * @example
    * ```ts
@@ -4094,8 +4060,8 @@ var RouteBuilder = class _RouteBuilder {
     return next;
   }
   /**
-   * Set a human-readable summary of the route. Surfaces in OpenAPI,
-   * `well-known`, and `llms.txt` discovery output.
+   * Set a human-readable summary of the route. Surfaces in OpenAPI and
+   * `llms.txt` discovery output.
    *
    * @example
    * ```ts
@@ -4231,38 +4197,46 @@ var RouteBuilder = class _RouteBuilder {
   }
   register(handlerFn, streaming) {
     if (!this.#s.authMode) {
-      throw new Error(
-        `route '${this.#s.key}': Select an auth mode: .paid(pricing), .upTo(maxPrice), .metered(options), .siwx(), .apiKey(resolver), or .unprotected()`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `Select an auth mode: .paid(pricing), .upTo(maxPrice), .metered(options), .siwx(), .apiKey(resolver), or .unprotected()`
       );
     }
     if (this.#s.validateFn && !this.#s.bodySchema) {
-      throw new Error(
-        `route '${this.#s.key}': .validate() requires .body() \u2014 validation runs on parsed body`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `.validate() requires .body() \u2014 validation runs on parsed body`
       );
     }
     if (this.#s.settlement && !this.#s.pricing) {
-      throw new Error(`route '${this.#s.key}': .settlement() requires a paid route`);
+      throw new RouteDefinitionError(this.#s.key, `.settlement() requires a paid route`);
     }
     if (this.#s.mppInfo?.settleBeforeHandler) {
       if (!this.#s.pricing) {
-        throw new Error(`route '${this.#s.key}': mpp.settleBeforeHandler requires a paid route`);
+        throw new RouteDefinitionError(
+          this.#s.key,
+          `mpp.settleBeforeHandler requires a paid route`
+        );
       }
       if (this.#s.billing !== "exact") {
-        throw new Error(
-          `route '${this.#s.key}': mpp.settleBeforeHandler is only supported on .paid() routes`
+        throw new RouteDefinitionError(
+          this.#s.key,
+          `mpp.settleBeforeHandler is only supported on .paid() routes`
         );
       }
       if (this.#s.settlement?.beforeSettle) {
-        throw new Error(
-          `route '${this.#s.key}': mpp.settleBeforeHandler is incompatible with .settlement({ beforeSettle }) \u2014 MPP payment is already broadcast before the handler runs`
+        throw new RouteDefinitionError(
+          this.#s.key,
+          `mpp.settleBeforeHandler is incompatible with .settlement({ beforeSettle }) \u2014 MPP payment is already broadcast before the handler runs`
         );
       }
     }
     if (this.#s.billing === "upto") {
       const hasUpto = this.#s.deps.x402Accepts.some((accept) => accept.scheme === "upto");
       if (!hasUpto) {
-        throw new Error(
-          `route '${this.#s.key}': .upTo() requires an 'upto' accept on at least one configured network. Add { scheme: 'upto', network, asset } to RouterConfig.x402.accepts.`
+        throw new RouteDefinitionError(
+          this.#s.key,
+          `.upTo() requires an 'upto' accept on at least one configured network. Add { scheme: 'upto', network, asset } to RouterConfig.x402.accepts.`
         );
       }
     }
@@ -4271,26 +4245,30 @@ var RouteBuilder = class _RouteBuilder {
         (accept) => (accept.scheme ?? "exact") !== "upto"
       );
       if (!hasExact) {
-        throw new Error(
-          `route '${this.#s.key}': .paid() needs a non-'upto' x402 accept \u2014 an 'upto'-only accept list cannot serve a fixed-price route. Add { scheme: 'exact', network } to RouterConfig.x402.accepts, or use .upTo() for handler-computed billing.`
+        throw new RouteDefinitionError(
+          this.#s.key,
+          `.paid() needs a non-'upto' x402 accept \u2014 an 'upto'-only accept list cannot serve a fixed-price route. Add { scheme: 'exact', network } to RouterConfig.x402.accepts, or use .upTo() for handler-computed billing.`
         );
       }
     }
     if (this.#s.billing === "metered") {
       if (!this.#s.deps.mppSessionConfig) {
-        throw new Error(
-          `route '${this.#s.key}': .metered() requires MPP session mode. Set RouterConfig.mpp.session = {} and provide mpp.operatorKey.`
+        throw new RouteDefinitionError(
+          this.#s.key,
+          `.metered() requires MPP session mode. Set RouterConfig.mpp.session = {} and provide mpp.operatorKey.`
         );
       }
     }
     if (streaming && this.#s.billing !== "metered") {
-      throw new Error(
-        `route '${this.#s.key}': .stream() requires .metered() \u2014 static/free/upto routes can't meter per-chunk billing.`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `.stream() requires .metered() \u2014 static/free/upto routes can't meter per-chunk billing.`
       );
     }
     if (this.#s.description !== void 0 && this.#s.description.length > MAX_X402_DESCRIPTION_LENGTH && this.#s.pricing !== void 0 && this.#s.protocols.includes("x402")) {
-      throw new Error(
-        `route '${this.#s.key}': .description() is ${this.#s.description.length} chars; must be \u2264 ${MAX_X402_DESCRIPTION_LENGTH} chars \u2014 the CDP x402 facilitator rejects payments whose 402 challenge resource.description exceeds ~500 chars.`
+      throw new RouteDefinitionError(
+        this.#s.key,
+        `.description() is ${this.#s.description.length} chars; must be \u2264 ${MAX_X402_DESCRIPTION_LENGTH} chars \u2014 the CDP x402 facilitator rejects payments whose 402 challenge resource.description exceeds ~500 chars.`
       );
     }
     validateExamples(
@@ -4358,14 +4336,15 @@ function normalizePaidArg(routeKey, arg, options) {
   if ("price" in arg && typeof arg.price === "string") {
     return { pricing: arg.price, resolvedOptions: arg, billing: "exact" };
   }
-  throw new Error(
-    `route '${routeKey}': .paid() requires one of: a price string, a (body) => string function, { price }, or { field, tiers }. For handler-computed billing use .upTo(); for per-tick billing use .metered().`
+  throw new RouteDefinitionError(
+    routeKey,
+    `.paid() requires one of: a price string, a (body) => string function, { price }, or { field, tiers }. For handler-computed billing use .upTo(); for per-tick billing use .metered().`
   );
 }
 function normalizeUpToArg(routeKey, arg) {
   const options = typeof arg === "string" ? { maxPrice: arg } : arg;
   if (!options.maxPrice) {
-    throw new Error(`route '${routeKey}': .upTo() requires maxPrice`);
+    throw new RouteDefinitionError(routeKey, `.upTo() requires maxPrice`);
   }
   return {
     pricing: options.maxPrice,
@@ -4377,10 +4356,10 @@ function normalizeUpToArg(routeKey, arg) {
 }
 function normalizeMeteredArg(routeKey, options) {
   if (!options.maxPrice) {
-    throw new Error(`route '${routeKey}': .metered() requires maxPrice`);
+    throw new RouteDefinitionError(routeKey, `.metered() requires maxPrice`);
   }
   if (!options.tickCost) {
-    throw new Error(`route '${routeKey}': .metered() requires tickCost`);
+    throw new RouteDefinitionError(routeKey, `.metered() requires tickCost`);
   }
   return {
     pricing: options.maxPrice,
@@ -4687,9 +4666,9 @@ function createNotFoundHandler(baseUrl) {
       code: "route_not_found",
       error: "Route not found. Rediscover this origin and retry with the current discovery document.",
       requestedUrl: request.url,
+      // The deprecated /.well-known/x402 surface is intentionally not advertised.
       discovery: {
         openapi: `${normalizedBase}/openapi.json`,
-        wellKnown: `${normalizedBase}/.well-known/x402`,
         llmsTxt: `${normalizedBase}/llms.txt`
       }
     },
@@ -4723,6 +4702,7 @@ function formatRouterConfigIssues(issues) {
 
 // src/config/schema.ts
 var import_zod = require("zod");
+init_accepts();
 init_constants();
 
 // src/config/utils.ts
@@ -4911,18 +4891,8 @@ function deriveBaseUrlEnv(env) {
     BASE_URL: vercelBaseUrl
   };
 }
-function getConfiguredX402Accepts2(config) {
-  if (config.x402?.accepts?.length) return [...config.x402.accepts];
-  return [
-    {
-      scheme: "exact",
-      network: config.network ?? BASE_MAINNET_NETWORK,
-      payTo: config.payeeAddress
-    }
-  ];
-}
 function validateX402Config(config, env) {
-  const accepts = getConfiguredX402Accepts2(config);
+  const accepts = getConfiguredX402Accepts(config);
   const issues = [];
   const push = (code, message) => issues.push({ code, protocol: "x402", message });
   if (accepts.length === 0) {
@@ -5223,7 +5193,8 @@ function getMppxRequestContext(args) {
         recipient: mppConfig.recipient ?? payeeAddress,
         getClient,
         ...feePayerAccount ? { feePayer: feePayerAccount } : {},
-        ...resolvedStore ? { store: resolvedStore } : {}
+        ...resolvedStore ? { store: resolvedStore } : {},
+        ...mppConfig.feePayerPolicy ? { feePayerPolicy: mppConfig.feePayerPolicy } : {}
       }),
       ...sessionEnabled ? [
         tempo.session({
@@ -5261,7 +5232,7 @@ async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
   try {
     const { Mppx, tempo } = await import("mppx/server");
     const { createClient, http } = await import("viem");
-    const { tempo: tempoChain } = await import("viem/chains");
+    const { tempo: tempoChain } = await import("viem/tempo/chains");
     const { privateKeyToAccount: privateKeyToAccount2 } = await import("viem/accounts");
     const rpcUrl = config.mpp.rpcUrl ?? process.env.TEMPO_RPC_URL ?? DEFAULT_TEMPO_RPC_URL;
     const tempoClient = createClient({ chain: tempoChain, transport: http(rpcUrl) });
@@ -5279,7 +5250,9 @@ async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
       getClient,
       ...operatorAccount ? { account: operatorAccount } : {},
       ...feePayerAccount ? { feePayer: feePayerAccount } : {},
-      ...resolvedStore ? { store: resolvedStore } : {}
+      ...resolvedStore ? { store: resolvedStore } : {},
+      ...mppConfig.feePayerPolicy ? { feePayerPolicy: mppConfig.feePayerPolicy } : {},
+      ...mppConfig.session?.settlementSchedule ? { settlementSchedule: mppConfig.session.settlementSchedule } : {}
     };
     const mppxArgs = {
       Mppx,
@@ -5295,6 +5268,7 @@ async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
     };
     const primary = getMppxRequestContext(mppxArgs);
     const streaming = getMppxStreamingContext(mppxArgs);
+    subscribePaymentFailedAlerts(config.plugin, [primary, streaming]);
     const mppx = {
       charge: primary.charge,
       ...primary.session ? { sessionRequest: primary.session } : {},
@@ -5305,6 +5279,41 @@ async function initMpp(config, resolvedBaseUrl, kvStore, configError) {
     return { initError: err instanceof Error ? err.message : String(err) };
   }
 }
+function subscribePaymentFailedAlerts(plugin, instances) {
+  if (!plugin?.onAlert) return;
+  const ctx = {
+    requestId: "mppx",
+    route: "mpp",
+    walletAddress: null,
+    clientId: null,
+    sessionId: null,
+    verifiedWallet: null,
+    setVerifiedWallet() {
+    }
+  };
+  for (const instance of instances) {
+    const events = instance;
+    if (typeof events?.onPaymentFailed !== "function") continue;
+    events.onPaymentFailed((payload) => {
+      try {
+        const error = payload?.error ?? {};
+        firePluginHook(plugin, "onAlert", ctx, {
+          level: (error.status ?? 402) >= 500 ? "error" : "warn",
+          message: `MPP payment failed: ${error.message ?? error.name ?? "unknown error"}`,
+          route: "mpp",
+          meta: {
+            ...payload?.method ? { method: `${payload.method.name}/${payload.method.intent}` } : {},
+            ...error.type ? { errorType: error.type } : {},
+            ...error.status !== void 0 ? { status: error.status } : {},
+            ...error.hint ? { hint: error.hint } : {},
+            ...payload?.credential?.source ? { payer: payload.credential.source } : {}
+          }
+        });
+      } catch {
+      }
+    });
+  }
+}
 
 // src/index.ts
 init_constants();
@@ -5448,6 +5457,7 @@ function createRouterFromEnv(options) {
   DEFAULT_SOLANA_FACILITATOR_URL,
   DEFAULT_TEMPO_RPC_URL,
   HttpError,
+  RouteDefinitionError,
   RouterConfigError,
   SOLANA_MAINNET_NETWORK,
   TEMPO_USDC_ADDRESS,