@agentcash/router 1.12.0 → 1.13.0

package/dist/index.d.cts

@@ -128,6 +128,20 @@ declare class HttpError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
 }
+/**
+ * Thrown when a route definition is invalid — an impossible builder
+ * combination, a malformed price, or a route that needs config the router
+ * wasn't given. Fires at module-import time (when the route file is first
+ * loaded), so Next.js surfaces it as a build/dev error, never as a response.
+ * The registration-time sibling of {@link RouterConfigError}.
+ */
+declare class RouteDefinitionError extends Error {
+    /** Registry key of the offending route. */
+    readonly route: string;
+    constructor(
+    /** Registry key of the offending route. */
+    route: string, detail: string);
+}
 type AlertLevel = 'info' | 'warn' | 'error' | 'critical';
 interface AlertEvent {
     level: AlertLevel;
@@ -419,6 +433,23 @@ interface DiscoveryConfig {
     /** Override the OpenAPI `servers` URL. Defaults to `RouterConfig.baseUrl`. Use when the public API hostname differs from the payment realm URL. */
     serverUrl?: string;
 }
+/** Sponsor fee-budget ceilings for fee-sponsored Tempo transactions. Structural mirror of mppx's `FeePayer.Policy`, all fields optional. */
+interface MppFeePayerPolicy {
+    maxGas?: bigint;
+    maxFeePerGas?: bigint;
+    maxPriorityFeePerGas?: bigint;
+    maxTotalFee?: bigint;
+    maxValidityWindowSeconds?: number;
+}
+/** Server-owned automatic settlement cadence for MPP session channels. Structural mirror of mppx's `SettlementSchedule`. */
+interface MppSettlementSchedule {
+    /** Settle after this many additional paid units since the previous settlement. */
+    units?: number;
+    /** Settle after this much additional billed amount (decimal-dollar string) since the previous settlement. */
+    amount?: string;
+    /** Settle after this many milliseconds since the previous settlement. */
+    intervalMs?: number;
+}
 interface RouterConfig {
     /** Default payee for paid routes — populates `payTo` on the auto-generated x402 `exact` accept and acts as the MPP `recipient` fallback. Override per-protocol via `x402.accepts[i].payTo` / `mpp.recipient`, or per-route via the `payTo` option on `.paid()` / `.upTo()` / `.metered()`. */
     payeeAddress?: string;
@@ -454,19 +485,23 @@ interface RouterConfig {
         rpcUrl?: string;
         /** Hex private key. Signs channel close/settle; required for `session`. Address MUST equal `recipient`/payee — mppx asserts sender===payee on settle. Validated at init. */
         operatorKey?: string;
-        /** Hex private key. Sponsors gas for client channel open/topUp. MUST resolve to a different address than `operatorKey` — Tempo rejects sender===feePayer. Validated at init. Omit to make clients pay their own gas. */
+        /** Hex private key. Sponsors gas for client channel open/topUp. MUST resolve to a different address than `operatorKey` — Tempo rejects sender===feePayer. Validated at init. Omit to make clients pay their own gas. The account must hold the Tempo fee token (pathUSD) to pay sponsored gas. */
         feePayerKey?: string;
+        /** Partial override of mppx's sponsor fee-budget ceilings for fee-sponsored Tempo transactions (charge co-signs and session open/topUp/close). Raise `maxTotalFee` alongside `maxGas`/`maxFeePerGas`. Omit for mppx's per-chain defaults. */
+        feePayerPolicy?: MppFeePayerPolicy;
         /** Enables MPP payment-channel sessions for `.metered()` routes (registers both request and SSE session middleware). Also requires `mpp.operatorKey`. */
         session?: {
             /** Suggested deposit on the 402 challenge = `tickCost × depositMultiplier` USDC. Route `maxPrice` overrides. @default 10 */
             depositMultiplier?: number;
+            /** Server-owned automatic settlement cadence for session channels. Omitted: channels settle only on client close. Thresholds compose (whichever trips first). */
+            settlementSchedule?: MppSettlementSchedule;
         };
     };
     /** Payment protocols to accept on paid routes unless overridden per route. @default ['x402'] */
     protocols?: ProtocolType[];
     /** When true, `.route('key')` is rejected (use `.route({ path })`) and custom `key !== path` is rejected. Prevents discovery/openapi drift. */
     strictRoutes?: boolean;
-    /** Static metadata for auto-generated discovery surfaces — `/.well-known/x402`, OpenAPI (`/api/openapi`), and `/llms.txt`. */
+    /** Static metadata for auto-generated discovery surfaces — `/openapi.json` (`.openapi()`) and `/llms.txt` (`.llmsTxt()`). Also feeds the deprecated `.wellKnown()` handler. */
     discovery: DiscoveryConfig;
 }
 
@@ -543,14 +578,27 @@ type InputTypeFor<TBody, TQuery> = [TBody] extends [undefined] ? [TQuery] extend
 type RequestHandlerFn<TBody, TQuery> = (ctx: HandlerContext<TBody, TQuery>) => Promise<unknown>;
 type UptoHandlerFn<TBody, TQuery> = (ctx: UptoHandlerContext<TBody, TQuery>) => Promise<unknown>;
 type StreamingHandlerFn<TBody, TQuery> = (ctx: StreamingHandlerContext<TBody, TQuery>) => AsyncIterable<unknown>;
-/** Discriminator threaded through the builder so `.handler()` / `.stream()` can pick the right handler shape. */
-type BillingMode = 'none' | 'upto' | 'metered';
-type HandlerArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean, Bill extends BillingMode> = HasAuth extends true ? [NeedsBody, HasBody] extends [true, false] ? RouteError<'Call .body(schema) — body-derived/tiered pricing reads the parsed body'> : Bill extends 'upto' ? UptoHandlerFn<TBody, TQuery> : RequestHandlerFn<TBody, TQuery> : RouteError<'Pick an auth mode first: .paid(...), .upTo(...), .metered(...), .siwx(), .apiKey(...), or .unprotected()'>;
-type StreamArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean, Bill extends BillingMode> = HasAuth extends true ? Bill extends 'metered' ? [NeedsBody, HasBody] extends [true, false] ? RouteError<'Call .body(schema) — metered pricing reads the parsed body'> : StreamingHandlerFn<TBody, TQuery> : Bill extends 'upto' ? RouteError<'Streaming is not supported on .upTo() — use .metered() on MPP for per-yield billing'> : RouteError<'Streaming requires .metered({ tickCost, maxPrice }) — static/free routes cannot meter per-chunk billing'> : RouteError<'Pick an auth mode first: .metered({ ... }) — streaming requires metered pricing'>;
+/**
+ * Pricing-mode discriminator threaded through the builder. `'none'` until a
+ * pricing method is chained; then `'exact'` (`.paid()`), `'upto'`, or
+ * `'metered'`. Gates repeat pricing calls and picks the handler shape.
+ */
+type BillingMode = 'none' | 'exact' | 'upto' | 'metered';
+/**
+ * Identity-mode discriminator threaded through the builder. `'none'` until an
+ * identity method is chained; then `'siwx'`, `'apiKey'`, or `'open'`
+ * (`.unprotected()`). Gates the mutually-exclusive combinations at compile
+ * time, mirroring the registration-time throws.
+ */
+type IdentMode = 'none' | 'siwx' | 'apiKey' | 'open';
+/** Resolves to `TSelf` when a pricing method may be chained, else a `RouteError`. Mirrors the runtime guards in `applyPaid`. */
+type PricingGate<TSelf, Ident extends IdentMode, Bill extends BillingMode, M extends string> = Ident extends 'open' ? RouteError<`Cannot combine .unprotected() and .${M}() on the same route`> : Bill extends 'none' ? TSelf : RouteError<'Cannot combine .paid(), .upTo(), and .metered() — pick one pricing mode'>;
+type HandlerArg<TBody, TQuery, Ident extends IdentMode, NeedsBody extends boolean, HasBody extends boolean, Bill extends BillingMode> = [Ident, Bill] extends ['none', 'none'] ? RouteError<'Pick an auth mode first: .paid(...), .upTo(...), .metered(...), .siwx(), .apiKey(...), or .unprotected()'> : [NeedsBody, HasBody] extends [true, false] ? RouteError<'Call .body(schema) — body-derived/tiered pricing reads the parsed body'> : Bill extends 'upto' ? UptoHandlerFn<TBody, TQuery> : RequestHandlerFn<TBody, TQuery>;
+type StreamArg<TBody, TQuery, Ident extends IdentMode, NeedsBody extends boolean, HasBody extends boolean, Bill extends BillingMode> = [Ident, Bill] extends ['none', 'none'] ? RouteError<'Pick an auth mode first: .metered({ ... }) — streaming requires metered pricing'> : Bill extends 'metered' ? [NeedsBody, HasBody] extends [true, false] ? RouteError<'Call .body(schema) — metered pricing reads the parsed body'> : StreamingHandlerFn<TBody, TQuery> : Bill extends 'upto' ? RouteError<'Streaming is not supported on .upTo() — use .metered() on MPP for per-yield billing'> : RouteError<'Streaming requires .metered({ tickCost, maxPrice }) — static/free routes cannot meter per-chunk billing'>;
 interface RouteBuilderDefaults {
     protocols?: ProtocolType[];
 }
-declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false, Bill extends BillingMode = 'none'> {
+declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = undefined, Ident extends IdentMode = 'none', NeedsBody extends boolean = false, HasBody extends boolean = false, Bill extends BillingMode = 'none'> {
     #private;
     constructor(key: string, registry: RouteRegistry, deps: RouterDeps, defaults?: RouteBuilderDefaults);
     private fork;
@@ -562,7 +610,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * router.route('search').paid('0.01').handler(handler);
      * ```
      */
-    paid(price: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, 'none'>;
+    paid(this: PricingGate<RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>, Ident, Bill, 'paid'>, price: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, Ident, False, HasBody, 'exact'>;
     /**
      * Compute the price from the parsed body before issuing the 402 challenge.
      * Throw an `HttpError` from the pricing function to reject the request
@@ -576,7 +624,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(handler);
      * ```
      */
-    paid<TBodyIn>(fn: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, 'none'>;
+    paid<TBodyIn>(this: PricingGate<RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>, Ident, Bill, 'paid'>, fn: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, Ident, True, HasBody, 'exact'>;
     /**
      * Options-object form of fixed or body-derived pricing. Pass exactly one of:
      *
@@ -595,9 +643,9 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .body(schema).handler(handler);
      * ```
      */
-    paid<T extends PaidArg>(arg: T): RouteBuilder<TBody, TQuery, TOutput, True, T extends {
+    paid<T extends PaidArg>(this: PricingGate<RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>, Ident, Bill, 'paid'>, arg: T): RouteBuilder<TBody, TQuery, TOutput, Ident, T extends {
         tiers: Record<string, TierConfig>;
-    } ? True : False, HasBody, 'none'>;
+    } ? True : False, HasBody, 'exact'>;
     /**
      * x402-only handler-computed billing. The handler receives `charge(amount)`
      * and the request settles once for the accumulated total, capped at
@@ -612,7 +660,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async ({ body, charge }) => { await charge('0.001'); ... });
      * ```
      */
-    upTo(arg: string | UpToOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, 'upto'>;
+    upTo(this: PricingGate<RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>, Ident, Bill, 'upTo'>, arg: string | UpToOptions): RouteBuilder<TBody, TQuery, TOutput, Ident, False, HasBody, 'upto'>;
     /**
      * MPP-only per-tick billing. `.handler()` bills exactly `tickCost`;
      * `.stream()` calls `charge()` (no-arg) per yield, settling per tick up to
@@ -625,7 +673,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .stream(async function* ({ charge }) { await charge(); yield 'hi'; });
      * ```
      */
-    metered(options: MeteredOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, 'metered'>;
+    metered(this: Ident extends 'siwx' ? RouteError<'Cannot combine .siwx() and .metered() — per-tick MPP billing has no entitlement model'> : PricingGate<RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>, Ident, Bill, 'metered'>, options: MeteredOptions): RouteBuilder<TBody, TQuery, TOutput, Ident, False, HasBody, 'metered'>;
     private applyPaid;
     /**
      * Require Sign-In-with-X wallet identity on this route — clients prove
@@ -641,7 +689,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * router.route('inbox').paid('0.01').siwx().handler(async ({ wallet }) => getInbox(wallet));
      * ```
      */
-    siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, Bill>;
+    siwx(this: Ident extends 'open' ? RouteError<'Cannot combine .unprotected() and .siwx() on the same route'> : Ident extends 'apiKey' ? RouteError<'Combining .siwx() and .apiKey() is not supported on the same route'> : Bill extends 'metered' ? RouteError<'Cannot combine .metered() and .siwx() — per-tick MPP billing has no entitlement model'> : RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>): RouteBuilder<TBody, TQuery, TOutput, 'siwx', NeedsBody, HasBody, Bill>;
     /**
      * Require an `X-API-Key` header (or `Authorization: Bearer <key>`); the
      * resolver returns the account record, or `null` for 401. Composes with
@@ -655,7 +703,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async ({ account }) => db.user.list(account.orgId));
      * ```
      */
-    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, TOutput, True, NeedsBody, HasBody, Bill>;
+    apiKey(this: Ident extends 'open' ? RouteError<'Cannot combine .unprotected() and .apiKey() on the same route'> : Ident extends 'siwx' ? RouteError<'Combining .apiKey() and .siwx() is not supported on the same route'> : RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>, resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, TOutput, 'apiKey', NeedsBody, HasBody, Bill>;
     /**
      * Mark the route as public — no auth, no payment, no SIWX. The handler
      * receives `null` for `wallet`, `payment`, and `account`.
@@ -665,11 +713,11 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * router.route('health').unprotected().handler(async () => ({ status: 'ok' }));
      * ```
      */
-    unprotected(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, Bill>;
+    unprotected(this: Bill extends 'none' ? Ident extends 'siwx' ? RouteError<'Cannot combine .unprotected() and .siwx() on the same route'> : Ident extends 'apiKey' ? RouteError<'Cannot combine .unprotected() and .apiKey() on the same route'> : RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill> : RouteError<'Cannot combine .unprotected() and a pricing mode on the same route'>): RouteBuilder<TBody, TQuery, TOutput, 'open', NeedsBody, HasBody, Bill>;
     /**
      * 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
@@ -691,7 +739,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async ({ body }) => search(body.query));
      * ```
      */
-    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput, HasAuth, NeedsBody, True, Bill>;
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput, Ident, NeedsBody, True, Bill>;
     /**
      * Declare a query-string Zod schema and switch the route to `GET`. Parsed
      * query is typed as `ctx.query` in the handler. Use `.inputExample()` to
@@ -703,7 +751,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async ({ query }) => getById(query.id));
      * ```
      */
-    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput, Ident, NeedsBody, HasBody, Bill>;
     /**
      * Declare the response output's Zod schema for OpenAPI generation. The
      * runtime does not validate handler return values — use Zod's `.parse()`
@@ -716,7 +764,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async () => ({ result: 'ok' }));
      * ```
      */
-    output<T>(schema: ZodType<T>): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody, Bill>;
+    output<T>(schema: ZodType<T>): RouteBuilder<TBody, TQuery, T, Ident, NeedsBody, HasBody, Bill>;
     /**
      * Attach an example of the request body or query for discovery output,
      * validated against the registered schema at registration.
@@ -726,7 +774,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * .body(searchSchema).inputExample({ query: 'cats' });
      * ```
      */
-    inputExample(example: InputTypeFor<TBody, TQuery> & JsonObject): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    inputExample(example: InputTypeFor<TBody, TQuery> & JsonObject): RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>;
     /**
      * Attach an example response for discovery output, validated against the
      * registered output schema at registration.
@@ -736,10 +784,10 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * .output(resultSchema).outputExample({ result: 'ok' });
      * ```
      */
-    outputExample(example: TOutput & JsonValue): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    outputExample(example: TOutput & JsonValue): RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>;
     /**
-     * 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
@@ -781,7 +829,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * });
      * ```
      */
-    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>;
     /**
      * Override MPP protocol metadata and per-route MPP settlement options.
      * Merges with any `mpp` options passed to `.paid()`. Use on auto-priced routes
@@ -795,7 +843,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(handler);
      * ```
      */
-    mpp(info: MppProtocolInfo): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    mpp(info: MppProtocolInfo): RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>;
     /**
      * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
      * succeeds but before on-chain settlement and can cancel the charge;
@@ -809,7 +857,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * });
      * ```
      */
-    settlement(lifecycle: SettlementLifecycle<TBody>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
+    settlement(lifecycle: SettlementLifecycle<TBody>): RouteBuilder<TBody, TQuery, TOutput, Ident, NeedsBody, HasBody, Bill>;
     /**
      * Register the request handler and return the Next.js route function. The
      * handler receives a typed context and may return a value (serialized to
@@ -824,7 +872,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async ({ body, wallet }) => searchService(body, wallet));
      * ```
      */
-    handler(fn: HandlerArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, Bill>): (request: NextRequest) => Promise<Response>;
+    handler(fn: HandlerArg<TBody, TQuery, Ident, NeedsBody, HasBody, Bill>): (request: NextRequest) => Promise<Response>;
     /**
      * Register a streaming handler (`async function*`) and return the Next.js
      * route function. Each `charge()` call bills one tick (`tickCost` USDC) up
@@ -844,7 +892,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   });
      * ```
      */
-    stream(fn: StreamArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, Bill>): (request: NextRequest) => Promise<Response>;
+    stream(fn: StreamArg<TBody, TQuery, Ident, NeedsBody, HasBody, Bill>): (request: NextRequest) => Promise<Response>;
     private register;
 }
 
@@ -861,7 +909,7 @@ interface RouterConfigIssue {
 interface CreateRouterFromEnvOptions<TPrices extends Record<string, string> = Record<never, string>> {
     /** Defaults to `process.env`. Pass an explicit object in tests. */
     env?: Record<string, string | undefined>;
-    /** Discovery title. Shown in `.well-known/agentcash`, OpenAPI, and `/llms.txt`. */
+    /** Discovery title. Shown in `/openapi.json` and `/llms.txt`. */
     title: string;
     /** Discovery description. */
     description: string;
@@ -871,7 +919,7 @@ interface CreateRouterFromEnvOptions<TPrices extends Record<string, string> = Re
     version?: string;
     /** Optional contact metadata published in discovery. */
     contact?: DiscoveryConfig['contact'];
-    /** Optional ownership proofs published in `.well-known/agentcash`. */
+    /** Optional ownership proofs published in `/openapi.json` (and the deprecated `/.well-known/x402`). */
     ownershipProofs?: string[];
     /** Per-route HTTP method hint visibility. */
     methodHints?: DiscoveryConfig['methodHints'];
@@ -937,10 +985,19 @@ interface MonitorEntry {
     critical?: number;
 }
 interface ServiceRouter<TPriceKeys extends string = never> {
-    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, undefined, true, false, false> : RouteBuilder<undefined, undefined, undefined, false, false, false>;
+    route<K extends string>(keyOrDefinition: K | RouteDefinition<K>): [K] extends [TPriceKeys] ? RouteBuilder<undefined, undefined, undefined, 'none', false, false, 'exact'> : RouteBuilder<undefined, undefined, undefined, 'none', false, false, 'none'>;
+    /**
+     * @deprecated The `/.well-known/x402` surface is no longer a recommended
+     * discovery location. The handler keeps working for legacy x402 clients,
+     * but new integrations should mount `.openapi()` (at `/openapi.json`) and
+     * `.llmsTxt()` (at `/llms.txt`) instead.
+     */
     wellKnown(): (request: NextRequest) => Promise<NextResponse>;
+    /** OpenAPI 3.1 discovery document. Mount at `GET /openapi.json`. */
     openapi(): (request: NextRequest) => Promise<NextResponse>;
+    /** Plain-text agent guidance. Mount at `GET /llms.txt`. */
     llmsTxt(): (request: NextRequest) => Promise<NextResponse>;
+    /** JSON 404 fallback with rediscovery links. Mount in a catch-all route. */
     notFound(): (request: NextRequest) => Promise<NextResponse>;
     monitors(): MonitorEntry[];
     registry: RouteRegistry;
@@ -970,4 +1027,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 CheckoutSessionContext, type CheckoutSessionFn, type CheckoutSessionResponse, type CreateRouterFromEnvOptions, DEFAULT_SOLANA_FACILITATOR_URL, DEFAULT_TEMPO_RPC_URL, type DiscoveryConfig, type HandlerContext, HttpError, type KvStore, type MppProtocolInfo, 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 MppProtocolInfo, type PaidOptions, type ProtocolType, RouteDefinitionError, 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 };