@agentcash/router 1.7.0 → 1.8.0

package/dist/index.d.cts

@@ -58,13 +58,13 @@ interface PluginContext {
     setVerifiedWallet(address: string): void;
 }
 interface PaymentEvent {
-    protocol: 'x402' | 'mpp';
+    protocol: ProtocolType;
     payer: string;
     amount: string;
     network: string;
 }
 interface SettlementEvent {
-    protocol: 'x402' | 'mpp';
+    protocol: ProtocolType;
     payer: string;
     transaction: string;
     network: string;
@@ -188,7 +188,7 @@ interface X402AcceptBase {
     extra?: Record<string, unknown>;
 }
 interface X402AcceptConfig extends X402AcceptBase {
-    /** `'exact'` for fixed-price one-shot payments; `'upto'` for settle-≤-cap (required for `.paid({ dynamic: true })` on x402). @default 'exact' */
+    /** `'exact'` for fixed-price one-shot payments; `'upto'` for settle-≤-cap (required for `.upTo()` routes). @default 'exact' */
     scheme?: string;
     /** Per-accept payee override. Function form receives the request and parsed body for dynamic recipient routing. Falls back to `RouterConfig.payeeAddress`. */
     payTo?: PayToConfig;
@@ -212,14 +212,29 @@ interface PaidOptions {
     protocols?: ProtocolType[];
     maxPrice?: string;
     minPrice?: string;
-    /** Override the payment recipient. String for static, function for dynamic (receives the Request). */
+    /** Override the payment recipient. String for static, function for body-derived (receives the Request). */
     payTo?: PayToConfig;
     /** Override MPP protocol metadata in x-payment-info discovery. */
     mpp?: MppProtocolInfo;
-    /** Handler-driven dynamic pricing: handler calls `charge()` per tick, total billed is `tickCost × calls` capped at `maxPrice`. Requires `maxPrice`. Incompatible with tiered pricing. On x402 needs an `upto` accept; on MPP needs `RouterConfig.mpp.session`. */
-    dynamic?: boolean;
-    /** Per-tick cost (positive decimal-dollar string). Required for `.paid({ dynamic: true })`. Also the voucher-headroom granularity for MPP sessions. */
-    tickCost?: string;
+}
+type PaidArg = (PaidOptions & {
+    price: string;
+}) | (PaidOptions & {
+    field: string;
+    tiers: Record<string, TierConfig>;
+    default?: string;
+});
+interface UpToOptions extends Omit<PaidOptions, 'maxPrice'> {
+    /** Cap on total billed amount; handler-accumulated `charge(amount)` calls cannot exceed this. */
+    maxPrice: string;
+    /** Cosmetic unit label for 402 challenges / UIs. Does not affect billing. */
+    unitType?: string;
+}
+interface MeteredOptions extends Omit<PaidOptions, 'maxPrice'> {
+    /** Per-tick cost (positive decimal-dollar string). On `.handler()` bills exactly this per request; on `.stream()` is the voucher-headroom granularity. */
+    tickCost: string;
+    /** Cap on total billed amount (streaming only — request-mode bills exactly `tickCost`). */
+    maxPrice: string;
     /** Cosmetic unit label for 402 challenges / UIs (e.g. `'token'`, `'byte'`). Does not affect billing. */
     unitType?: string;
 }
@@ -267,6 +282,7 @@ interface SettlementLifecycle<TBody = unknown> {
     onSettlementError?: (ctx: SettlementErrorContext<TBody>) => void | Promise<void>;
 }
 type ChargeFn = () => Promise<void>;
+type UptoChargeFn = (amount: string) => Promise<void>;
 interface HandlerContext<TBody = undefined, TQuery = undefined> {
     body: TBody;
     query: TQuery;
@@ -279,10 +295,14 @@ interface HandlerContext<TBody = undefined, TQuery = undefined> {
     alert: AlertFn;
     setVerifiedWallet: (addr: string) => void;
 }
-/** Handler context for streaming `.paid({ dynamic: true })` handlers (async generators). Call `charge()` once per billable unit. */
+/** Handler context for streaming `.metered()` handlers (async generators). Call `charge()` once per billable unit. */
 interface StreamingHandlerContext<TBody = undefined, TQuery = undefined> extends HandlerContext<TBody, TQuery> {
     charge: ChargeFn;
 }
+/** Handler context for `.upTo()` routes (x402-only). Call `charge(amount)` one or more times; the request settles for the accumulated total capped at `maxPrice`. */
+interface UptoHandlerContext<TBody = undefined, TQuery = undefined> extends HandlerContext<TBody, TQuery> {
+    charge: UptoChargeFn;
+}
 type OveragePolicy = 'same-rate' | 'increased-rate' | 'hard-stop';
 type QuotaLevel = 'healthy' | 'warn' | 'critical';
 interface QuotaInfo {
@@ -316,9 +336,9 @@ interface RouteEntry {
      */
     siwxEnabled?: boolean;
     pricing?: PricingConfig;
-    /** When true the route is dynamic-priced; bills `tickCost` per request (request-mode) or per `charge()` call (streaming). */
-    dynamicPrice?: boolean;
-    /** True iff handler is an async generator. Streaming handlers settle per-tick over SSE; non-streaming dynamic handlers bill exactly `tickCost` per request. Set by the builder at `.handler(fn)` time. */
+    /** `'exact'` settles a fixed price once; `'upto'` (x402-only) settles the handler-accumulated `charge(amount)` total capped at `maxPrice`; `'metered'` (MPP-only) bills per `tickCost`. */
+    billing: 'exact' | 'upto' | 'metered';
+    /** True iff handler is an async generator. Streaming handlers settle per-tick over SSE; non-streaming metered handlers bill exactly `tickCost` per request. Set by the builder at `.handler(fn)` time. */
     streaming?: boolean;
     protocols: ProtocolType[];
     bodySchema?: ZodType;
@@ -340,7 +360,7 @@ interface RouteEntry {
     validateFn?: (body: unknown) => void | Promise<void>;
     settlement?: SettlementLifecycle;
     mppInfo?: MppProtocolInfo;
-    /** Per-tick cost (decimal-dollar). Required when `dynamicPrice` is true. */
+    /** Per-tick cost (decimal-dollar). Required when `metered` is true. */
     tickCost?: string;
     /** Cosmetic unit label for 402 challenges and client UIs. */
     unitType?: string;
@@ -369,7 +389,7 @@ interface RouterConfig {
     network?: string;
     /** x402 protocol settings. Omit to default to a single `exact`/USDC accept on `network` paid to `payeeAddress`, verified via the Coinbase default facilitator (requires `CDP_API_KEY_ID`/`CDP_API_KEY_SECRET`). */
     x402?: {
-        /** Explicit accepts list (scheme + network + asset). Overrides the auto-generated default. Add an `upto` accept here to enable `.paid({ dynamic: true })` on x402. */
+        /** Explicit accepts list (scheme + network + asset). Overrides the auto-generated default. Add an `upto` accept here to enable `.upTo()` routes. */
         accepts?: X402AcceptConfig[];
         /** Per-chain facilitator overrides (`evm`/`solana`). Defaults to the Coinbase facilitator on EVM; set `solana` to accept Solana payments. */
         facilitators?: X402FacilitatorsConfig;
@@ -397,7 +417,7 @@ interface RouterConfig {
         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. */
         feePayerKey?: string;
-        /** Enables MPP payment-channel sessions for `.paid({ dynamic: true })` routes (registers both request and SSE session middleware). Also requires `mpp.operatorKey`. */
+        /** 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;
@@ -438,6 +458,7 @@ type MppxMiddlewareResponse<T extends Transport.AnyTransport> = {
     withReceipt: Transport.WithReceipt<T>;
 };
 type MppxMiddleware<TOptions, T extends Transport.AnyTransport> = (options: TOptions) => (input: Request) => Promise<MppxMiddlewareResponse<T>>;
+
 interface RouterDeps {
     x402Server: X402Server | null;
     initPromise: Promise<void>;
@@ -472,123 +493,99 @@ interface RouterDeps {
     tempoClient?: viem.Client | null;
 }
 
-/** @deprecated alias kept for downstream consumers; use `RouterDeps`. */
-type OrchestrateDeps = RouterDeps;
-
 type True = true;
 type False = false;
+declare const ROUTE_ERROR: unique symbol;
+interface RouteError<M extends string> {
+    readonly [ROUTE_ERROR]: M;
+}
 type InputTypeFor<TBody, TQuery> = [TBody] extends [undefined] ? [TQuery] extends [undefined] ? never : TQuery : TBody;
 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>;
-type HandlerArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean> = HasAuth extends true ? [NeedsBody, HasBody] extends [true, false] ? {
-    __missing: 'Call .body(schema) — dynamic/tiered pricing requires a body schema to resolve the price against';
-} : RequestHandlerFn<TBody, TQuery> : {
-    __missing: 'Select an auth mode: .paid(pricing), .siwx(), .apiKey(resolver), or .unprotected()';
-};
-type StreamArg<TBody, TQuery, HasAuth extends boolean, NeedsBody extends boolean, HasBody extends boolean, IsDynamic extends boolean> = HasAuth extends true ? IsDynamic extends true ? [NeedsBody, HasBody] extends [true, false] ? {
-    __missing: 'Call .body(schema) — dynamic pricing requires a body schema to resolve the price against';
-} : StreamingHandlerFn<TBody, TQuery> : {
-    __missing: 'Streaming handlers require .paid({ dynamic: true, tickCost, unitType, maxPrice }) — static/free routes cannot meter per-chunk billing';
-} : {
-    __missing: 'Select an auth mode: .paid({ dynamic: true, ... }) — streaming requires handler-driven dynamic pricing';
-};
-declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = undefined, HasAuth extends boolean = false, NeedsBody extends boolean = false, HasBody extends boolean = false, IsDynamic extends boolean = false> {
-    /** @internal */ readonly _key: string;
-    /** @internal */ readonly _registry: RouteRegistry;
-    /** @internal */ readonly _deps: OrchestrateDeps;
-    /** @internal */ _authMode: AuthMode | null;
-    /** @internal */ _pricing: PricingConfig | undefined;
-    /** @internal */ _siwxEnabled: boolean;
-    /** @internal */ _protocols: ProtocolType[];
-    /** @internal */ _maxPrice: string | undefined;
-    /** @internal */ _minPrice: string | undefined;
-    /** @internal */ _dynamicPrice: boolean;
-    /** @internal */ _tickCost: string | undefined;
-    /** @internal */ _unitType: string | undefined;
-    /** @internal */ _payTo: PayToConfig | undefined;
-    /** @internal */ _bodySchema: ZodType | undefined;
-    /** @internal */ _querySchema: ZodType | undefined;
-    /** @internal */ _outputSchema: ZodType | undefined;
-    /** @internal */ _inputExample: JsonObject | undefined;
-    /** @internal */ _hasInputExample: boolean;
-    /** @internal */ _outputExample: JsonValue | undefined;
-    /** @internal */ _hasOutputExample: boolean;
-    /** @internal */ _description: string | undefined;
-    /** @internal */ _path: string | undefined;
-    /** @internal */ _method: 'GET' | 'POST' | 'DELETE' | 'PUT' | 'PATCH';
-    /** @internal */ _apiKeyResolver: ((key: string) => unknown | Promise<unknown>) | undefined;
-    /** @internal */ _providerName: string | undefined;
-    /** @internal */ _providerConfig: ProviderConfig | undefined;
-    /** @internal */ _validateFn: ((body: TBody) => void | Promise<void>) | undefined;
-    /** @internal */ _settlement: SettlementLifecycle<TBody> | undefined;
-    /** @internal */ _mppInfo: MppProtocolInfo | undefined;
-    constructor(key: string, registry: RouteRegistry, deps: OrchestrateDeps);
+/** 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'>;
+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'> {
+    #private;
+    constructor(key: string, registry: RouteRegistry, deps: RouterDeps, defaults?: RouteBuilderDefaults);
     private fork;
     /**
-     * Charge a fixed price per request, denominated in USDC as a decimal string.
+     * Fixed-price string sugar: `paid('0.01')` charges 0.01 USDC per request.
      *
      * @example
      * ```ts
      * router.route('search').paid('0.01').handler(handler);
      * ```
      */
-    paid(pricing: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, IsDynamic>;
+    paid(price: string, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, 'none'>;
     /**
-     * Configure handler-driven dynamic pricing — each tick costs `tickCost` USDC,
-     * capped at `maxPrice`. Pair with `.handler()` for one-tick-per-request
-     * billing, or with `.stream()` for per-yield metering.
+     * Compute the price from the parsed body before issuing the 402 challenge.
+     * Throw an `HttpError` from the pricing function to reject the request
+     * before payment is requested. Requires `.body(schema)`.
      *
      * @example
      * ```ts
-     * router
-     *   .route('llm/stream')
-     *   .paid({ dynamic: true, tickCost: '0.0001', unitType: 'token', maxPrice: '0.05' })
-     *   .stream(async function* ({ charge }) { await charge(); yield 'hi'; });
+     * router.route('llm')
+     *   .paid((body) => `${body.tokens * 0.0001}`, { maxPrice: '5.00' })
+     *   .body(schema)
+     *   .handler(handler);
      * ```
      */
-    paid(options: PaidOptions & {
-        dynamic: true;
-        maxPrice: string;
-    }): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, True>;
+    paid<TBodyIn>(fn: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, 'none'>;
     /**
-     * Compute the price from the parsed body before issuing the 402 challenge.
-     * Throw an `HttpError` from the pricing function to reject the request before
-     * payment is requested.
+     * Options-object form of fixed or body-derived pricing. Pass exactly one of:
+     *
+     * - `{ 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`) live
+     * alongside the pricing shape. For handler-computed billing use `.upTo()`;
+     * for per-tick billing use `.metered()`.
      *
      * @example
      * ```ts
-     * router
-     *   .route('llm')
-     *   .paid((body) => `${body.tokens * 0.0001}`, { maxPrice: '5.00' })
-     *   .body(schema)
-     *   .handler(handler);
+     * router.route('upload')
+     *   .paid({ field: 'size', tiers: { sm: { price: '0.01' }, lg: { price: '0.10' } } })
+     *   .body(schema).handler(handler);
      * ```
      */
-    paid<TBodyIn>(pricing: (body: TBodyIn) => string | Promise<string>, options?: PaidOptions & {
-        maxPrice?: string;
-    }): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, IsDynamic>;
+    paid<T extends PaidArg>(arg: T): RouteBuilder<TBody, TQuery, TOutput, True, T extends {
+        tiers: Record<string, TierConfig>;
+    } ? True : False, HasBody, 'none'>;
     /**
-     * Select a price tier from `body[field]`, optionally falling back to the
-     * `default` tier when the value is missing. The 402 challenge advertises the
-     * highest tier price.
+     * 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('upload')
-     *   .paid({ field: 'size', tiers: { sm: { price: '0.01' }, lg: { price: '0.10' } } })
+     * router.route('llm')
+     *   .upTo('0.05')
      *   .body(schema)
-     *   .handler(handler);
+     *   .handler(async ({ body, charge }) => { await charge('0.001'); ... });
+     * ```
+     */
+    upTo(arg: string | UpToOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, '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'; });
      * ```
      */
-    paid(pricing: {
-        field: string;
-        tiers: Record<string, {
-            price: string;
-            label?: string;
-        }>;
-        default?: string;
-    }, options?: PaidOptions): RouteBuilder<TBody, TQuery, TOutput, True, True, HasBody, IsDynamic>;
+    metered(options: MeteredOptions): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, 'metered'>;
+    private applyPaid;
     /**
      * Require Sign-In-with-X wallet identity on this route — clients prove
      * control of a wallet via a signed challenge. Combine with `.paid()` to gate
@@ -599,7 +596,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * router.route('profile').siwx().handler(async ({ wallet }) => getProfile(wallet));
      * ```
      */
-    siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, IsDynamic>;
+    siwx(): RouteBuilder<TBody, TQuery, TOutput, True, False, HasBody, Bill>;
     /**
      * Require an `X-API-Key` header (or `Authorization: Bearer <key>`); the
      * resolver returns the account record, or `null` for 401. Composes with
@@ -613,7 +610,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, IsDynamic>;
+    apiKey(resolver: (key: string) => unknown | Promise<unknown>): RouteBuilder<TBody, TQuery, TOutput, True, NeedsBody, HasBody, Bill>;
     /**
      * Mark the route as public — no auth, no payment, no SIWX. The handler
      * receives `null` for `wallet`, `payment`, and `account`.
@@ -623,7 +620,7 @@ 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, IsDynamic>;
+    unprotected(): RouteBuilder<TBody, TQuery, TOutput, True, False, 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
@@ -649,7 +646,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, IsDynamic>;
+    body<T>(schema: ZodType<T>): RouteBuilder<T, TQuery, TOutput, HasAuth, 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
@@ -661,7 +658,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, IsDynamic>;
+    query<T>(schema: ZodType<T>): RouteBuilder<TBody, T, TOutput, HasAuth, 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()`
@@ -674,7 +671,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, IsDynamic>;
+    output<T>(schema: ZodType<T>): RouteBuilder<TBody, TQuery, T, HasAuth, NeedsBody, HasBody, Bill>;
     /**
      * Attach an example of the request body or query for discovery output,
      * validated against the registered schema at registration.
@@ -684,7 +681,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, IsDynamic>;
+    inputExample(example: InputTypeFor<TBody, TQuery> & JsonObject): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
     /**
      * Attach an example response for discovery output, validated against the
      * registered output schema at registration.
@@ -694,7 +691,7 @@ 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, IsDynamic>;
+    outputExample(example: TOutput & JsonValue): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
     /**
      * Set a human-readable summary of the route. Surfaces in OpenAPI,
      * `well-known`, and `llms.txt` discovery output.
@@ -739,7 +736,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * });
      * ```
      */
-    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, IsDynamic>;
+    validate(fn: (body: TBody) => void | Promise<void>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, Bill>;
     /**
      * Hook into the settlement lifecycle. `beforeSettle` runs after the handler
      * succeeds but before on-chain settlement and can cancel the charge;
@@ -753,7 +750,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      * });
      * ```
      */
-    settlement(lifecycle: SettlementLifecycle<TBody>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, NeedsBody, HasBody, IsDynamic>;
+    settlement(lifecycle: SettlementLifecycle<TBody>): RouteBuilder<TBody, TQuery, TOutput, HasAuth, 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
@@ -768,17 +765,17 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   .handler(async ({ body, wallet }) => searchService(body, wallet));
      * ```
      */
-    handler(fn: HandlerArg<TBody, TQuery, HasAuth, NeedsBody, HasBody>): (request: NextRequest) => Promise<Response>;
+    handler(fn: HandlerArg<TBody, TQuery, HasAuth, 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
-     * to `maxPrice`; requires `.paid({ dynamic: true, ... })` and MPP session mode.
+     * to `maxPrice`; requires `.metered({ ... })` and MPP session mode.
      *
      * @example
      * ```ts
      * export const POST = router
      *   .route('llm/stream')
-     *   .paid({ dynamic: true, tickCost: '0.0001', unitType: 'token', maxPrice: '0.05' })
+     *   .metered({ tickCost: '0.0001', maxPrice: '0.05', unitType: 'token' })
      *   .body(schema)
      *   .stream(async function* ({ body, charge }) {
      *     for await (const token of streamLLM(body.prompt)) {
@@ -788,7 +785,7 @@ declare class RouteBuilder<TBody = undefined, TQuery = undefined, TOutput = unde
      *   });
      * ```
      */
-    stream(fn: StreamArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, IsDynamic>): (request: NextRequest) => Promise<Response>;
+    stream(fn: StreamArg<TBody, TQuery, HasAuth, NeedsBody, HasBody, Bill>): (request: NextRequest) => Promise<Response>;
     private register;
 }